Use Secret Manager add-on to access parameters

This page describes how applications running on Google Kubernetes Engine (GKE) can use the Secret Manager add-on to access configuration parameters (including embedded secrets) that are stored externally in Parameter Manager.

Applications often require configuration parameters (like database addresses, server settings) and secrets (like API keys, passwords, security tokens). Instead of directly embedding configurations and secrets within pod definitions or container images, you can store them securely in Parameter Manager. At runtime, the Secret Manager add-on automatically grabs the data from Parameter Manager and makes it appear as a file inside your app's container. Your GKE pods can access the necessary configuration and secret payloads from Parameter Manager as if they were local files.

The Secret Manager add-on includes the following:

• The open source Kubernetes Secrets Store CSI Driver.
• The Google Secret Manager provider for Secret Manager and Parameter Manager services.

The Secret Manager add-on is derived from the open source Kubernetes Secrets Store CSI Driver and the Google Secret Manager provider. If you're using the open source Secrets Store CSI Driver to access secrets, you can migrate to the Secret Manager add-on. For information, see Migrate from the existing Secrets Store CSI Driver.

Benefits

The Secret Manager add-on provides the following benefits:

• You don't have to write custom code to get your parameters.
• It's simpler to access parameters because the support is already built into the system.

Before you begin

• Enable the Parameter Manager and Google Kubernetes Engine APIs.

  Enable the APIs

• If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running the gcloud components update command.

  You can't manually set up the Secret Manager add-on using the Google Cloud SDK or the Google Cloud console.

• Ensure that your cluster runs GKE version 1.33.3-gke.1136000 or later with a Linux node image.

• If you use a GKE Standard cluster, ensure that your cluster has Workload Identity Federation for GKE enabled. Workload Identity Federation for GKE is enabled by default on an Autopilot cluster. Kubernetes Pods use Workload Identity Federation for GKE to authenticate to the Parameter Manager API.

Enable the Secret Manager add-on

You can enable the Secret Manager add-on on both Standard clusters as well as Autopilot clusters.

Enable the Secret Manager add-on on a new GKE cluster

To enable the Secret Manager add-on on cluster creation, do the following:

gcloud container clusters create CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \
    --cluster-version=VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog

gcloud container clusters create CLUSTER_NAME `
    --enable-secret-manager `
    --location=LOCATION `
    --cluster-version=VERSION `
    --workload-pool=PROJECT_ID.svc.id.goog

gcloud container clusters create CLUSTER_NAME ^
    --enable-secret-manager ^
    --location=LOCATION ^
    --cluster-version=VERSION ^
    --workload-pool=PROJECT_ID.svc.id.goog

gcloud container clusters create-auto CLUSTER_NAME \
    --enable-secret-manager \
    --cluster-version=VERSION \
    --location=LOCATION

gcloud container clusters create-auto CLUSTER_NAME `
    --enable-secret-manager `
    --cluster-version=VERSION `
    --location=LOCATION

gcloud container clusters create-auto CLUSTER_NAME ^
    --enable-secret-manager ^
    --cluster-version=VERSION ^
    --location=LOCATION

After you have enabled the Secret Manager add-on, you can use the Secrets Store CSI Driver in Kubernetes volumes using the driver and provisioner name: secrets-store-gke.csi.k8s.io.

Enable the Secret Manager add-on on an existing GKE cluster

To enable the Secret Manager add-on on an existing cluster, do the following:

gcloud container clusters update CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \

gcloud container clusters update CLUSTER_NAME `
    --enable-secret-manager `
    --location=LOCATION `

gcloud container clusters update CLUSTER_NAME ^
    --enable-secret-manager ^
    --location=LOCATION ^

Verify the Secret Manager add-on installation

To verify that the Secret Manager add-on is installed on the Kubernetes cluster, run the following command:

  gcloud container clusters describe CLUSTER_NAME --location LOCATION | grep secretManagerConfig -A 4

Replace the following:

• CLUSTER_NAME: the name of the cluster
• LOCATION: the location of your cluster, such as us-central1

Configure applications to authenticate to the Parameter Manager API

The Google Secret Manager provider uses the workload identity of the Pod that a secret is mounted onto when authenticating to the Parameter Manager API. To allow your applications to authenticate to the Parameter Manager API using Workload Identity Federation for GKE, follow these steps:

• Create a new Kubernetes ServiceAccount or use an existing Kubernetes ServiceAccount in the same namespace as the Pod onto which you want to mount the parameters.

• Create an Identity and Access Management (IAM) allow policy for the parameter in Parameter Manager.

Pods that use the configured Kubernetes ServiceAccount automatically authenticate as the IAM principal identifier that corresponds to the Kubernetes ServiceAccount when accessing the Parameter Manager API.

Create a new Kubernetes ServiceAccount

1. Save the following manifest as service-account.yaml:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: KSA_NAME
     namespace: NAMESPACE
   

   Replace the following:

   • KSA_NAME: the name of your new Kubernetes ServiceAccount
   • NAMESPACE: the name of the Kubernetes namespace for the ServiceAccount

2. Apply the manifest:

   kubectl apply -f service-account.yaml
   

3. Create an IAM allow policy that references the new Kubernetes ServiceAccount and grant it permission to access the parameter:

   gcloud projects add-iam-policy-binding PARAMETER_PROJECT_ID \
       --role=roles/parametermanager.parameterAccessor \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
   

   Replace the following:

   • PARAMETER_PROJECT_ID: the ID of the project where the parameter is stored. This can be the same as the PROJECT_ID if the parameter is stored in the same project as the GKE cluster.
   • PROJECT_NUMBER: your numerical Google Cloud project number.
   • PROJECT_ID: the project ID of the Google Cloud project that contains your GKE cluster.
   • NAMESPACE: the name of the Kubernetes namespace for the ServiceAccount.
   • KSA_NAME: the name of the new Kubernetes ServiceAccount.

