Configurar secretos para instancias

Vista previa — Instancias de Cloud Run

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "tal como están" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Es posible que tu instancia requiera claves de API, contraseñas, certificados o cualquier otra información sensible para sus dependencias. Para Cloud Run, Google recomienda almacenar esta información sensible en un secreto que crees en Secret Manager.

Haz que un secreto esté disponible para tus contenedores de una de las siguientes maneras:

• Cuando activas cada secreto como un volumen, Cloud Run lo pone a disposición del contenedor como archivos. Cuando lee un volumen, Cloud Run siempre recupera el valor del secreto de Secret Manager para usarlo con la versión más reciente. Este método también funciona bien con la rotación de secretos.
• Pasa un secreto mediante variables de entorno. Las variables de entorno se resuelven en el momento del inicio de la instancia, por lo que si usas este método, Google te recomienda fijar el secreto en una versión específica en lugar de usar latest como la versión.

Para obtener más información, consulta las prácticas recomendadas de Secret Manager .

Cómo se verifican los secretos en la implementación y el entorno de ejecución

Durante la implementación de la instancia, Cloud Run verifica todos los secretos que usas. La verificación garantiza que la cuenta de servicio que ejecuta el contenedor tenga permiso para acceder a estos secretos.

Durante el tiempo de ejecución, cuando se inician las instancias:

• Si el secreto es una variable de entorno, Cloud Run recupera su valor antes de iniciar la instancia. Si falla el proceso de recuperación del secreto, la instancia no se inicia.
• Si activas el secreto como un volumen, Cloud Run no realiza ninguna verificación durante el inicio de la instancia. Sin embargo, durante el tiempo de ejecución, si no se puede acceder a un secreto, los intentos de leer el volumen activado fallarán.

Propiedad del volumen

La propiedad de un volumen de secretos de Cloud Run difiere según el entorno de ejecución y el tipo de implementación.

Cuando activas un volumen de secretos con el entorno de ejecución de segunda generación, que siempre es el caso de la instancia, la raíz es propietaria del volumen.

Antes de comenzar

1. Habilitar la API de Secret Manager.

   Roles necesarios para habilitar las APIs

   Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

   Habilitar la API

2. Usa un secreto existente o crea uno en Secret Manager, como se describe en Crea un secreto.

Roles obligatorios

Para obtener los permisos que necesitas para configurar los objetos Secret, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Administrador de Cloud Run (roles/run.admin) en la instancia de Cloud Run
• Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) en la identidad del servicio

Para permitir que Cloud Run acceda al Secret, la identidad del servicio debe tener el siguiente rol:

• Descriptor de acceso de secretos de Secret Manager (roles/secretmanager.secretAccessor)

Si deseas obtener instrucciones para agregar el principal de identidad del servicio al rol de descriptor de acceso a secretos de Secret Manager, consulta Administra el acceso a los objetos Secret.

Para obtener una lista de los roles y los permisos de IAM asociados con Cloud Run, consulta los roles de IAM de Cloud Run y los permisos de IAM de Cloud Run. Si tu instancia de Cloud Run interactúa con Google Cloud las APIs, como las bibliotecas cliente de Cloud, consulta la guía de configuración de identidades del servicio. Para obtener más información sobre cómo otorgar roles, consulta permisos de implementación y administra el acceso.

Haz que Cloud Run tenga acceso a un Secret

Puedes hacer que un secreto sea accesible para tu instancia con Google Cloud CLI o YAML cuando implementas una instancia nueva o actualizas una existente instancia:

gcloud

• Para exponer el secreto como una variable de entorno cuando implementas una instancia, ejecuta el siguiente comando:

  gcloud beta run instances deploy INSTANCE \
    --image IMAGE_URL \
    --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

  Reemplaza lo siguiente:

  • INSTANCE: el nombre de tu instancia
  • IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest.
  • ENV_VAR_NAME: el nombre de la variable de entorno que deseas usar con el secreto
  • SECRET_NAME: el nombre del secreto en el mismo proyecto, por ejemplo, mysecret
  • VERSION: la versión del secreto Usa latest para la versión más reciente o un número, por ejemplo, 2.

