workload-identity

terraform-google-workload-identity

Workload Identity is the recommended way to access GCP services from Kubernetes.

This module creates:

• IAM Service Account binding to roles/iam.workloadIdentityUser
• Optionally, a Google Service Account
• Optionally, a Kubernetes Service Account

Usage

The terraform-google-workload-identity can create service accounts for you, or you can use existing accounts; this applies for both the Google and Kubernetes accounts.

Note: This module currently supports Kubernetes <= 1.23.

Creating a Workload Identity

module "my-app-workload-identity" {
  source     = "terraform-google-modules/kubernetes-engine/google//modules/workload-identity"
  name       = "my-application-name"
  namespace  = "default"
  project_id = "my-gcp-project-name"
  roles      = ["roles/storage.admin", "roles/compute.admin"]
}

This will create:

• Google Service Account named: [email protected]
• Kubernetes Service Account named: my-application-name in the default namespace
• IAM Binding (roles/iam.workloadIdentityUser) between the service accounts

Usage from a Kubernetes deployment:

metadata:
  namespace: default
  # ...
spec:
  # ...
  template:
    spec:
      serviceAccountName: my-application-name

Using an existing Google Service Account

An existing Google service account can optionally be used.

resource "google_service_account" "preexisting" {
  account_id   = "preexisting-sa"
}

module "my-app-workload-identity" {
  source              = "terraform-google-modules/kubernetes-engine/google//modules/workload-identity"
  use_existing_gcp_sa = true
  name                = google_service_account.preexisting.account_id
  project_id          = var.project_id

  # wait for the custom GSA to be created to force module data source read during apply
  # https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/issues/1059
  depends_on = [google_service_account.preexisting]
}

Using an existing Kubernetes Service Account

An existing Kubernetes service account can optionally be used.

resource "kubernetes_service_account" "preexisting" {
  metadata {
    name      = "preexisting-sa"
    namespace = "prod"
  }
}

module "my-app-workload-identity" {
  source              = "terraform-google-modules/kubernetes-engine/google//modules/workload-identity"
  use_existing_k8s_sa = true
  name                = kubernetes_service_account.preexisting.metadata[0].name
  namespace           = kubernetes_service_account.preexisting.metadata[0].namespace
  project_id          = var.project_id
}

If annotation is disabled (via annotate_k8s_sa = false), the existing Kubernetes service account must already bear the "iam.gke.io/gcp-service-account" annotation.

Inputs

Name	Description	Type	Default	Required
annotate_k8s_sa	Annotate the kubernetes service account with 'iam.gke.io/gcp-service-account' annotation. Valid in cases when an existing SA is used.	bool	true	no
automount_service_account_token	Enable automatic mounting of the service account token	bool	false	no
cluster_name	Cluster name. Required if using existing KSA.	string	""	no
gcp_sa_name	Name for the Google service account; overrides var.name.	string	null	no
impersonate_service_account	An optional service account to impersonate for gcloud commands. If this service account is not specified, the module will use Application Default Credentials.	string	""	no
k8s_sa_name	Name for the Kubernetes service account; overrides var.name. cluster_name and location must be set when this input is specified.	string	null	no
k8s_sa_project_id	GCP project ID of the k8s service account; overrides var.project_id.	string	null	no
location	Cluster location (region if regional cluster, zone if zonal cluster). Required if using existing KSA.	string	""	no
module_depends_on	List of modules or resources to depend on before annotating KSA. If multiple, all items must be the same type.	list(any)	[]	no
name	Name for both service accounts. The GCP SA will be truncated to the first 30 chars if necessary.	string	n/a	yes
namespace	Namespace for the Kubernetes service account	string	"default"	no
project_id	GCP project ID	string	n/a	yes
roles	A list of roles to be added to the created service account	list(string)	[]	no
use_existing_context	An optional flag to use local kubectl config context.	bool	false	no
use_existing_gcp_sa	Use an existing Google service account instead of creating one	bool	false	no
use_existing_k8s_sa	Use an existing kubernetes service account instead of creating one	bool	false	no

Outputs

Name	Description
gcp_service_account	GCP service account.
gcp_service_account_email	Email address of GCP service account.
gcp_service_account_fqn	FQN of GCP service account.
gcp_service_account_name	Name of GCP service account.
k8s_service_account_name	Name of k8s service account.
k8s_service_account_namespace	Namespace of k8s service account.