Use an existing Kubernetes ServiceAccount

Create an IAM allow policy that references the existing Kubernetes ServiceAccount and grant it permission to access the parameter:

gcloud projects add-iam-policy-binding PARAMETER_PROJECT_ID \
    --role=roles/parametermanager.parameterAccessor \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME

Replace the following:

• PARAMETER_PROJECT_ID: the ID of the project where the parameter is stored. This can be the same as the PROJECT_ID if the parameter is stored in the same project as the GKE cluster.
• PROJECT_NUMBER: your numerical Google Cloud project number.
• PROJECT_ID: the project ID of the Google Cloud project that contains your GKE cluster.
• NAMESPACE: the name of the Kubernetes namespace for the ServiceAccount.
• KSA_NAME: the name of your existing Kubernetes ServiceAccount.

Define which parameters to mount

To specify which parameters to mount as files in the Kubernetes Pod, create a SecretProviderClass YAML manifest and list the parameters to mount and the filename to mount them as. Follow these steps:

1. Save the following manifest as app-parameters.yaml:

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: SECRET_PROVIDER_CLASS_NAME
   spec:
     provider: gke
     parameters:
       secrets: |
         - resourceName: "projects/PARAMETER_PROJECT_ID/locations/PARAMETER_LOCATION_ID/parameters/PARAMETER_NAME/versions/PARAMETER_VERSION"
           path: "FILENAME.txt"
   

   Replace the following:

   • SECRET_PROVIDER_CLASS_NAME: the name for your SecretProviderClass object.
   • PARAMETER_PROJECT_ID: the ID of the project where the parameter is stored. This can be the same as the PROJECT_ID if the parameter is stored in the same project as the GKE cluster.
   • PARAMETER_NAME: the parameter name.
   • PARAMETER_VERSION: the parameter version. The version must be in the same region as the cluster.
   • PARAMETER_LOCATION_ID: the location of the parameter.
   • FILENAME.txt: the filename where the parameter value is mounted. You can create multiple files using the resourceName and path variables.

2. Apply the manifest:

   kubectl apply -f app-parameters.yaml
   

3. Verify that the SecretProviderClass object is created:

   kubectl get SecretProviderClasses
   

Configure a volume where the parameters will be mounted

1. Save the following configuration as my-pod.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: POD_NAME
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     containers:
     - image: IMAGE_NAME
       imagePullPolicy: IfNotPresent
       name: POD_NAME
       resources:
         requests:
           cpu: 100m
       stdin: true
       stdinOnce: true
       terminationMessagePath: /dev/termination-log
       terminationMessagePolicy: File
       tty: true
       volumeMounts:
         - mountPath: "/var/secrets"
           name: mysecret
     volumes:
     - name: mysecret
       csi:
         driver: secrets-store-gke.csi.k8s.io
         readOnly: true
         volumeAttributes:
           secretProviderClass: SECRET_PROVIDER_CLASS_NAME
   

   Replace the following:

   • POD_NAME: the name of the Kubernetes Pod where the secret is mounted
   • NAMESPACE: the name of the Kubernetes namespace for the ServiceAccount
   • KSA_NAME: the Kubernetes ServiceAccount that you set up in the step Configure applications to authenticate to the Secret Manager API
   • IMAGE_NAME: name of the container image
   • SECRET_PROVIDER_CLASS_NAME: the name for your SecretProviderClass object

2. In Standard clusters only, add the following to the template.spec field to place the Pods on node pools that use Workload Identity Federation for GKE.

   Skip this step in Autopilot clusters, which reject this nodeSelector because every node uses Workload Identity Federation for GKE.

   spec:
     nodeSelector:
       iam.gke.io/gke-metadata-server-enabled: "true"
   

3. Apply the configuration to your cluster.

   kubectl apply -f my-pod.yaml
   

This step mounts a volume mysecret at /var/secrets using the CSI driver (secrets-store-gke.csi.k8s.io). This volume references the SecretProviderClass object which acts as the provider.

Migrate from the existing Secrets Store CSI Driver

If you're migrating to the Secret Manager add-on from your existing installation of the Secrets Store CSI Driver, update your Pod manifest as follows:

1. Update the name of your SecretProviderClass and the provider as described in the following manifest:

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: app-secrets-gke
   spec:
     provider: gke
     parameters:
       secrets: |
         - resourceName: "projects/<PARAMETER_PROJECT_ID>/locations/<PARAMETER_LOCATION_ID>/parameters/<PARAMETER_NAME>/versions/<PARAMETER_VERSION>"
           path: "FILENAME.txt"
   

2. Update the driver and the secretProviderClass for your Kubernetes volume as described in the following manifest:

   volumes:
     - name: mysecret
       csi:
         driver: secrets-store-gke.csi.k8s.io
         readOnly: true
         volumeAttributes:
           secretProviderClass: "app-secrets-gke"
   

Disable the Secret Manager add-on

To disable the Secret Manager add-on on an existing Standard cluster or on an Autopilot cluster, run the following command:

gcloud container clusters update CLUSTER_NAME \
    --no-enable-secret-manager \
    --region=REGION \

gcloud container clusters update CLUSTER_NAME `
    --no-enable-secret-manager `
    --region=REGION `

gcloud container clusters update CLUSTER_NAME ^
    --no-enable-secret-manager ^
    --region=REGION ^