fix: upgrade path on docs

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",

docs/enterprise/externalsecrets/credential-rotation.mdx

@@ -0,0 +1,137 @@
+---
+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.
+
+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 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 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
+
+External Secrets Enterprise provides different mechanisms for credential rotation depending on your environment:
+
+#### Kubernetes Environments
+
+<AccordionGroup>
+  <Accordion title="Reloader Integration">
+    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.
+  </Accordion>
+
+  <Accordion title="Dynamic Credentials with [Pod Webhook](/docs/enterprise/externalsecrets/pod-webhook/index)">
+    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.
+  </Accordion>
+</AccordionGroup>
+
+#### Virtual Machine Environments
+
+<AccordionGroup>
+  <Accordion title="VM Target Integration">
+    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.
+  </Accordion>
+</AccordionGroup>
+
+
+## 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:
+
+<AccordionGroup>
+  <Accordion title="Regular Restarts">
+    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.
+  </Accordion>
+
+  <Accordion title="Graceful Failure Handling">
+    Applications should implement graceful handling of credential failures, including:
+    - Retry mechanisms with exponential backoff
+    - Circuit breakers to prevent cascading failures
+    - Fallback mechanisms where appropriate
+  </Accordion>
+
+  <Accordion title="Credential Caching">
+    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
+  </Accordion>
+</AccordionGroup>
+
+## 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.

docs/enterprise/externalsecrets/get-started.mdx

@@ -33,7 +33,8 @@
   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.
 </Note>
 
-
+<Tabs>
+<Tab title="New Installation">
 ```bash
 helm install esi-bundle \
     --namespace esi-bundle \
@@ -43,6 +44,26 @@
     --timeout 10m \
     oci://oci.externalsecrets.com/external-secrets-inc-registry/public/charts/esi-bundle
 ```
+</Tab>
+<Tab title="Upgrade an existing external-secrets operator instance">
+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.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
+```
+</Tab>
+</Tabs>
+
 <Tip>
 The Helm installation will wait until everything is up and running.
 This can take up to 10 minutes due to image downloads.
@@ -54,7 +75,7 @@
 </Accordion>
 
 <Accordion title="3. Access the Web UI">
 To access the web UI, you need to port-forward the Traefik service that was installed as part of the bundle. Traefik is used as an Ingress controller to expose the UI.
 
 ```bash
 kubectl port-forward -n traefik svc/traefik 8080:80