diff --git a/pages/index.md b/pages/index.md index b0347a3b779..aefa14044de 100644 --- a/pages/index.md +++ b/pages/index.md @@ -2210,6 +2210,7 @@ + [Manage your OKMS access certificate](manage_and_operate/kms/okms-certificate-management) + [OKMS Architecture overview](manage_and_operate/kms/architecture-overview) + [OKMS - Shared responsibilities](manage_and_operate/kms/responsibility-model-kms) + + [Use Kubernetes External Secret Operator with Secret Manager](manage_and_operate/secret_manager/external-secret-operator) + OVHcloud Labs + [Data Collector](products/ovhcloud-labs-data-collector) + [Getting started](ovhcloud-labs-data-collector-getting-started) diff --git a/pages/manage_and_operate/secret_manager/external-secret-operator/guide.en-gb.md b/pages/manage_and_operate/secret_manager/external-secret-operator/guide.en-gb.md new file mode 100644 index 00000000000..2288175f1ae --- /dev/null +++ b/pages/manage_and_operate/secret_manager/external-secret-operator/guide.en-gb.md @@ -0,0 +1,265 @@ +--- +title: "Use Kubernetes External Secret Operator with Secret Manager" +excerpt: "Configure External Secret Operator to store Kubernetes secrets on the OVHcloud Secret Manager" +updated: 2025-11-07 +--- + +> [!primary] +> Secret Manager is currently in Beta phase. This guide can be updated in the future with the advancements made by our teams in charge of this product. + +## Objective + +This guide explains how to set up the Kubernetes External Secret Operator to use the OVHcloud Secret Manager as a provider. + +## Requirements + +- An [OVHcloud customer account](/pages/account_and_service_management/account_information/ovhcloud-account-creation). +- Have [ordered an OKMS domain](/pages/manage_and_operate/kms/quick-start) or [created a first secret](/pages/manage_and_operate/secret_manager/secret-manager-ui). +- Have a Kubernetes cluster. + +## Instructions + +### Setup the Secret Manager + +To allow access to the Secret Manager you will need to have a `token`, the `region` and `okms-id` of your Secret Manager. + +#### Credential creation + +Create an [IAM local user](/pages/account_and_service_management/account_information/ovhcloud-users-management) with access right on your domain. + +The user should be a member of a group with the ADMIN role, or if using [IAM policies](/pages/account_and_service_management/account_information/iam-policy-ui) to have at least the following rights on the OKMS domain: + +- `okms:apikms:secret/create` +- `okms:apikms:secret/version/getData` +- `okms:apiovh:secret/get` + +Then create a Personnal Acces Token (PAT) `user_pat`: + +> [!tabs] +> API +>> > [!api] +>> > +>> > @api {v1} /me POST /me/identity/user/{user}/token +>> +>> With the following payload (fill with your values): +>> +>> ```json +>> { +>> "description": "PAT secret manager for domain xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", +>> "name": "pat-secretmanager-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx" +>> } +>> ``` +>> +>> API will answer with: +>> +>> ```json +>> { +>> "creation": "2025-11-13T10:38:44.658926311Z", +>> "description": "PAT secret manager for domain xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", +>> "expiresAt": null, +>> "lastUsed": null, +>> "name": "pat-secretmanager-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", +>> "token": "eyJhbGciOiJ...punpVAg" +>> } +>> ``` +>> +> CLI +>> PAT can also created with the [OVHcloud CLI](https://github.com/ovh/ovhcloud-cli) and the command (fill with your values): +>> +>> ```bash +>> ovhcloud iam user token create {user} --name pat-secretmanager-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx --description "PAT secret manager for domain xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx" +>> ``` +>> +>> CLI will answer with the `token` value : +>> +>> ```bash +>> ✅ Token Secret-Manager created successfully, value: eyJhbGciOiJ...punpVAg +>> ``` + +Keep safe the value of `token` field as it will never be prompt again and will be used to authenticate on the Secret Manager as `user_pat`. + +#### Secret Manager info + +You will also need the `region` and the `okms-id` of the OKMS domain you want to use. This ID and this region can be found on the OVHcloud Control Panel. + +Or through the [`ovhcloud` CLI](https://github.com/ovh/ovhcloud-cli): + +```bash +$ ovhcloud okms list +┌──────────────────────────────────────┬─────────────┐ +│ id │ region │ +├──────────────────────────────────────┼─────────────┤ +│ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ eu-west-par │ +│ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ eu-west-par │ +└──────────────────────────────────────┴─────────────┘ +``` + +### Setup the Secret Provider in Kubernetes + +#### Install the External Secret Operator on your kubernetes + +```bash +helm repo add external-secrets https://charts.external-secrets.io +helm repo update + +helm install external-secrets \ + external-secrets/external-secrets \ + -n external-secrets \ + --create-namespace \ + --set installCRDs=true +``` + +Check ESO is running: + +```bash +$ kubectl get all -n external-secrets +NAME READY STATUS RESTARTS AGE +pod/external-secrets-8cbc56569-9875p 1/1 Running 0 12s +pod/external-secrets-cert-controller-565fcd479b-xbkcp 0/1 Running 0 12s +pod/external-secrets-webhook-7fb59d4b88-9tkl6 0/1 Running 0 12s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/external-secrets-webhook ClusterIP 10.3.43.102 443/TCP 13s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/external-secrets 1/1 1 1 13s +deployment.apps/external-secrets-cert-controller 0/1 1 0 13s +deployment.apps/external-secrets-webhook 0/1 1 0 13s + +NAME DESIRED CURRENT READY AGE +replicaset.apps/external-secrets-8cbc56569 1 1 1 13s +replicaset.apps/external-secrets-cert-controller-565fcd479b 1 1 0 13s +replicaset.apps/external-secrets-webhook-7fb59d4b88 1 1 0 13s +``` + +#### Create a secret containing the PAT + +Start by encoding your `user_pat` is base64 so it can be stored in a kubernetes secret. + +```bash +$ echo -n "" | base64 +ZXlKaG...wVkFn +``` + +Then create a `secret.yaml`: + +```yaml + apiVersion: v1 +kind: Secret +metadata: + name: ovhcloud-vault-token + namespace: external-secrets +data: + token: ZXlKaG...wVkFn +``` + +And apply the ressource to the cluster: + +```bash +kubectl apply -f secret.yaml +``` + +The secret should have been created: + +```bash +$ kubectl get secret ovhcloud-vault-token -n external-secrets +NAME TYPE DATA AGE +ovhcloud-vault-token Opaque 1 5m +``` + +#### Configure External Secret Operator + +First, setup a `ClusterSecretStore` that is responsible of the synchronization with the Secret Manager. +We configure the SecretStore using HashiCorp Vault with token authentification and with the OKMS endpoint as backend. + +Add the `user_pat` as a secret to be able to use it in the charts. + +To define a new `ClusterSecretStore` resource, create a `clustersecretstore.yaml` file with the followong content: + +```yaml +apiVersion: external-secrets.io/v1 +kind: ClusterSecretStore +metadata: + name: vault-secret-store +spec: + provider: + vault: + server: "https://.okms.ovh.net/api/" # OKMS endpoint, fill with the correct region and your okms_id + path: "secret" + version: "v2" + auth: + tokenSecretRef: + name: ovhcloud-vault-token # The k8s secret that contain your PAT + key: token +``` + +> [!info] +> Only [token authentication](https://external-secrets.io/latest/provider/hashicorp-vault/#token-based-authentication) is supported + +> [!info] +> This integration works with a `SecretStore` as well + +Region name can be translated from your region location using: + +> [!api] +> +> @api {v1} /location GET /location + +As an example for **Europe (France - Paris)**, OKMS endpoint is **eu-west-par.okms.ovh.net** + +Deploy the resource in your cluster: + +```bash +kubectl apply -f secretstore.yaml +``` + +#### Use External Secret Operator + +Once the `ClusterSecretStore` is setup you can define `ExternalSecret` that comes from the secret manager. +Create a `externalsecret.yaml` file with this content: + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: docker-config-secret + namespace: external-secrets +spec: + refreshInterval: 30m + secretStoreRef: + name: vault-secret-store + kind: ClusterSecretStore + target: + template: + type: kubernetes.io/dockerconfigjson + data: + .dockerconfigjson: "{{ .mysecret | toString }}" + name: ovhregistrycred + creationPolicy: Owner + data: + - secretKey: mysecret + remoteRef: + key: prod/va1/dockerconfigjson +``` + +Apply the resource in your cluster: + +```bash +kubectl apply -f externalsecret.yaml +``` + +It will create a Kubernetes Secret object. + +```bash +$ kubectl get secret -n external-secrets +NAME TYPE DATA AGE +... +ovhregistrycred kubernetes.io/dockerconfigjson 1 15m +... +``` + +For any additionnal informations on how to manage the External Secret Operator refer to the dedicated documentation, using the HashiCorp Vault provider: . + +## Go further + +Join our [community of users](/links/community). diff --git a/pages/manage_and_operate/secret_manager/external-secret-operator/guide.fr-fr.md b/pages/manage_and_operate/secret_manager/external-secret-operator/guide.fr-fr.md new file mode 100644 index 00000000000..236088e777a --- /dev/null +++ b/pages/manage_and_operate/secret_manager/external-secret-operator/guide.fr-fr.md @@ -0,0 +1,265 @@ +--- +title: "Utiliser Kubernetes External Secret Operator avec Secret Manager" +excerpt: "Configurer External Secret Operator pour stocker les secrets Kubernetes sur le Secret Manager d'OVHcloud" +updated: 2025-11-07 +--- + +> [!primary] +> Secret Manager est actuellement en phase bêta. Ce guide peut être mis à jour à l'avenir avec les avancées apportées par nos équipes en charge de ce produit. + +## Objectif + +Ce guide explique comment configurer l'External Secret Operator Kubernetes pour utiliser le Secret Manager d'OVHcloud en tant que fournisseur. + +## Prérequis + +- Un [compte client OVHcloud](/pages/account_and_service_management/account_information/ovhcloud-account-creation). +- Avoir [commandé un domaine OKMS](/pages/manage_and_operate/kms/quick-start) ou [créé un premier secret](/pages/manage_and_operate/secret_manager/secret-manager-ui). +- Avoir un cluster Kubernetes. + +## En pratique + +### Configuration du Secret Manager + +Pour permettre l'accès au Secret Manager, vous aurez besoin d'un `token`, de la `region` et de l'`okms-id` de votre Secret Manager. + +#### Création des identifiants + +Créez un [utilisateur local IAM](/pages/account_and_service_management/account_information/ovhcloud-users-management) avec les droits d'accès à votre domaine. + +L'utilisateur doit appartenir à un groupe avec le rôle ADMIN, ou si vous utilisez des [politiques IAM](/pages/account_and_service_management/account_information/iam-policy-ui), il doit avoir au moins les droits suivants sur le domaine OKMS : + +- `okms:apikms:secret/create` +- `okms:apikms:secret/version/getData` +- `okms:apiovh:secret/get` + +Puis créez un jeton d'accès personnel (PAT) `user_pat` : + +> [!tabs] +> API +>> > [!api] +>> > +>> > @api {v1} /me POST /me/identity/user/{user}/token +>> +>> Avec la charge utile suivante (remplissez avec vos valeurs) : +>> +>> ```json +>> { +>> "description": "PAT secret manager for domain xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", +>> "name": "pat-secretmanager-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx" +>> } +>> ``` +>> +>> L'API répondra avec : +>> +>> ```json +>> { +>> "creation": "2025-11-13T10:38:44.658926311Z", +>> "description": "PAT secret manager for domain xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", +>> "expiresAt": null, +>> "lastUsed": null, +>> "name": "pat-secretmanager-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", +>> "token": "eyJhbGciOiJ...punpVAg" +>> } +>> ``` +>> +> CLI +>> Le PAT peut également être créé avec l'[OVHcloud CLI](https://github.com/ovh/ovhcloud-cli) et la commande suivante (remplissez avec vos valeurs) : +>> +>> ```bash +>> ovhcloud iam user token create {user} --name pat-secretmanager-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx --description "PAT secret manager for domain xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx" +>> ``` +>> +>> La CLI répondra avec la valeur du `token` : +>> +>> ```bash +>> ✅ Token Secret-Manager created successfully, Value: eyJhbGciOiJ...punpVAg +>> ``` + +Conservez la valeur du champ `token` car elle ne sera plus affichée et sera utilisée pour s'authentifier sur le Secret Manager en tant que `user_pat`. + +#### Informations du Secret Manager + +Vous aurez également besoin de la `region` et de l'`okms-id` du domaine OKMS que vous souhaitez utiliser. Cet ID et cette région peuvent être trouvés sur l'espace client OVHcloud. + +Ou via l'[OVHcloud CLI](https://github.com/ovh/ovhcloud-cli) : + +```bash +$ ovhcloud okms list +┌──────────────────────────────────────┬─────────────┐ +│ id │ region │ +├──────────────────────────────────────┼─────────────┤ +│ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ eu-west-par │ +│ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ eu-west-par │ +└──────────────────────────────────────┴─────────────┘ +``` + +### Configuration du fournisseur de secrets dans Kubernetes + +#### Installation de l'External Secret Operator sur votre Kubernetes + +```bash +helm repo add external-secrets https://charts.external-secrets.io +helm repo update + +helm install external-secrets \ + external-secrets/external-secrets \ + -n external-secrets \ + --create-namespace \ + --set installCRDs=true +``` + +Vérifiez que l'ESO est en cours d'exécution : + +```bash +$ kubectl get all -n external-secrets +NAME READY STATUS RESTARTS AGE +pod/external-secrets-8cbc56569-9875p 1/1 Running 0 12s +pod/external-secrets-cert-controller-565fcd479b-xbkcp 0/1 Running 0 12s +pod/external-secrets-webhook-7fb59d4b88-9tkl6 0/1 Running 0 12s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/external-secrets-webhook ClusterIP 10.3.43.102 443/TCP 13s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/external-secrets 1/1 1 1 13s +deployment.apps/external-secrets-cert-controller 0/1 1 0 13s +deployment.apps/external-secrets-webhook 0/1 1 0 13s + +NAME DESIRED CURRENT READY AGE +replicaset.apps/external-secrets-8cbc56569 1 1 1 13s +replicaset.apps/external-secrets-cert-controller-565fcd479b 1 1 0 13s +replicaset.apps/external-secrets-webhook-7fb59d4b88 1 1 0 13s +``` + +#### Création d'un secret contenant le PAT + +Commencez par encoder votre `user_pat` en base64 afin de pouvoir le stocker dans un secret Kubernetes. + +```bash +$ echo -n "" | base64 +ZXlKaG...wVkFn +``` + +Puis créez un fichier `secret.yaml` : + +```yaml + apiVersion: v1 +kind: Secret +metadata: + name: ovhcloud-vault-token + namespace: external-secrets +data: + token: ZXlKaG...wVkFn +``` + +Et appliquez la ressource au cluster : + +```bash +kubectl apply -f secret.yaml +``` + +Le secret devrait avoir été créé : + +```bash +$ kubectl get secret ovhcloud-vault-token -n external-secrets +NAME TYPE DATA AGE +ovhcloud-vault-token Opaque 1 5m +``` + +#### Configuration de l'External Secret Operator + +Tout d'abord, configurez un `ClusterSecretStore` qui est chargé de la synchronisation avec le Secret Manager. +Nous configurons le SecretStore en utilisant HashiCorp Vault avec l'authentification par jeton et l'endpoint OKMS en tant que backend. + +Ajoutez le `user_pat` en tant que secret pour pouvoir l'utiliser dans les chartes. + +Pour définir une nouvelle ressource `ClusterSecretStore`, créez un fichier `clustersecretstore.yaml` avec le contenu suivant : + +```yaml +apiVersion: external-secrets.io/v1 +kind: ClusterSecretStore +metadata: + name: vault-secret-store +spec: + provider: + vault: + server: "https://.okms.ovh.net/api/" # endpoint OKMS, remplissez avec la région correcte et votre okms_id + path: "secret" + version: "v2" + auth: + tokenSecretRef: + name: ovhcloud-vault-token # le secret k8s contenant votre PAT + key: token +``` + +> [!info] +> Seule l'[authentification par jeton](https://external-secrets.io/latest/provider/hashicorp-vault/#token-based-authentication) est prise en charge + +> [!info] +> Cette intégration fonctionne également avec un `ClusterSecretStore` + +Le nom de la région peut être traduit à partir de votre emplacement régional en utilisant : + +> [!api] +> +> @api {v1} /location GET /location + +Par exemple, pour **Europe (France - Paris)**, l'endpoint OKMS est **eu-west-par.okms.ovh.net** + +Déployez la ressource dans votre cluster : + +```bash +kubectl apply -f secretstore.yaml +``` + +#### Utilisation de l'External Secret Operator + +Une fois le `ClusterSecretStore` configuré, vous pouvez définir des `ExternalSecret` provenant du gestionnaire de secrets. +Créez un fichier `externalsecret.yaml` avec le contenu suivant : + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: docker-config-secret + namespace: external-secrets +spec: + refreshInterval: 30m + secretStoreRef: + name: vault-secret-store + kind: ClusterSecretStore + target: + template: + type: kubernetes.io/dockerconfigjson + data: + .dockerconfigjson: "{{ .mysecret | toString }}" + name: ovhregistrycred + creationPolicy: Owner + data: + - secretKey: mysecret + remoteRef: + key: prod/va1/dockerconfigjson +``` + +Appliquez la ressource dans votre cluster : + +```bash +kubectl apply -f externalsecret.yaml +``` + +Cela créera un objet de secret Kubernetes. + +```bash +$ kubectl get secret -n external-secrets +NAME TYPE DATA AGE +... +ovhregistrycred kubernetes.io/dockerconfigjson 1 15m +... +``` + +Pour toute information supplémentaire sur la gestion de l'External Secret Operator, veuillez consulter la documentation dédiée, en utilisant le fournisseur HashiCorp Vault : . + +## Aller plus loin + +Rejoignez notre [communauté d'utilisateurs](/links/community). diff --git a/pages/manage_and_operate/secret_manager/external-secret-operator/meta.yaml b/pages/manage_and_operate/secret_manager/external-secret-operator/meta.yaml new file mode 100644 index 00000000000..cc78c7c3cdb --- /dev/null +++ b/pages/manage_and_operate/secret_manager/external-secret-operator/meta.yaml @@ -0,0 +1,3 @@ +id: f1e7d674-2086-49c9-b315-cfe6df0e0781 +full_slug: secret-manager-external-secret-operator +reference_category: manage-operate-secret-manager \ No newline at end of file