• Para actualizar varios secretos al mismo tiempo, separa las opciones de configuración de cada secreto con una coma. Con el siguiente comando, se actualiza un secreto activado como un volumen y otro expuesto como una variable de entorno. Para actualizar los secretos existentes, ejecuta el siguiente comando:

  gcloud beta run instances deploy INSTANCE \
  --image IMAGE_URL \
  --update-secrets=PATH=SECRET_NAME:VERSION,ENV_VAR_NAME=SECRET_NAME:VERSION

• Si deseas borrar los secretos existentes y hacer que un servicio nuevo sea accesible para la instancia, usa la marca --set-secrets:

  gcloud beta run instances update INSTANCE \
   --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"

YAML

1. Si creas una instancia nueva, omite este paso. Si actualizas una instancia existente, descarga su configuración de YAML:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. Para los secretos expuestos como variables de entorno:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - image: IMAGE_URL
       env:
       - name: ENV_VAR
         valueFrom:
           secretKeyRef:
             key: SECRET_VERSION
             name: SECRET_NAME

   Reemplaza lo siguiente:

   • INSTANCE: el nombre de tu instancia de Cloud Run
   • IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest
   • ENV_VAR: el nombre de la variable de entorno
   • SECRET_VERSION: la versión del secreto Usa latest para la versión más reciente o un número, por ejemplo, 2.
   • SECRET_NAME: el nombre del secreto, por ejemplo, mysecret

3. Para los secretos activados como rutas de acceso de archivo:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - image: IMAGE_URL
       volumeMounts:
       - name: VOLUME_NAME
         mountPath: MOUNT_PATH
     volumes:
     - name: VOLUME_NAME
       secret:
         secretName: SECRET_NAME
         items:
         - key: SECRET_VERSION
           path: SECRET_NAME

   Reemplaza lo siguiente:

   • INSTANCE: el nombre de tu instancia de Cloud Run
   • IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest.
   • VOLUME_NAME: Cualquier nombre que desees para tu volumen.
   • MOUNT_PATH: La ruta de acceso relativa en la que activarás el volumen, por ejemplo, /mnt/my-volume.
   • SECRET_NAME: el nombre del secreto, por ejemplo, mysecret
   • SECRET_VERSION: la versión del secreto Usa latest para la versión más reciente o un número, por ejemplo, 2.

4. Reemplaza la instancia por la configuración nueva con el siguiente comando:

   gcloud beta run services replace service.yaml

Haz referencia a secretos de otros proyectos

Para hacer referencia a un secreto de otro proyecto, verifica que la cuenta de instancia de tu proyecto tenga acceso al secreto.

gcloud

Para hacer referencia a un secreto como una variable de entorno, ejecuta el siguiente comando:

gcloud beta run instances deploy INSTANCE \
    --image IMAGE_URL \
    --update-secrets=ENV_VAR_NAME=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

Reemplaza lo siguiente:

• INSTANCE: el nombre de tu instancia
• IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest.
• PROJECT_NUMBER: el número de proyecto del proyecto en el que se creó el secreto
• SECRET_NAME: el nombre del secreto, por ejemplo, mysecret.
• VERSION: la versión del secreto Usa latest para la versión más reciente o un número, por ejemplo, 2.

YAML

1. Si creas una instancia nueva, omite este paso. Si actualizas una instancia existente, descarga su configuración de YAML:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. Para los secretos expuestos como variables de entorno:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
       metadata:
         annotations:
           run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
       spec:
         containers:
         - image: IMAGE_URL
           env:
           - name: ENV_VAR
             valueFrom:
               secretKeyRef:
                 key: SECRET_VERSION
                 name: SECRET_LOOKUP_NAME

   Reemplaza lo siguiente:

   • INSTANCE: el nombre de tu instancia de Cloud Run
   • SECRET_LOOKUP_NAME: Cualquier nombre que tenga una sintaxis de nombre de secreto válida, por ejemplo, my-secret. Puede ser igual que SECRET_NAME.
   • PROJECT_NUMBER: el número de proyecto del proyecto en el que se creó el secreto
   • SECRET_NAME: el nombre del secreto, por ejemplo, mysecret
   • IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest
   • ENV_VAR: el nombre de la variable de entorno
   • SECRET_VERSION: la versión del secreto Usa latest para la versión más reciente o un número, por ejemplo, 2.

