add docs for google secret rotation

[vivki]

Proposed changes

Checklist

Before sharing this pull request, I completed the following checklist:

• I read the Contributing guidelines
• My branch adheres to the Git conventions
• My content changes adhere to the F5 Technical Writing Style Guide
• If my changes involve potentially sensitive information¹, I have assessed the possible impact
• I have waited to ensure my changes pass tests, and addressed any discovered issues

Footnotes

1. Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩

[JTorreG]

approved with suggestions

[mjang]

a few more comments

[mjang]

Awaiting @tstraley 's approval before merging

[tstraley]

I'm thinking this is missing a step:

The user either needs to update their config to reference the new Version ID, or they need to update their alias to point at the new secret version, or we are assuming they are using latest here but that isn't clear.

Maybe we should be better about calling out all of these approaches here as options? I guess changing their config to a new Version ID doesn't also require "Reapply Configuration" but it definitely seems like a "manual" secret manager cert rotation method.

[vivki]

I think touching on the various scenarios is a good idea, which is why I left the above portion in:

"This [manual rotation] is useful in the following scenarios:

• New secret version: You've uploaded a new certificate and want NGINXaaS to use it right away.
• WIF or permissions fix: You've updated a WIF provider or granted Secret Manager permissions and want NGINXaaS to retry immediately."

I don't want to complicate the sequence with more steps, as the user may choose to Reapply Config/manually rotate intentionally having made no updates.

[valyria257]

nit (clarification on what's being updated):

Suggested change

	**Manual rotation** — When you need an immediate update, use **Reapply Configuration** in the console to refetch secrets right away. See [Rotate a Secret Manager certificate (manual)]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#rotate-a-secret-manager-certificate-manual" >}}).
	**Manual rotation** — When you need to update certificates immediately, use **Reapply Configuration** in the console to refetch secrets right away. See [Rotate a Secret Manager certificate (manual)]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#rotate-a-secret-manager-certificate-manual" >}}).

[valyria257]

Suggested change

	| Google Secret ID | The resource name of the secret in Secret Manager | The resource name must match the format `projects/$PROJECT_ID/secrets/$SECRET_ID/versions/$VERSION`, where `$VERSION` can be a specific version ID (for example, `3`) or the special version ID `latest`. |
	| Google Secret ID | The resource name of the secret in Secret Manager | The resource name must match the format `projects/$PROJECT_ID/secrets/$SECRET_ID/versions/$VERSION`, where `$VERSION` can be a specific version ID (for example, `3`), a custom alias, or the special version ID `latest`. |

[valyria257]

"Next scheduled sync" feels a bit like an internal detail. I think we should also clarify where the version ID is coming from. What about this instead:

Suggested change

	If your configuration uses `latest` as the version ID, NGINXaaS fetches the latest secret version on the next scheduled sync. When you add a new secret version in Secret Manager, the next sync picks it up and reloads NGINX.
	If you set the version ID of your secret to `latest`, NGINXaaS fetches the latest secret version. When you [add a new secret version in Secret Manager](https://docs.cloud.google.com/secret-manager/docs/add-secret-version#add-a-secret-version), NGINXaaS automatically picks up that version within 4 hours.

[valyria257]

similar comment:

Suggested change

	If your configuration uses a custom alias as the version ID, NGINXaaS fetches whichever version the alias points to on the next scheduled sync. When you update the alias to point to a different version in Secret Manager, the next sync applies that version.
	If you set the version ID of your secret to a custom alias, NGINXaaS fetches the secret version the alias points to. When you [update the alias to point to a different version in Secret Manager](https://docs.cloud.google.com/secret-manager/docs/assign-alias-to-secret-version), NGINXaaS automatically picks up that version within 4 hours.

[valyria257]

Suggested change

	NGINXaaS generates an event each time it fetches or fails to fetch a certificate or key from Secret Manager. Use these events to track successful rotations and diagnose access failures.
	NGINXaaS generates an event each time it fetches or fails to fetch a secret from Secret Manager. Use these events to track successful rotations and diagnose access failures.

[valyria257]

These steps only apply to the latest case (adding a new secret version instead of referencing a different one). Since we can include the Google instructions in line above, can we remove most of this?

Suggested change

	No configuration changes are required in either case.
	To ensure certificates are automatically rotated:
	1. Generate your new certificate and key.
	2. Follow Google's instructions to [add a new secret version in Secret Manager](https://docs.cloud.google.com/secret-manager/docs/add-secret-version#add-a-secret-version).
	3. When rotation is complete, confirm by checking the **Certificates** list for the new serial number, or by inspecting the certificate at your deployment's endpoint.
	No configuration changes are required in either case. To confirm your deployment is using an updated certificate, check the **Certificates** list for the new serial number or inspect the certificate at your deployment's endpoint.

[valyria257]

If we say "within 4 hours" above, do we still need this?

Suggested change

	### Rotation timeline
	New secret versions are picked up and applied to your deployment within four hours.

[vivki]

Hm I think you're right, I'll drop the "Rotation Timeline" heading since it's one line away.