diff --git a/content/nginxaas-google/getting-started/ssl-tls-certificates/overview.md b/content/nginxaas-google/getting-started/ssl-tls-certificates/overview.md index 756f63aba..716970248 100644 --- a/content/nginxaas-google/getting-started/ssl-tls-certificates/overview.md +++ b/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" >}}). diff --git a/content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md b/content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md index 4c04f8b80..f991b2caf 100644 --- a/content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-console.md +++ b/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" >}}) diff --git a/content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md b/content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md index 5a8e784c7..708179e81 100644 --- a/content/nginxaas-google/getting-started/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md +++ b/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" >}}) \ No newline at end of file