3. Para los secretos activados como rutas de acceso de archivo:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   metadata:
     annotations:
       run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
   spec:
     containers:
     - image: IMAGE_URL
       volumeMounts:
       - name: VOLUME_NAME
         mountPath: MOUNT_PATH
     volumes:
     - name: VOLUME_NAME
       secret:
         secretName: SECRET_NAME
         items:
         - key: SECRET_VERSION
           path: SECRET_LOOKUP_NAME

   Reemplaza lo siguiente:

   • INSTANCE: el nombre de tu instancia de Cloud Run
   • SECRET_LOOKUP_NAME: Cualquier nombre que tenga una sintaxis de nombre de secreto válida , por ejemplo, my-secret. Puede ser igual que SECRET_NAME.
   • PROJECT_NUMBER: el número de proyecto del proyecto en el que se creó el secreto
   • SECRET_NAME: el nombre del secreto, por ejemplo, mysecret
   • IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest.
   • VOLUME_NAME: Cualquier nombre que desees para tu volumen.
   • MOUNT_PATH: La ruta de acceso relativa en la que activarás el volumen, por ejemplo, /mnt/my-volume.
   • SECRET_VERSION: la versión del secreto Usa latest para la versión más reciente o un número, por ejemplo, 2.

4. Reemplaza la instancia por la configuración nueva con el siguiente comando:

   gcloud beta run instances replace instance.yaml

Visualiza la configuración de los Secrets

Para ver la configuración actual de los Secrets de tu instancia de Cloud Run, sigue estos pasos:

gcloud

1. Usa el siguiente comando:

   gcloud beta run instances describe INSTANCE

2. Busca la configuración de Secrets en la configuración mostrada.

Quita los Secrets de una instancia

Puedes quitar Secrets de una instancia con gcloud CLI:

gcloud

Puedes quitar todos los secretos de una instancia o especificar uno o más secretos para quitarlos.

Para quitar todos los secretos, ejecuta el siguiente comando:

  gcloud beta run instances deploy INSTANCE --image IMAGE_URL \
      --clear-secrets

Reemplaza lo siguiente:

• INSTANCE: el nombre de tu instancia
• IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest.

Para especificar una lista de secretos que deseas quitar, usa la marca --remove-secrets. Con el siguiente comando, se quita un secreto activado como un volumen y otro expuesto como una variable de entorno:

  gcloud beta run instances deploy INSTANCE --image IMAGE_URL \
      --remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH

Reemplaza lo siguiente:

• INSTANCE: el nombre de tu instancia
• IMAGE_URL: una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest.
• ENV_VAR_NAME: el nombre de la variable de entorno

• SECRET_FILE_PATH: la ruta completa del secreto Por ejemplo, /mnt/secrets/primary/latest, en el que /mnt/secrets/primary/ es la ruta de activación y latest es la ruta del secreto. También puedes especificar las rutas de activación y del secreto por separado:

  --set-secrets MOUNT_PATH:SECRET_PATH=SECRET:VERSION

Usa secretos en tu código

Para ver ejemplos sobre cómo acceder a los secretos en tu código como variables de entorno, consulta el instructivo sobre la autenticación de usuario final, en especial la sección Maneja la configuración sensible con Secret Manager.

Limitaciones

En las siguientes secciones, se describen las limitaciones que se aplican a la activación de secretos.

Rutas no permitidas

• Cloud Run no te permite activar secretos en /dev, /proc y /sys, ni en sus subdirectorios.
• Cloud Run no te permite activar varios Secrets en la misma ruta porque dos activaciones de volumen no se pueden activar en la misma ubicación.

Secrets regionales

Cloud Run no admite secretos regionales.

Anula un directorio

Si el Secret se activa como un volumen en Cloud Run y el último directorio en la ruta de activación de volumen ya existe, los archivos o las carpetas en del directorio existente se vuelven inaccesibles.

Por ejemplo, si un Secret llamado my-secret se activa en la ruta de acceso /etc/app_data, se reemplazará todo el contenido dentro del directorio app_data y el único archivo visible es /etc/app_data/my-secret.

Si deseas evitar reemplazar archivos en un directorio existente, crea un directorio nuevo para activar el Secret, por ejemplo, /etc/app_data/secrets, para que la ruta de activación del Secret sea /etc/app_data/secrets/my-secret.