Usa el operador de External Secrets

En esta página, se describe cómo usar el External Secrets Operator (ESO) para sincronizar secretos de Secret Manager con tus clústeres conectados de Google Distributed Cloud.

External Secrets Operator es un operador de Kubernetes de código abierto que integra sistemas externos de administración de secretos. El operador lee información de APIs externas y, luego, inserta automáticamente los valores en un secreto de Kubernetes.

Requisitos previos

Antes de usar External Secrets Operator, debes hacer lo siguiente:

  • Crea un clúster conectado funcional de Distributed Cloud.
  • Verifica que las siguientes APIs estén habilitadas en tu proyecto de Google Cloud . Para obtener información sobre cómo habilitar las APIs, consulta Habilita servicios:
    • secretmanager.googleapis.com
    • iamcredentials.googleapis.com

  • Asegúrate de tener instaladas las siguientes herramientas de línea de comandos:

    • La versión más reciente de Google Cloud CLI, que incluye gcloud, la herramienta de línea de comandos para interactuar con Google Cloud.
    • kubectl

    Si usas Cloud Shell como entorno de shell para interactuar conGoogle Cloud, estas herramientas están instaladas.

  • Asegúrate de haber inicializado la gcloud CLI para usarla en tu proyecto.

  • Habilita la federación de identidades para cargas de trabajo en el clúster. El grupo de identidades para cargas de trabajo está disponible automáticamente y sigue el formato PROJECT_ID.svc.id.goog.

  • Instala el operador de External Secrets en tu clúster. Si deseas obtener instrucciones de instalación, consulta la documentación del operador de External Secrets. Recomendamos instalar el operador en un espacio de nombres dedicado, como external-secrets. No lo instales en espacios de nombres administrados por el sistema, como kube-system o gke-system.

Los clústeres conectados de Distributed Cloud se registran automáticamente en una flota del proyecto en el que se crean.

Autenticación

El operador de External Secrets requiere autenticación para acceder a Secret Manager. Distributed Cloud connected usa la federación de identidades para cargas de trabajo de la flota para permitir que las cargas de trabajo se autentiquen en las APIs deGoogle Cloud .

Para configurar la autenticación del operador de External Secrets, sigue estos pasos:

  1. Configura la relación de confianza entre tu clúster y Google Cloud siguiendo las instrucciones en Autenticación de clústeres de Workload Identity.
  2. Asegúrate de que la cuenta de servicio de Google que usa External Secrets Operator tenga el rol Descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) en los secretos a los que deseas acceder.

  3. Sigue las instrucciones de Configura la carga de trabajo para configurar el Pod del operador de External Secrets para que use la federación de identidades para cargas de trabajo.

    La mayoría de los clientes usan la federación de identidades para cargas de trabajo para la autenticación. Para configurar la federación de identidades para cargas de trabajo, debes anotar el ServiceAccount de Kubernetes que usa el operador con la cuenta de servicio de Google. Para agregar esta anotación, ejecuta el comando kubectl annotate:

    kubectl annotate serviceaccount KSA_NAME \
    --namespace OPERATOR_NAMESPACE \
    iam.gke.io/gcp-service-account=GSA_EMAIL

    Como alternativa, puedes agregar la anotación a tu archivo YAML de ServiceAccount:

    apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    iam.gke.io/gcp-service-account: GSA_EMAIL
  name: KSA_NAME
  namespace: OPERATOR_NAMESPACE

    Reemplaza los siguientes valores:

    • KSA_NAME: Es el nombre de la ServiceAccount de Kubernetes que usa el operador.
    • OPERATOR_NAMESPACE: Es el espacio de nombres en el que instalaste el operador.
    • GSA_EMAIL: La dirección de correo electrónico de la cuenta de servicio de Google

  4. Proporciona el archivo de configuración de credenciales al Pod del operador. Para obtener más información, consulta Configura la carga de trabajo.

Crea recursos de ESO para sincronizar secretos

Después de configurar la autenticación, puedes crear recursos del operador de External Secrets para sincronizar secretos.

Crear una SecretStore

Un SecretStore especifica cómo acceder al sistema externo de administración de secretos. Puedes crear recursos SecretStore en el mismo espacio de nombres que el operador de External Secrets o en los espacios de nombres de la aplicación. Para obtener más información, consulta SecretStore en la documentación de Kubernetes.

  1. Crea un archivo llamado secret-store.yaml con el siguiente contenido:

    apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: gcp-store
  namespace: NAMESPACE
