Using secrets

You can use Secret Manager to securely store API keys, passwords, and other sensitive information. This guide shows you how to configure Cloud Functions to access secrets stored in Secret Manager.

This document covers both ways of making a secret available to your function:

  • Mounting the secret as a volume. This makes the secret available to the function as a file. If you reference a secret as a volume, your function accesses the secret value from Secret Manager each time the file is read from disk. This makes mounting as a volume a good strategy if you want to reference the latest version of the secret instead of a pinned version of the secret. This method also works well if you plan to implement secret rotation.

  • Passing the secret as an environment variable. Environment variable values are resolved at instance startup time, so if you use this method, we recommend referencing a pinned version of the secret instead of referencing the latest version of the secret.

For more information on using Secret Manager, see the Secret Manager overview.

Before you begin

  1. Enable the Secret Manager API.

    Enable the API

  2. If you haven't already, create a secret in Secret Manager. To learn how to create and access secrets, see Creating a secret.

Granting access to secrets

Your function can access secrets that reside in the same project as the function as well as secrets that reside in another project. To access a secret, the function's runtime service account must be granted access to the secret.

By default, Cloud Functions uses the App Engine default service account to authenticate with Secret Manager. For production use, Google recommends that you configure your function to authenticate using a user-managed service account that is assigned the least-permissive set of roles required to accomplish that function's tasks.

To use Secret Manager with Cloud Functions, assign the roles/secretmanager.secretAccessor role to the service account associated with your function:

  1. Go to the Secret Manager page in the Cloud Console:
    Go to the Secret Manager page

  2. Click the name of a secret.

  3. If it is not already open, click Show Info Panel to open the panel.

  4. In the info panel, click Add principal.

  5. In the New principals field, enter the service account your function uses for its identity. The function's service account is one of the following:

  6. In the Select a role dropdown, choose Secret Manager and then Secret Manager Secret Accessor.

Making a secret accessible to a function

In order to reference a secret from a function, you must first make the secret accessible to the function. You can make a secret accessible to new or existing functions using either the Google Cloud Console or the gcloud command-line tool:

Console

To make a secret accessible to a function:

  1. Go to the Cloud Functions page in the Google Cloud Console:
    Go to the Cloud Functions page

  2. Click the name of the function you want to be able to access a secret.

  3. Click Edit.

  4. Click Runtime, build and connections settings to expand the advanced configuration options.

  5. Click Security to open the security tab.

  6. Click Reference a secret to set a secret for the function.

  7. Select the secret to make accessible. If you need to create a secret, see Creating and accessing secrets.

    • To reference a secret in the same project as your function:

      1. Select the secret from the dropdown list.
    • To reference a secret from another project:

      1. Verify that your project's service account has been granted access to the secret.

      2. Select Don't see your secret? Enter secret resource ID.

      3. Enter the secret's resource ID in the following format:

        project/PROJECT_ID/secrets/SECRET_NAME

        Replace the following:

        • PROJECT_ID: The ID of the project where the secret resides.

        • SECRET_NAME: The name of the secret in Secret Manager.

  8. Select the reference method for the secret. You can mount the secret as a volume or expose the secret as an environment variable.

    • To mount the secret as a volume:

      1. Select Mounted as volume.

      2. In the Mount path field, enter the path to use for your secret.

      3. From the Version dropdown, select the version of the secret to reference.

    • To expose the secret as an environment variable:

      1. Select Exposed as environment variable.

      2. In the Mount path field, enter the path to use for your secret.

      3. From the Version dropdown, select the version of the secret to reference.

  9. Click Done.

  10. Click Next.

  11. Click Deploy.

Your function's code can now reference the secret.

gcloud

