Configurar variables de entorno para servicios

En esta página se describe cómo configurar variables de entorno para tu servicio de Cloud Run.

Puedes usar variables de entorno para la configuración de servicios, pero no las recomendamos como forma de almacenar secretos, como credenciales de bases de datos o claves de API. Los valores sensibles deben almacenarse fuera del código fuente y de las variables de entorno. Para almacenar secretos, te recomendamos que uses Secret Manager. Para configurar los servicios para acceder a los secretos almacenados en Secret Manager, consulta Configurar secretos.

Cualquier cambio en la configuración conlleva la creación de una nueva revisión. Las revisiones posteriores también recibirán automáticamente este ajuste de configuración, a menos que hagas cambios explícitos para modificarlo.

Roles obligatorios

Para obtener los permisos que necesitas para configurar e implementar servicios de Cloud Run, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

• Desarrollador de Cloud Run (roles/run.developer) en el servicio Cloud Run
• Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la identidad de servicio

Si vas a desplegar un servicio o una función a partir de código fuente, también debes tener otros roles concedidos en tu proyecto y en la cuenta de servicio de Cloud Build.

Para ver una lista de los roles y permisos de gestión de identidades y accesos asociados a Cloud Run, consulta los artículos sobre roles de gestión de identidades y accesos de Cloud Run y permisos de gestión de identidades y accesos de Cloud Run. Si tu servicio de Cloud Run interactúa con APIs, como las bibliotecas de cliente de Cloud, consulta la guía de configuración de la identidad del servicio.Google Cloud Para obtener más información sobre cómo conceder roles, consulta los artículos sobre permisos de implementación y gestión del acceso.

Advertencia: Si tu servicio de Cloud Run usa la identidad de servicio para autenticar el acceso a las APIs de Google Cloud , nunca definas GOOGLE_APPLICATION_CREDENTIALS como variable de entorno en un servicio de Cloud Run. Configura siempre una cuenta de servicio gestionada por el usuario.

Número máximo de variables de entorno y límites

Puedes definir un máximo de 1000 variables de entorno para un servicio de Cloud Run.

La longitud variable máxima es de 32 kB.

Establece variables de entorno:

Puedes definir variables de entorno para servicios nuevos y actuales. Ten en cuenta que la marca --set-env-vars es una acción destructiva que elimina las variables de entorno definidas anteriormente que no se incluyan en la nueva lista de variables de entorno.

Las variables de entorno están vinculadas a una revisión de servicio específica y no son visibles para otros servicios de tu proyecto de Google Cloud .

Puedes definir variables de entorno mediante la Google Cloud consola, la CLI de gcloud o un archivo YAML cuando creas un servicio o despliegas una revisión:

Consola

1. En la Google Cloud consola, ve a Cloud Run:

   Ir a Cloud Run

2. Seleccione Servicios en el menú y haga clic en Implementar contenedor para configurar un nuevo servicio. Si vas a configurar un servicio que ya tienes, haz clic en él y, a continuación, en Editar y desplegar nueva revisión.

3. Si vas a configurar un servicio nuevo, rellena la página de configuración inicial del servicio y, a continuación, haz clic en Contenedores, volúmenes, redes y seguridad para desplegar la página de configuración del servicio.

4. Haz clic en la pestaña Contenedor.

   

   • En la pestaña Variables y secretos, haz clic en Añadir variable para añadir una variable nueva y especifica el nombre que quieras darle y su valor en los campos Nombre y Valor. Para obtener más información sobre cómo definir varias variables de entorno o escapar caracteres especiales, consulta Definir varias variables de entorno.

5. Haz clic en Crear o en Implementar.

gcloud

Nota: Si usas la CLI de gcloud para desplegar una función, debes especificar las marcas obligatorias al ejecutar gcloud run deploy y tener los roles necesarios.

Para especificar variables de entorno al implementar tu servicio, usa la marca --set-env-vars:

gcloud run deploy SERVICE --image IMAGE_URL --set-env-vars KEY1=VALUE1,KEY2=VALUE2

Haz los cambios siguientes:

• SERVICE: el nombre de tu servicio.
• KEY1=VALUE1,KEY2=VALUE2: lista de nombres y valores de variables separados por comas.
• IMAGE_URL: una referencia a la imagen del contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME ya debe estar creado. La URL sigue el formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

Para obtener más información sobre cómo definir varias variables de entorno o escapar caracteres especiales, consulta Definir varias variables de entorno.

YAML

1. Si va a crear un servicio, puede saltarse este paso. Si va a actualizar un servicio, descargue su configuración YAML:

   gcloud run services describe SERVICE --format export > service.yaml