spec:
  provider:
    gcpsm:
      projectID: PROJECT_ID

    Reemplaza los siguientes valores:

    • NAMESPACE: Es el espacio de nombres en el que deseas crear el SecretStore.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud en el que se almacenan los secretos.

  2. Usa el comando kubectl apply para aplicar el manifiesto:

    kubectl apply -f secret-store.yaml

Crear una ClusterSecretStore

Un ClusterSecretStore es un recurso con alcance de clúster que los recursos ExternalSecret pueden usar en cualquier espacio de nombres. Para obtener más información, consulta ClusterSecretStore en la documentación de Kubernetes.

  1. Crea un archivo llamado cluster-secret-store.yaml con el siguiente contenido:

    apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: gcp-cluster-store
spec:
  provider:
    gcpsm:
      projectID: PROJECT_ID

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud en el que se almacenan los secretos.

  2. Aplica el manifiesto

    kubectl apply -f cluster-secret-store.yaml

Crea un ExternalSecret

Un ExternalSecret declara qué datos recuperar y dónde almacenarlos en el clúster. Crea recursos ExternalSecret en el espacio de nombres en el que los Pods de la aplicación consumen el objeto Secret de Kubernetes resultante. Para obtener más información, consulta ExternalSecret en la documentación de Kubernetes.

  1. Crea un archivo llamado external-secret.yaml con el siguiente contenido:

    apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: EXTERNAL_SECRET
  namespace: NAMESPACE
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: gcp-store
  target:
    name: K8S_SECRET_NAME
    creationPolicy: Owner
  data:
  - secretKey: K8S_SECRET_KEY
    remoteRef:
      key: SECRET_NAME

    Reemplaza los siguientes valores:

    • EXTERNAL_SECRET: El nombre del recurso ExternalSecret.
    • NAMESPACE: Es el espacio de nombres en el que creaste el SecretStore.
    • K8S_SECRET_NAME: Es el nombre del Secret de Kubernetes que creará ESO.
    • K8S_SECRET_KEY: Es la clave en los datos del Secret de Kubernetes.
    • SECRET_NAME: Es el nombre del secreto enGoogle Cloud Secret Manager.

    Si usas un ClusterSecretStore, configura kind: ClusterSecretStore y actualiza name en secretStoreRef.

  2. Aplica el manifiesto

    kubectl apply -f external-secret.yaml

Sincroniza varias claves desde un secreto JSON

Si tu Secret en Secret Manager contiene una cadena JSON, puedes extraer todas las claves como entradas individuales en el Secret de Kubernetes.

  1. Crea un archivo llamado external-secret-json.yaml con el siguiente contenido:

    apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: EXTERNAL_SECRET
  namespace: NAMESPACE
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: gcp-store
  target:
    name: K8S_SECRET_NAME
    creationPolicy: Owner
  dataFrom:
  - extract:
      key: SECRET_NAME

  2. Aplica el manifiesto

    kubectl apply -f external-secret-json.yaml

Cada par clave-valor del secreto JSON se asigna a un par clave-valor en el secreto de Kubernetes resultante.

Soluciona problemas

Si tus secretos no se sincronizan, sigue estos pasos para solucionar el problema:

  1. Usa el comando kubectl get para verificar el estado del recurso ExternalSecret:

    kubectl get externalsecret EXTERNAL_SECRET -n NAMESPACE -o yaml

    Examina la sección status para ver si hay mensajes de error o condiciones fallidas.

  2. Usa el comando kubectl logs para verificar los registros del Pod del controlador del operador de External Secrets:

    kubectl logs -l app.kubernetes.io/name=external-secrets -n OPERATOR_NAMESPACE

  3. Verifica que la cuenta de servicio de Kubernetes que usa el operador esté anotada correctamente con el correo electrónico de la cuenta de servicio de Google. Para obtener más información, consulta Federación de identidades para cargas de trabajo en el clúster.

  4. Verifica que la cuenta de servicio de Google tenga los permisos necesarios y que la federación de identidades para cargas de trabajo esté configurada correctamente. Para obtener más información, consulta Federación de identidades para cargas de trabajo en el clúster.

¿Qué sigue?