add docs for google secret rotation

content/nginxaas-google/getting-started/ssl-tls-certificates/overview.md

@@ -27,7 +27,16 @@ Encrypt your certificates, keys, and PEM files using one of these standards:
 
 ## Add SSL/TLS certificates
 
-Add a certificate to your NGINXaaS deployment using your preferred client tool:
+NGINXaaS supports two ways to manage your certificates and keys securely:
 
-- [Add certificates from Secret Manager]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md" >}})
-- [Add certificates using the NGINXaaS Console]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md" >}})
+**NGINXaaS console** — Manage certificates alongside the NGINX configurations that reference them. See [Add certificates using the NGINXaaS Console]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}).
+
+**Google Secret Manager** — Fetch secrets directly from [Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview), keeping credentials within Google Cloud. See [Add certificates from Secret Manager]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md" >}}).
+
+## Certificate rotation
+
+NGINXaaS supports automatic and manual rotation for Secret Manager certificates:
+
+**Automatic rotation** — Let NGINXaaS pick up new certificate versions automatically with no configuration changes needed. See [Rotate a Secret Manager certificate (automatic)]({{< ref "/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#rotate-a-secret-manager-certificate-automatic" >}}).
+
+**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" >}}).

content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md

@@ -71,7 +71,6 @@ To use a certificate in an NGINX configuration, follow these steps:
 
 {{< call-out "warning" >}}Deleting a TLS/SSL certificate currently in-use by the NGINXaaS for Google Cloud deployment will cause an error.{{< /call-out >}}
 
-
 ## What's next
 
 [Upload an NGINX Configuration]({{< ref "/nginxaas-google/getting-started/nginx-configuration/nginx-configuration-console.md" >}})

content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md

@@ -45,10 +45,15 @@ To add your Secret Manager certificate and key to an NGINX configuration in the
 
    | Field                       | Description                  | Note |
    |---------------------------- | ---------------------------- | ---- |
-   | 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 or an alias such as `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`. |
    | File Path               | The secret will be written to this file path so it can be used with NGINX directives such as ssl_certificate or ssl_certificate_key in your NGINX configuration. | The path must be unique within the configuration. |
 
     {{< /table >}}
+
+{{< call-out "tip" "Enable automatic rotation with latest" >}}
+If you set `$VERSION` to `latest`, NGINXaaS automatically picks up any new secret version you add to Secret Manager without a configuration change. NGINXaaS applies new versions within four hours. See [Rotate a Secret Manager certificate (automatic)](#rotate-a-secret-manager-certificate-automatic) for details.
+{{< /call-out >}}
+
 - Update the NGINX configuration to reference the certificate you just added by the path value.
 - Select **Add**, **Next**, and then **Save** to save your changes.
 
@@ -62,6 +67,55 @@ Before updating your NGINXaaS deployment to use your new NGINX configuration, en
 - Select the configuration and configuration version created in the last section.
 - Select **Update Configuration**.
 
+## Rotate a Secret Manager certificate (automatic)
+
+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 four hours.
+
+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 four hours.
+
+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.
+
+## Rotate a Secret Manager certificate (manual)
+
+To immediately refetch secrets without editing your NGINX configuration, use **Reapply Configuration**. This 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.
+
+To reapply your configuration:
+
+1. In the NGINXaaS console, go to your deployment.
+2. Select **Reapply Configuration** in the **Configuration Info** panel.
+
+NGINXaaS reapplies your current configuration version and immediately refetches all referenced secrets.
+
+## Monitor secret fetch events
+
+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.
+
+### Event types
+
+{{< table >}}
+| Event type | Description |
+|---|---|
+| Successful Secret Fetch from Google | The secret was fetched from Secret Manager and applied to NGINX. |
+| Failed Secret Fetch from Google | NGINXaaS couldn't fetch the secret. The event message includes the error details. |
+{{< /table >}}
+
+### View events in the console
+
+- Select **Overview** in the left menu, then select **Events**. To narrow results to a specific deployment, filter by its object ID using the controls at the top of the page.
+- For a summary of recent events for a specific deployment, select **Deployments**, select the deployment, and look for the **Recent Events** card. Select **See Events Details** to go to the full Events page pre-filtered for that deployment.
+
+### Common failure messages and remediation
+
+{{< table >}}
+| Message | Likely cause | Remediation |
+|---|---|---|
+| `Failed to fetch secret ... PermissionDenied: Permission 'secretmanager.versions.access' denied` | The Workload Identity Federation principal doesn't have the required IAM role on the secret. | Verify the WIF principal has the Secret Manager Secret Accessor role on the project or secret. |
+| `Failed to fetch secret ... NotFound: Secret [...] has no alias [latest]` | No versions exist for the referenced secret, or the specified version alias or number doesn't exist. | Confirm the secret has at least one enabled version and that the resource name in your configuration uses a valid version or alias. |
+{{< /table >}}
+
 ## What's next
 
 [Upload an NGINX Configuration]({{< ref "/nginxaas-google/getting-started/nginx-configuration/nginx-configuration-console.md" >}})