2. Actualice los atributos name y value del atributo env en containers::

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       metadata:
         name: REVISION
       spec:
         containers:
         - image: IMAGE
           env:
           - name: KEY-1
             value: VALUE-1
           - name: KEY-N
             value: VALUE-N

   Haz los cambios siguientes:

   • SERVICE: el nombre de tu servicio de Cloud Run.
   • IMAGE_URL: una referencia a la imagen del contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME ya debe estar creado. La URL sigue el formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
   • KEY-1, VALUE-1: la variable de entorno y el valor. También puede añadir más variables y valores según sea necesario.
   • REVISION con un nuevo nombre de revisión o elimínelo (si está presente). Si proporcionas un nuevo nombre de revisión, debe cumplir los siguientes criterios:
     • Empieza por SERVICE-
     • Contiene solo letras minúsculas, números y -
     • No termina con -
     • No supera los 63 caracteres

3. Crea o actualiza el servicio con el siguiente comando:

   gcloud run services replace service.yaml

Terraform

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform.

Añade lo siguiente a un recurso google_cloud_run_v2_service en tu configuración de Terraform:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-env-var"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      # Environment variables
      env {
        name  = "foo"
        value = "bar"
      }
      env {
        name  = "baz"
        value = "quux"
      }
    }
  }
}

El recurso google_cloud_run_v2_service anterior especifica que la variable de entorno foo se define como bar y que la variable de entorno baz se define como quux. Actualice las variables de entorno según sea necesario.

Definir variables de entorno predeterminadas en el contenedor

Puedes usar la instrucción ENV en un Dockerfile para definir valores predeterminados para las variables de entorno:

ENV KEY1=VALUE1,KEY2=VALUE2

Orden de prioridad: variables de contenedor frente a variables de servicio

Si define una variable de entorno predeterminada en el contenedor y también define una variable de entorno con el mismo nombre en el servicio de Cloud Run, prevalecerá el valor definido en el servicio.

Definir varias variables de entorno

Puedes definir varias variables de entorno mediante el archivo .env o la marca --set-env-vars.

Definir varias variables de entorno con el archivo .env

Preview — Set multiple environment variables using the .env file

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Consola

1. En la Google Cloud consola, ve a Cloud Run:

   Ir a Cloud Run

2. Seleccione Servicios en el menú y haga clic en Implementar contenedor para configurar un nuevo servicio. Si vas a configurar un servicio que ya tienes, haz clic en él y, a continuación, en Editar y desplegar nueva revisión.

3. Si vas a configurar un servicio nuevo, rellena la página de configuración inicial del servicio y, a continuación, haz clic en Contenedores, volúmenes, redes y seguridad para desplegar la página de configuración del servicio.

4. Haz clic en la pestaña Contenedor.

   

   • En la pestaña Variables y secretos, haz clic en Añadir variable y pega el contenido de tu archivo .env en el campo Nombre. Cloud Run rellena automáticamente el campo Valor y crea variables para cada par clave-valor que definas en el archivo .env.

5. Haz clic en Crear o en Implementar.

gcloud

Para especificar varias variables de entorno desde el archivo .env, ejecuta el siguiente comando:

gcloud beta run deploy SERVICE --image=IMAGE_URL --env-vars-file=ENV_FILE_PATH

Haz los cambios siguientes:

• SERVICE: el nombre de tu servicio de Cloud Run.
• IMAGE_URL: una referencia a la imagen del contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME ya debe estar creado. La URL sigue el formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
• ENV_FILE_PATH: ruta al archivo .env.

Definir varias variables de entorno con la marca --set-env-vars

Si tienes varias variables de entorno que no se pueden enumerar en el formato KEY1=VALUE1,KEY2=VALUE2, puedes repetir la marca --set-env-vars varias veces:

   [...]
   --set-env-vars "KEY1=VALUE1" \
   --set-env-vars "KEY2=VALUE2" \
   --set-env-vars "KEY3=VALUE3"

Evitar caracteres de coma

Como el carácter de coma , se usa para dividir las variables de entorno, si tu variable de entorno contiene comas como valores, debes escapar esos delimitadores especificando otro carácter delimitador, por ejemplo, @:

--set-env-vars "^@^KEY1=value1,value2,value3@KEY2=..."

Actualizar variables de entorno

Puedes actualizar las variables de entorno de los servicios que ya tengas. Se trata de un enfoque no destructivo que cambia o añade variables de entorno, pero no elimina las que se hayan definido anteriormente.

Consola

Para actualizar las variables de entorno mediante la consola Google Cloud , sigue estos pasos:

1. En la Google Cloud consola, ve a Cloud Run:

   Ir a Cloud Run

2. Selecciona tu servicio en la lista y haz clic en Editar y desplegar nueva revisión.

3. Haz clic en la pestaña Contenedor.

4. En la pestaña Variables y secretos, edita los campos Nombre o Valor y haz clic en Hecho.

5. Haz clic en Desplegar.

gcloud

Nota: Si usas la CLI de gcloud para desplegar una función, debes especificar las marcas obligatorias al ejecutar gcloud run deploy y tener los roles necesarios.

Para actualizar las variables de entorno de un servicio, usa la marca --update-env-vars:

gcloud run services update SERVICE --update-env-vars KEY1=VALUE1,KEY2=VALUE2

Haz los cambios siguientes:

