Use Secret Manager add-on with Google Kubernetes Engine

The integration between Secret Manager and Google Kubernetes Engine (GKE) lets you store sensitive data such as passwords and certificates used by GKE clusters as secrets in Secret Manager.

This page explains how you can use the Secret Manager add-on to access the secrets stored in Secret Manager as volumes mounted in Kubernetes Pods.

This process involves the following steps:

1. Enable the Secret Manager add-on on a new or existing GKE cluster.
2. Configure applications to authenticate to the Secret Manager API.
3. Define which secrets to mount onto Kubernetes Pods using a SecretProviderClass YAML file. The Secret Manager add-on supports both global and regional secrets.
4. Create a volume where the secrets will be mounted. After the volume is attached, applications in the container can access the data in the container file system.

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 can use a fully managed and supported solution to access Secret Manager secrets from within GKE without any operational overhead.
• You don't have to write custom code to access secrets stored in Secret Manager.
• You can store and manage all your secrets centrally in Secret Manager and selectively access secrets from GKE pods using the Secret Manager add-on. By doing this, you can use features offered by Secret Manager such as CMEK encryption, fine-grained access control, managed rotation, lifecycle management, and audit logs, along with using Kubernetes features such as passing secrets to containers in the form of mounted volumes.
• The Secret Manager add-on is supported on both Standard clusters and Autopilot clusters.
• The Secret Manager add-on supports nodes that use Container-Optimized OS or Ubuntu node images.

Limitations

The Secret Manager add-on has the following limitations:

• The Secret Manager add-on doesn't support the Sync as Kubernetes Secret feature, which is available in the open source Secrets Store CSI Driver. If you want to synchronize secrets stored in Secret Manager to Kubernetes Secrets, use the integrated secret synchronization feature of Secret Manager. For information, see Synchronize secrets to Kubernetes Secrets.

• The Secret Manager add-on doesn't support Windows Server nodes.

Before you begin

• Enable the Secret Manager and Google Kubernetes Engine APIs.

  Roles required to enable APIs

  To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

  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.27.14-gke.1042001 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 Secret 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 automatic rotation of secrets