feat(qov-1870) Improve secret manager doc

docs/configuration/integrations/secret-managers/secret-manager-access.mdx

@@ -16,6 +16,25 @@ import ReferenceExternalSecrets from '/snippets/secret-manager-access/reference-
   * GCP Secret Manager
 </Info>
 
+## Secret Manager Access benefits
+
+Compared to Qovery built-in secrets, integrating a dedicated Secret Manager offers several key advantages:
+
+- **Security and data sovereignty**: Your secrets stay entirely within your own infrastructure and are never transmitted through Qovery's systems.
+ Secret values are fetched directly by External Secret Operator from your provider into your cluster, minimizing the number of systems that ever handle
+ raw secret values. With built-in secrets, the value passes through Qovery's API and storage layer.
+
+- **Centralized secret management**: Use your existing secrets provider as a single source of truth across all your infrastructure —
+Qovery services, Lambda functions, CI pipelines, and other tools all reference the same secrets without duplication.
+A secret defined once can also be consumed by multiple clusters (e.g., staging and production) without recreating it in each environment.
+
+- **Simplified and automatic secret rotation**: When a shared secret needs updating, change it once in your secrets manager, then redeploy
+the affected services via Qovery to pick up the new value. You can also leverage native automatic rotation from your provider (e.g., database credentials
+rotated via a Lambda function) — Qovery services will benefit from it in the next deployment without any additional secret management step.
+
+- **Audit trails and compliance**: Cloud-native secret managers provide built-in versioning, access logs, and fine-grained IAM policies —
+seamlessly extending your existing compliance posture to secrets consumed by Qovery services.
+
 ## How it works
 
 Qovery integrates with external secrets by deploying [ESO](https://external-secrets.io/latest/) (External Secrets Operator) in your cluster.

docs/snippets/secret-manager-access/reference-external-secrets.mdx

@@ -1,60 +1,9 @@
-## Reference the external secrets in your service
-
-Once your cluster is deployed, you can link external secrets to any service:
-* Open your service
-* Navigate to the **Variables** tab
-* Select the **External secrets** tab
-* Click **Add external secret**
-
-<Frame>
-  <img src="/images/configuration/secret-manager-access/create-external-secret-path.png" alt="External Secrets path"/>
-</Frame>
-
-Qovery automatically lists the secrets available in your Secrets Provider to simplify setup:
-
-<Frame>
-  <img src="/images/configuration/secret-manager-access/create-external-secret-list.png" alt="External Secrets list secrets available"/>
-</Frame>
-
-You can filter results **by prefix** to narrow the list:
-
-<Frame>
-  <img src="/images/configuration/secret-manager-access/create-external-secret-list-prefix.png" alt="External Secrets list secrets available by prefix"/>
-</Frame>
-
-To create an external secret, you need to:
-* Select the Secret Manager Access
-* Select the secret from your Secret Manager
-* Provide the environment variable key to inject
-
-<Frame>
-  <img src="/images/configuration/secret-manager-access/create-external-secret-details.png" alt="External Secrets details"/>
-</Frame>
-
-<Warning>
-  External secrets are fetched **only at deployment**. A running service won't automatically pick up changes to its external secrets — it requires a redeploy.
-</Warning>
-
-### Using external secrets with Terraform services
-
-Terraform services handle environment variables differently from other service types. Unlike application services where any environment variable is directly injected into the container, Terraform services expose variables through the Terraform variable system (`TF_VAR_*`). This means external secrets require a specific naming convention to be picked up correctly by Terraform at runtime.
-
-External secrets are supported only in the "External Secrets" tab:
-* You can't reference an external secret inside the "Terraform variables" section
-* You can't reference an external secret inside the "Terraform arguments" section
-
-To inject external secrets into your Terraform workflows:
-* The key of your external secrets must follow the pattern `TF_VAR_${your_variable}`
-* You must not have an override of `your_variable` inside the "Terraform variables" from any `file.tfvars`
-
-<Frame>
-  <img src="/images/configuration/secret-manager-access/terraform-service-external-secret.png" alt="Terraform service external secret"/>
-</Frame>
+## Reference the external secrets in your services
 
 <Warning>
   **Setting external secrets at the environment level multiplies cloud costs.**
 
-  You can set external secrets at the environment level, but be careful:
+  You can set external secrets at the environment level to inject them to all services, but be careful:
   * The secret value will be fetched individually for each service running in the environment.
   * With many services, this multiplies the number of secret fetches and can significantly increase your cloud costs.
 
@@ -113,3 +62,101 @@ To inject external secrets into your Terraform workflows:
 
   Prefer service-level secrets when only a subset of services need access to the value.
 </Warning>
+
+### Using the Qovery Console
+
+Once your cluster is deployed, you can link external secrets to any service:
+* Open your service
+* Navigate to the **Variables** tab
+* Select the **External secrets** tab
+* Click **Add external secret**
+
+<Frame>
+  <img src="/images/configuration/secret-manager-access/create-external-secret-path.png" alt="External Secrets path"/>
+</Frame>
+
+Qovery automatically lists the secrets available in your Secrets Provider to simplify setup:
+
+<Frame>
+  <img src="/images/configuration/secret-manager-access/create-external-secret-list.png" alt="External Secrets list secrets available"/>
+</Frame>
+
+You can filter results **by prefix** to narrow the list:
+
+<Frame>
+  <img src="/images/configuration/secret-manager-access/create-external-secret-list-prefix.png" alt="External Secrets list secrets available by prefix"/>
+</Frame>
+
+To create an external secret, you need to:
+* Select the Secret Manager Access
+* Select the secret from your Secret Manager
+* Provide the environment variable key to inject
+
+<Frame>
+  <img src="/images/configuration/secret-manager-access/create-external-secret-details.png" alt="External Secrets details"/>
+</Frame>
+
+Similarly to a basic environment variable, you can create an external secret that can be mounted to a file:
+
+<Frame>
+  <img src="/images/configuration/secret-manager-access/create-external-secret-file.png" alt="External Secret file details"/>
+</Frame>
+
+
+<Warning>
+  External secrets are fetched **only at deployment**. A running service won't automatically pick up changes to its external secrets — it requires a redeploy.
+</Warning>
+
+### Using the Qovery CLI
+
+* Create an external secret:
+```bash
+qovery application external-secret create \
+  --project="My Project" \
+  --environment="My environment" \
+  --key="MY_EXTERNAL_SECRET" \
+  --reference="upstream/secret/name" \
+  --secret-manager-access-name="My Secret Manager Access"
+```
+
+<Info>
+  To create an external secret as a file, just add the `--mount-path="path"` parameter
+</Info>
+
+* Update an external secret:
+```bash
+qovery application external-secret update \
+  --project="My Project" \
+  --environment="My environment" \
+  --key="MY_EXTERNAL_SECRET" \
+  --reference="upstream/secret/name" \
+  --secret-manager-access-name="My Secret Manager Access"
+```
+
+<Info>
+  You can't update the mount path of an external secret (same behavior as basic environment variable)
+</Info>
+
+* Delete an external secret:
+```bash
+qovery application external-secret delete \
+  --project="My Project" \
+  --environment="My environment" \
+  --key="MY_EXTERNAL_SECRET"
+```
+
+### Using external secrets with Terraform services
+
+Terraform services handle environment variables differently from other service types. Unlike application services where any environment variable is directly injected into the container, Terraform services expose variables through the Terraform variable system (`TF_VAR_*`). This means external secrets require a specific naming convention to be picked up correctly by Terraform at runtime.
+
+External secrets are supported only in the "External Secrets" tab:
+* You can't reference an external secret inside the "Terraform variables" section
+* You can't reference an external secret inside the "Terraform arguments" section
+
+To inject external secrets into your Terraform workflows:
+* The key of your external secrets must follow the pattern `TF_VAR_${your_variable}`
+* You must not have an override of `your_variable` inside the "Terraform variables" from any `file.tfvars`
+
+<Frame>
+  <img src="/images/configuration/secret-manager-access/terraform-service-external-secret.png" alt="Terraform service external secret"/>
+</Frame>