From 2158ef0fa9b036108e5a51e4288b3d1453acd399 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Tue, 5 Aug 2025 07:42:34 -0300 Subject: [PATCH 1/5] fix: upgrade path on docs Signed-off-by: Gustavo Carvalho --- .../externalsecrets/get-started.mdx | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/enterprise/externalsecrets/get-started.mdx b/docs/enterprise/externalsecrets/get-started.mdx index ff44c67..ff0915c 100644 --- a/docs/enterprise/externalsecrets/get-started.mdx +++ b/docs/enterprise/externalsecrets/get-started.mdx @@ -33,7 +33,8 @@ Now, let's install the External Secrets Enterprise bundle using our Helm chart. The installation bundle is for a Trial License, which is available at https://externalsecrets.com/trial-license. By installing this bundle, you agree to the license terms. - + + ```bash helm install esi-bundle \ --namespace esi-bundle \ @@ -43,6 +44,24 @@ helm install esi-bundle \ --timeout 10m \ oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle ``` + + +If you are installing from `external-secrets-operator`, there is a path for a safe upgrade. + +All you need to do is to use the same `releaseName` and `namespace` as you used for the `external-secrets-operator` release: +```bash +ESO_RELEASE_NAME=external-secrets +ESO_RELEASE_NAMESPACE=external-secrets +helm upgrade $ESO_RELEASE_NAME \ + --namespace $ESO_RELEASE_NAMESPACE \ + --set global.trialLicenseAccepted=true \ + --set global.waitForReady=true \ + --timeout 10m \ + oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle +``` + + + The Helm installation will wait until everything is up and running. This can take up to 10 minutes due to image downloads. From 163ece844284f252f78d9d32351abf230044ec95 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Tue, 5 Aug 2025 08:12:16 -0300 Subject: [PATCH 2/5] fix: command Signed-off-by: Gustavo Carvalho --- docs/enterprise/externalsecrets/get-started.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/enterprise/externalsecrets/get-started.mdx b/docs/enterprise/externalsecrets/get-started.mdx index ff0915c..d12cb7b 100644 --- a/docs/enterprise/externalsecrets/get-started.mdx +++ b/docs/enterprise/externalsecrets/get-started.mdx @@ -54,11 +54,12 @@ ESO_RELEASE_NAME=external-secrets ESO_RELEASE_NAMESPACE=external-secrets helm upgrade $ESO_RELEASE_NAME \ --namespace $ESO_RELEASE_NAMESPACE \ + --set global.namespaces.externalSecrets.createNamespace=false \ + --set external-secrets.namespaceOverride=$ESO_RELEASE_NAMESPACE \ --set global.trialLicenseAccepted=true \ --set global.waitForReady=true \ --timeout 10m \ - oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle -``` + oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle``` From 8f77b0a3f626d15414167e831df078934a5ebd9e Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Tue, 5 Aug 2025 08:13:39 -0300 Subject: [PATCH 3/5] fix: indentation Signed-off-by: Gustavo Carvalho --- docs/enterprise/externalsecrets/get-started.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/enterprise/externalsecrets/get-started.mdx b/docs/enterprise/externalsecrets/get-started.mdx index d12cb7b..2509bed 100644 --- a/docs/enterprise/externalsecrets/get-started.mdx +++ b/docs/enterprise/externalsecrets/get-started.mdx @@ -59,7 +59,8 @@ helm upgrade $ESO_RELEASE_NAME \ --set global.trialLicenseAccepted=true \ --set global.waitForReady=true \ --timeout 10m \ - oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle``` + oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle +``` From 53320d140f1b386beca1363591110c6cce8c8c69 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Tue, 5 Aug 2025 08:34:44 -0300 Subject: [PATCH 4/5] feat: how does it work page Signed-off-by: Gustavo Carvalho --- docs.json | 1 + .../externalsecrets/credential-rotation.mdx | 131 ++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 docs/enterprise/externalsecrets/credential-rotation.mdx diff --git a/docs.json b/docs.json index 233ede0..642dfd5 100644 --- a/docs.json +++ b/docs.json @@ -20,6 +20,7 @@ "pages": [ "docs/enterprise/externalsecrets/introduction", "docs/enterprise/externalsecrets/get-started", + "docs/enterprise/externalsecrets/credential-rotation", { "icon": "lines-leaning", "group": "Tutorials", diff --git a/docs/enterprise/externalsecrets/credential-rotation.mdx b/docs/enterprise/externalsecrets/credential-rotation.mdx new file mode 100644 index 0000000..7a511fc --- /dev/null +++ b/docs/enterprise/externalsecrets/credential-rotation.mdx @@ -0,0 +1,131 @@ +--- +title: 'How does it Work?' +description: 'Best practices and mechanisms to maintain application availability during credential rotation' +icon: question +--- + +import { Accordion, AccordionGroup, Note, Tip } from '@mintlify/components' + + +One of the most critical aspects of secret management is ensuring that applications remain operational during credential rotation. External Secrets Enterprise provides several mechanisms to ensure zero-downtime credential rotation. + +## Understanding Credential Rotation Challenges + +When rotating credentials, organizations typically face several challenges: + +1. **Downtime Risk**: If an application can't access its credentials, it may fail or become unavailable. +2. **Coordination Complexity**: Ensuring all application instances switch to new credentials at the right time. +3. **Cleanup Timing**: Determining when it's safe to remove old credentials without disrupting services. +4. **Monitoring**: Tracking the rotation process and detecting any issues. + +External Secrets Enterprise addresses these challenges through several complementary approaches. + +## Credential Lifecycle Management + +External Secrets Enterprise implements a sophisticated credential lifecycle management system that ensures applications can continue running during rotation: + +### 🔄 Simultaneous Distribution + +When a new credential is generated through [workflows](/docs/enterprise/externalsecrets/workflows/introduction), External Secrets Enterprise immediately distributes it to all clients at once. The credential is created in your secret store (like Vault or AWS Secrets Manager) and becomes available to all applications across your environment simultaneously. This synchronized approach ensures consistency across your infrastructure and eliminates complex coordination between application instances. + +### 🔍 Comprehensive Usage Tracking + +External Secrets Enterprise maintains complete awareness of where and how credentials are being used. It tracks which Kubernetes Pods are using specific credentials, which files on which VMs contain credential data, and maintains relationships between dynamic credentials and their requesting applications. This visibility ensures that no credential is ever removed while still in use. + +### 🔌 Seamless Application Updates + +Applications can access updated credentials without disruption. Hot-reload capable applications automatically pick up new credentials without any restart required. For Kubernetes applications, the [Reloader](/docs/open_source/reloader/introduction) component can trigger rolling updates when credentials change. VM-based applications get the latest credentials after a simple restart. Since External Secrets Enterprise tracks all credential usage locations, it ensures all instances are updated appropriately. + +### 🛡️ Safe Credential Retirement + +Old credentials are only deleted when two conditions are met: a new credential has been successfully generated AND the old credential is no longer in use by any application. This careful approach ensures applications have time to transition to new credentials before old ones are removed, preventing any service disruption. + +## Rotation Mechanisms by Environment + +External Secrets Enterprise provides different mechanisms for credential rotation depending on your environment: + +#### Kubernetes Environments + + + + For applications running in Kubernetes, External Secrets Enterprise integrates with the [Reloader](/docs/open_source/reloader/introduction) component to automatically update applications when credentials change. + + The Reloader watches for changes in secrets and can trigger: + - Deployment rollouts + - StatefulSet updates + - DaemonSet refreshes + - External Secrets reconciliation + + This ensures that applications always have the latest credentials without manual intervention. + + + + For enhanced security, the [Pod Webhook](/docs/enterprise/externalsecrets/pod-webhook/index) and [`esi-cli`](/docs/enterprise/externalsecrets/esi-cli/index) provide runtime-bound credentials: + + - Credentials are generated at Pod startup and injected directly into the application runtime using [`esi-cli`](/docs/enterprise/externalsecrets/esi-cli/index) + - Credential lifecycle is bound to the Pod lifecycle + - When a Pod is deleted, its credentials are automatically revoked + - New Pods receive fresh credentials upon startup + + This approach provides the strongest security posture by ensuring credentials are ephemeral and unique to each application instance. + + + +#### Virtual Machine Environments + + + + For applications running on virtual machines outside Kubernetes, External Secrets Enterprise provides the [VirtualMachine target](/docs/enterprise/externalsecrets/targets/virtual-machine): + + - Credentials are pushed directly to files on the VM using [`eso-vm-server`](/docs/enterprise/externalsecrets/targets/eso-vm-server) + - Regular refresh intervals ensure credentials are kept up-to-date + - Applications can be configured to watch for file changes or reload periodically + + This enables credential rotation for traditional applications running outside container environments. + + + + +## Best Practices for Application Developers + +While External Secrets Enterprise handles much of the complexity of credential rotation, application developers can follow these best practices to ensure smooth rotation: + + + + Until applications can directly integrate with External Secrets Enterprise's notification system, implementing regular application restarts (weekly or based on your security policy) ensures applications pick up the latest credentials. + + + + Applications should implement graceful handling of credential failures, including: + - Retry mechanisms with exponential backoff + - Circuit breakers to prevent cascading failures + - Fallback mechanisms where appropriate + + + + Implement appropriate credential caching strategies: + - Cache credentials in memory to reduce dependency on constant secret store availability + - Implement cache refresh mechanisms that don't block application operation + - Use background refresh to update cached credentials before they expire + + + +## Handling Rotation Failures + +External Secrets Enterprise provides robust handling of rotation failures: + +1. **Retry Mechanism**: Workflows are retried at each scheduled interval, ensuring temporary failures don't prevent rotation. +2. **Preservation of Working Credentials**: Old credentials remain valid until new ones are successfully generated and deployed. +3. **No Premature Deletion**: The system never deletes old credentials until new ones are confirmed working and in use. + +## Future Enhancements + +External Secrets Enterprise is continuously evolving to improve credential rotation capabilities: + +- **Application Integration**: Future versions will enable direct management of application deployments, automatically triggering updates when credentials change. +- **Process Management on VMs**: Upcoming features will include the ability to restart processes on VMs when credential files change. +- **Enhanced Monitoring**: Additional monitoring and alerting capabilities for credential lifecycle events. + +## Conclusion + +External Secrets Enterprise provides comprehensive mechanisms to ensure application continuity during credential rotation. By combining intelligent credential lifecycle management, environment-specific update mechanisms, and robust failure handling, the platform enables organizations to implement secure credential rotation practices without risking application availability. From 4621e96f18c5eaa65aab21b3f78c25a1ddc42978 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Tue, 5 Aug 2025 08:40:45 -0300 Subject: [PATCH 5/5] fix: minor redaction Signed-off-by: Gustavo Carvalho --- .../enterprise/externalsecrets/credential-rotation.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/enterprise/externalsecrets/credential-rotation.mdx b/docs/enterprise/externalsecrets/credential-rotation.mdx index 7a511fc..ad146d3 100644 --- a/docs/enterprise/externalsecrets/credential-rotation.mdx +++ b/docs/enterprise/externalsecrets/credential-rotation.mdx @@ -32,13 +32,19 @@ When a new credential is generated through [workflows](/docs/enterprise/external External Secrets Enterprise maintains complete awareness of where and how credentials are being used. It tracks which Kubernetes Pods are using specific credentials, which files on which VMs contain credential data, and maintains relationships between dynamic credentials and their requesting applications. This visibility ensures that no credential is ever removed while still in use. +It does it by actively [scanning](/docs/enterprise/externalsecrets/scan/introduction) secret stores and targets for credential usage and distribution patterns. + ### 🔌 Seamless Application Updates -Applications can access updated credentials without disruption. Hot-reload capable applications automatically pick up new credentials without any restart required. For Kubernetes applications, the [Reloader](/docs/open_source/reloader/introduction) component can trigger rolling updates when credentials change. VM-based applications get the latest credentials after a simple restart. Since External Secrets Enterprise tracks all credential usage locations, it ensures all instances are updated appropriately. +Applications can access updated credentials without disruption. Hot-reload capable applications automatically pick up new credentials without any restart required. + +For Kubernetes applications, the [Reloader](/docs/open_source/reloader/introduction) component can trigger rolling updates when credentials change wherever they are (Secret Stores, Secrets, ...). VM-based applications get the latest credentials after a simple restart. Since External Secrets Enterprise tracks all credential usage locations, it ensures all instances are updated appropriately. ### 🛡️ Safe Credential Retirement -Old credentials are only deleted when two conditions are met: a new credential has been successfully generated AND the old credential is no longer in use by any application. This careful approach ensures applications have time to transition to new credentials before old ones are removed, preventing any service disruption. +Old credentials are only deleted when two conditions are met: a new credential has been successfully distributed AND the old credential is no longer in use by any application. This careful approach ensures applications have time to transition to new credentials before old ones are removed, preventing any service disruption. + +You can also keep track what are the credentials pending to be deleted, and what are the clients using it (when supported by the credentials provider) ## Rotation Mechanisms by Environment