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]

we should avoid vague language like "usually" and "approximately"

can this be reworded to say something like "on average..."

[tstraley]

Or be more assertive, since this is the requirement, right?

Suggested change

	New secret versions are usually applied to your deployment within approximately 4 hours.
	New secret versions are picked up and applied to your deployment within four hours.

[JTorreG]

approved with suggestions

[mjang]

a few more comments

[tstraley]

All of this new content is specific to Google Secret Manager managed certificates. It seems it would fit better as topics within /nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md rather than this overview page.

[valyria257]

I've been seeing the overview pages as "info" pages that describes what the feature is. Then, the other pages are more "how to" pages that describe how to enable the feature. (@JTorreG / @mjang feel free to tell me I'm off base)

With that in mind, I think it makes sense to describe manual and autorotation in the overview page and link to the "Add certificates from Secret Manager" how-to page. That way, the feature is more visible (maybe that's subjective)

[tstraley]

Yeah, this content sounded more like "how to rotate Secret Manager certs" not "what is autorotation".

I could see us expanding this overview a bit more to provide some info about each kind of cert management "tool". eg.

There are multiple ways to manage your SSL/TLS certs and keys securely:

*Google Secret Manager* can be utilized to fetch secrets directly from [Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview), without ever leaving Google Cloud infrastructure. This solution allows you to use secret aliases for auto-rotation, or secret version pinning for greater control of cert rotation through your deployments.

*NGINXaaS Console* can be used to manage your certs and keys right next to your NGINXaaS configurations that use them. [...]

[valyria257]

Yeah I like that 👍

@vivki thoughts on moving the more informational bits to the overview page and leave the how-to instructions in /nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md?

[tstraley]

Or be more assertive, since this is the requirement, right?

Suggested change

	New secret versions are usually applied to your deployment within approximately 4 hours.
	New secret versions are picked up and applied to your deployment within four hours.

[mjang]

Awaiting @tstraley 's approval before merging

[valyria257]

What does "Open the Configuration Info panel" mean?

Based on the UI right now, I think we can just say "Select Reapply Configuration in Configuration Info panel".

[valyria257]

Suggested change

	If your configuration references secrets using the `versions/latest` alias, NGINXaaS automatically picks up new certificate versions. When you add a new secret version in Secret Manager, the next scheduled sync fetches it and reloads NGINX. No configuration changes are required.
	If your configuration references secrets using `latest` as the version ID, NGINXaaS automatically picks up the latest certificate version. When you add a new secret version in Secret Manager, the next scheduled sync fetches it and reloads NGINX. No configuration changes are required.

[tstraley]

another place to clarify alias functionality as well:

Suggested change

	If your configuration references secrets using the `versions/latest` alias, NGINXaaS automatically picks up new certificate versions. When you add a new secret version in Secret Manager, the next scheduled sync fetches it and reloads NGINX. No configuration changes are required.
	If your configuration references secrets using `latest` as the version ID, NGINXaaS automatically picks up the latest secret version on a regular cadence. When you add a new secret version in Secret Manager, the next scheduled sync fetches it and reloads NGINX.
	If your configuration references secrets using a custom alias as the version ID, NGINXaaS automatically picks up the secret version referenced by that alias on a regular cadence. When you adjust the secret version an alias points to in Secret Manager, the next scheduled sync fetches that secret version and applies it to your NGINXaaS deployment.
	In either of these cases, no changes to your NGINXaaS configuration are required.

[valyria257]

4 hours is our SLO, so it shouldn't take longer than that 🤞

Suggested change

	New secret versions are applied to your deployment within four hours on average.
	New secret versions are applied to your deployment within four hours.

[valyria257]

"To rotate your certificate" implies this is a manual action. Maybe instead something like:

Suggested change

	To rotate your certificate:
	To ensure certificates are automatically rotated:

[valyria257]

Include instructions from google:

Suggested change

	2. Add the updated certificate and key as new secret versions in Secret Manager. No configuration changes are needed.
	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).

[valyria257]

I'm not sure about saying "Wait for NGINXaaS to apply the updated certificate" as this could take a couple hours. Maybe just remove this "step"? Maybe mention that the serial number gets updated in the monitor section?

[tstraley]

Maybe

Suggested change

	3. Wait for NGINXaaS to apply the updated certificate. Rotation is complete when the new certificate serial number appears on your NGINX endpoint and in the NGINXaaS **Certificates** list.
	3. NGINXaaS will eventually synchronize the latest certificate and key to your deployment. You can confirm the certificate(s) that are in-use by your deployment by reviewing the NGINXaaS **Certificates** list for uniquely identifying metadata, such as the serial number, or by inspecting the certificate(s) served by the specific endpoint of your deployment.

(maybe the last clause about inspecting the cert is overkill, or maybe it needs more detail such as an example openssl s_client -connect -showcerts command..)

[vivki]

Keeping it appropriately vague:
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.

[valyria257]

We already have the call-out "tip" "Enable automatic rotation with latest" and the intro to this section saying the version needs to be latest. Do we need this here too?

If you've pinned a specific version number, manually rotate using Reapply Configuration

If using a specific version number, it will not be rotated even if clicking Reapply Configuration. That will just fetch the same secret version.

[vivki]

removing this block

[valyria257]

I like this table thanks for adding this 👍

[tstraley]

since latest is a special keyword offered by Google Secret Manager that is separate from aliases, I think we need to clarify (and maybe offer some other content about how to manage certs with aliases in these docs, as well?)

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 number (for example, `3`) or an alias such as `latest`. Using `latest` enables automatic certificate rotation. For more information, see [Rotate a Secret Manager certificate (automatic)](#rotate-a-secret-manager-certificate-automatic). |

| 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`), an alias you've created, or the special version ID `latest`. Using `latest` enables automatic certificate rotation. For more information, see [Rotate a Secret Manager certificate (automatic)](#rotate-a-secret-manager-certificate-automatic). |

[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.

[tstraley]

another place to clarify alias functionality as well:

Suggested change

	If your configuration references secrets using the `versions/latest` alias, NGINXaaS automatically picks up new certificate versions. When you add a new secret version in Secret Manager, the next scheduled sync fetches it and reloads NGINX. No configuration changes are required.
	If your configuration references secrets using `latest` as the version ID, NGINXaaS automatically picks up the latest secret version on a regular cadence. When you add a new secret version in Secret Manager, the next scheduled sync fetches it and reloads NGINX.
	If your configuration references secrets using a custom alias as the version ID, NGINXaaS automatically picks up the secret version referenced by that alias on a regular cadence. When you adjust the secret version an alias points to in Secret Manager, the next scheduled sync fetches that secret version and applies it to your NGINXaaS deployment.
	In either of these cases, no changes to your NGINXaaS configuration are required.