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 
  
^