To make a secret accessible to a function, enter one of the following commands.

  • To mount the secret as a volume, enter the following command:

    gcloud beta functions deploy FUNCTION_NAME \
    --runtime RUNTIME \
    --set-secrets 'SECRET_FILE_PATH=SECRET:VERSION'
    

    Replace the following:

    • FUNCTION_NAME: The name of your function.

    • RUNTIME: The runtime in which to run your function.

    • SECRET_FILE_PATH: The full path of the secret. For example, /etc/secrets/primary/latest, where /etc/secrets/primary/ is the mount path and /latest/ is the secret path. You can also specify the mount and secret paths separately:

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

    • SECRET: The name of the secret in Secret Manager.

    • VERSION: The version of the secret to use. For example, 1 or latest.

    The --set-secrets flag overrides any existing secrets. To keep the function's existing secrets, use the --update-secrets flag instead.

  • To expose the secret as an environment variable, enter the following command:

    gcloud beta functions deploy FUNCTION_NAME \
    --runtime RUNTIME \
    --set-secrets 'ENV_VAR_NAME=SECRET:VERSION'
    

    Replace the following:

    • FUNCTION_NAME: The name of your function.

    • RUNTIME: The runtime in which to run your function.

    • ENV_VAR_NAME: The name of the environment variable.

    • SECRET: The name of the secret in Secret Manager.

    • VERSION: The version of the secret to use. For example, 1 or latest.

    The --set-secrets flag overrides any existing secrets. To keep the function's existing secrets, use the --update-secrets flag instead.

  • You can reference a secret from another project if the function's service account has been granted access to the secret. To reference a secret from another project, use the secret's resource path:

    gcloud beta functions deploy FUNCTION_NAME \
    --runtime RUNTIME \
    --update-secrets 'SECRET_FILE_PATH=SECRET_RESOURCE_PATH:VERSION'
    

    Replace the following:

    • FUNCTION_NAME: The name of your function.

    • SECRET_RESOURCE_PATH: The resource path for the secret residing in another project. The resource path uses the following format:

      project/PROJECT_ID/secrets/SECRET_NAME

      Replace the following:

      • PROJECT_ID: The ID of the project where the secret resides.

      • SECRET_NAME: The name of the secret in Secret Manager.

    • RUNTIME: The runtime in which to run your function.

    • SECRET_FILE_PATH: The full path of the secret. For example, /etc/secrets/primary/latest, where /etc/secrets/primary/ is the mount path and /latest/ is the secret path. You can also specify the mount and secret paths separately:

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

    • SECRET: The name of the secret in Secret Manager.

    • VERSION: The version of the secret to use. For example, 1 or latest.

  • You can update multiple secrets at once. Separate the configuration options for each secret with a comma. The following command updates one secret mounted as a volume and another secret exposed as an environment variable.

    To update existing secrets, enter the following command:

    gcloud beta functions deploy FUNCTION_NAME \
    --runtime RUNTIME \
    --update-secrets 'ENV_VAR_NAME=SECRET:VERSION, \
    SECRET_FILE_PATH=SECRET:VERSION'
    

    Replace the following:

    • FUNCTION_NAME: The name of your function.

    • RUNTIME: The runtime in which to run your function.

    • ENV_VAR_NAME: The name of the environment variable.

    • SECRET: The name of the secret in Secret Manager.

    • VERSION: The version of the secret to use. For example, 1 or latest.

    • SECRET_FILE_PATH: The full path of the secret. For example, /etc/secrets/primary/latest, where /etc/secrets/primary/ is the mount path and /latest/ is the secret path. You can also specify the mount and secret paths separately:

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

Removing secrets from a function

You can remove secrets from a function using either the Cloud Console or the gcloud tool:

Console

  1. Go to the Cloud Functions page in the Google Cloud Console:
    Go to the Cloud Functions page

  2. Click the name of the function to remove one of its secret.

  3. Click Edit.

  4. Click Runtime, build and connections settings to expand the advanced configuration options.

  5. Click Security to open the security tab.

  6. Hover over the secret you want to remove, then click Delete.

  7. Click Next.

  8. Click Deploy.

gcloud

You can remove all secrets from a function or specify one or more secrets to remove:

  • To remove all secrets, run the following command:

    gcloud beta functions deploy FUNCTION_NAME \
    --runtime RUNTIME \
    --clear-secrets
    

    Replace the following:

    • FUNCTION_NAME: The name of your function.

    • RUNTIME: The runtime in which to run your function.

    All secrets are cleared from the function.

  • To specify a list of secrets to remove, use the --remove-secrets flag. The following command removes one secret mounted as a volume and another secret exposed as an environment variable:

    gcloud beta functions deploy FUNCTION_NAME \
    --runtime RUNTIME \
    --remove-secrets='ENV_VAR_NAME,SECRET_FILE_PATH, ...'
    

    Replace the following:

    • FUNCTION_NAME: The name of your function.

    • RUNTIME: The runtime in which to run your function.

    • ENV_VAR_NAME: The name of the environment variable.

    • SECRET_FILE_PATH: The full path of the secret. For example, /etc/secrets/primary/latest, where /etc/secrets/primary/ is the mount path and /latest/ is the secret path. You can also specify the mount and secret paths separately:

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

    The specified secrets are removed from the function.

Viewing your function's accessible secrets

You can see which secrets your function can currently access using either the Cloud Console or the gcloud tool:

Console

  1. Go to the Cloud Functions page in the Google Cloud Console:
    Go to the Cloud Functions page

  2. Click the name of the function to see its available secrets.

  3. Click Edit.

  4. Click Runtime, build and connections settings to expand the advanced configuration options.

  5. Click Security to open the security tab.

The security tab lists the secrets currently accessible to your function.

gcloud

To see what secrets are available to your function, use the gcloud beta functions describe command:

gcloud beta functions describe FUNCTION_NAME

Replace FUNCTION_NAME with the name of your function.

What's next