• SERVICE: el nombre de tu servicio.
• KEY1=VALUE1,KEY2=VALUE2: lista separada por comas de nombres y valores de variables.

Para actualizar las variables de entorno de un servicio multirregional, usa el comando gcloud beta run multi-region-services update.

Ver la configuración de las variables de entorno

Para ver la configuración actual de las variables de entorno de tu servicio de Cloud Run, sigue estos pasos:

Consola

1. En la Google Cloud consola, ve a Cloud Run:

   Ir a Cloud Run

2. Haz clic en el servicio que te interese para abrir la página Detalles del servicio.

3. Haz clic en la pestaña Revisiones.

4. En el panel de detalles de la derecha, el ajuste de variables de entorno se encuentra en la pestaña Contenedor.

gcloud

1. Usa el siguiente comando:

   gcloud run services describe SERVICE

2. Busca la configuración de las variables de entorno en la configuración devuelta.

Eliminar variables de entorno

Puede eliminar variables de entorno de los servicios que ya tenga.

Consola

Para eliminar variables de entorno con la consola Google Cloud , sigue estos pasos:

1. En la Google Cloud consola, ve a Cloud Run:

   Ir a Cloud Run

2. Selecciona tu servicio en la lista y haz clic en Editar y desplegar nueva revisión.

3. Haz clic en la pestaña Contenedor.

4. En la pestaña Variables y secretos, mueve el cursor a la izquierda del campo Valor de la variable de entorno que vas a quitar para que se muestre el icono Eliminar y haz clic en él.

5. Haz clic en Listo.

6. Haz clic en Desplegar.

gcloud

Nota: Si usas la CLI de gcloud para desplegar una función, debes especificar las marcas obligatorias al ejecutar gcloud run deploy y tener los roles necesarios.

Para eliminar de forma selectiva las variables de entorno de un servicio,usa la marca --remove-env-vars:

gcloud run services update SERVICE --remove-env-vars KEY1,KEY2

Haz los cambios siguientes:

• SERVICE: el nombre de tu servicio.
• KEY1,KEY2: lista de nombres de variables separados por comas.

También puedes borrar todas las variables de entorno definidas anteriormente con la marca --clear-env-vars:

gcloud run services update SERVICE --clear-env-vars

Sustituye SERVICE por el nombre de tu servicio.

Prácticas recomendadas

En la siguiente sección se destacan algunas de las prácticas recomendadas para configurar variables de entorno.

Variables de entorno reservadas para servicios

Las variables de entorno definidas en el contrato de tiempo de ejecución del contenedor están reservadas y no se pueden definir. En concreto, Cloud Run inserta la variable de entorno PORT en tu contenedor. No deberías configurarlo tú mismo.

Variables de entorno reservadas adicionales al desplegar funciones

Cloud Run define automáticamente las siguientes variables de entorno de ejecución al desplegar funciones:

• FUNCTION_TARGET: la función que se va a ejecutar.
• FUNCTION_SIGNATURE_TYPE: el tipo de función: http para funciones HTTP y event para funciones basadas en eventos.

Algunas variables de entorno adicionales se definen automáticamente en función del tiempo de ejecución que use tu función. Se basan en el sistema operativo del tiempo de ejecución (por ejemplo, DEBIAN_FRONTEND, SHLVL o PATH) y en el tiempo de ejecución del lenguaje (por ejemplo, NODE_ENV, VIRTUAL_ENV o GOPATH).

Las variables de entorno proporcionadas por el entorno, distintas de las que se definen automáticamente, pueden cambiar en futuras versiones del tiempo de ejecución. Como práctica recomendada, te aconsejamos que no dependas de ninguna variable de entorno que no hayas definido explícitamente ni la modifiques.

Si modificas las variables de entorno proporcionadas por el entorno, es posible que se produzcan resultados impredecibles. Los intentos de modificar estas variables de entorno podrían bloquearse o, lo que es peor, provocar consecuencias no deseadas, como que no se puedan iniciar funciones. Como práctica recomendada, considera la posibilidad de añadir un prefijo a las variables de entorno con una clave única para evitar conflictos.

Variables de entorno no válidas

No puedes usar las siguientes variables de entorno:

Clave	Descripción
Vacío ('')	Las claves no pueden ser cadenas vacías.
=	Las claves no pueden contener el carácter "=".
X_GOOGLE_	Las claves no pueden contener el prefijo X_GOOGLE_.

Código de muestra

Para ver un ejemplo de código que muestra cómo acceder a las variables de entorno en tu código, consulta Gestionar la configuración sensible con Secret Manager en el tutorial Autenticación de usuarios finales.

Siguientes pasos

Puedes usar variables de entorno para definir la configuración de buildpacks. Para obtener información específica sobre cada lenguaje, consulta la documentación de los buildpacks de:

• Node.js
• Python
• Go
• Ruby
• PHP
• Java

Si vas a implementar desde la fuente y necesitas personalizar variables en tiempo de compilación, consulta Definir variables de entorno de compilación.