Configure managed workload identity authentication for Compute Engine

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

For information about access to managed workload identities for Compute Engine, see theaccess request page.

This page explains how to configuremanaged workload identities forCompute Engine using the gcloud CLI.

This page also describes how to set up automatic provisioning and lifecyclemanagement of managed workload identities for Compute Engine. Youconfigure certificate authority (CA) pools to issue certificates usingCertificate Authority Service.CA Service is a highly-available, scalable Google Cloud servicethat simplifies and automates the deployment, management, and security ofCA services. You can create virtual machine instances (VMs) that areprovisioned with X.509 credentials from the configured CA pool. Thesecredentials can then be used to establish mTLS connections between workloads.

Before you begin

  1. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects createPROJECT_ID

      ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set projectPROJECT_ID

      ReplacePROJECT_ID with your Google Cloud project name.

  2. Request access to the managed workload identities for Compute Engine Preview.

    Important: You must wait until you receive a confirmation that yourproject has been added to the allowlist before moving on to the next steps.

  3. Understandmanaged workload identities.

  4. Learn about certificate issuance usingCertificate Authority Service.

  5. Learn how toauthenticate Compute Engine workloads using managedworkload identities.

  6. Enable the IAM and Certificate Authority Service APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    gcloudservicesenableiam.googleapis.com privateca.googleapis.com

  7. Configure Google Cloud CLI to use the project that was added to the allowlistfor billing and quota.

    gcloud config set billing/quota_projectPROJECT_ID

    ReplacePROJECT_ID with the ID of the project thatwas added to the allowlist for the managed workload identity preview.

Required roles

To get the permissions that you need to create managed workload identities and provision managed workload identity certificates, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Alternatively, the IAM Owner (roles/owner) basicrole also includes permissions to configure managed workload identities.You should not grant basic roles in a production environment, but you can grant them in adevelopment or test environment.

Overview

To use managed workload identities for your applications, you must perform thefollowing tasks:

  1. Security Administrator:

  2. Compute Administrator:

    Enable managed workload identities for workloads running in Compute Engine:

Create managed workload identities

Managed workload identities enables Google Cloud toautomatically provision credentials for workload identity pool identities ontoyour workloads. Workload identities are defined within a workload identity pool,and are organized into administrative boundaries callednamespaces.

Create a workload identity pool

You must create a pool inTRUST_DOMAIN mode to create managedworkload identities. To create a workload identity pool for managedworkload identities, use theworkload-identity-pools create command.

gcloud iam workload-identity-pools createPOOL_ID \    --location="global" \    --mode="TRUST_DOMAIN"

Replace the following:

  • POOL_ID: the unique ID for the pool. The ID must bebetween 4 and 32 characters, and can contain only lowercase alphanumericcharacters and dashes, and start and end with an alphanumeric character.After you create a workload identity pool, you can't change its ID.

To verify that your workload identity pool was created inTRUST_DOMAIN mode, use theworkload-identity-pools describe command.

gcloud iam workload-identity-pools describePOOL_ID \    --location="global"

The command output should look similar to the following:

mode: TRUST_DOMAINname: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_IDstate: ACTIVE

Ifmode: TRUST_DOMAIN is not present in the command output,verifythat your project has been added to the allowlist for the managed workload identityPreview and that you've correctly configured yourgcloud CLI to use the correct project for billing and quota. Youmight need to update to a newer version of the gcloud CLI.

Create a namespace

Theworkload-identity-pools namespaces create commandlets you create a namespace in a workload identity pool.

gcloud iam workload-identity-pools namespaces createNAMESPACE_ID \    --workload-identity-pool="POOL_ID" \    --location="global"

Replace the following:

  • NAMESPACE_ID: the unique ID for the namespace. TheID must be between 2 and 63 characters, contain only lowercase alphanumericcharacters and dashes, and start and end with an alphanumeric character.After you create a namespace, you cannot change its ID.
  • POOL_ID: the workload identity pool ID that youcreated earlier.

Create a managed workload identity

Theworkload-identity-pools managed-identities create commandlets you create a managed workload identity in a workload identity poolnamespace.

gcloud iam workload-identity-pools managed-identities createMANAGED_IDENTITY_ID \    --namespace="NAMESPACE_ID" \    --workload-identity-pool="POOL_ID" \    --location="global"

Replace the following:

  • MANAGED_IDENTITY_ID: the unique ID for the managedidentity. The ID must be between 2 and 63 characters, contain only lowercasealphanumeric characters and dashes, and start and end with an alphanumericcharacter. After you create a managed workload identity, you cannot changeits ID.
  • NAMESPACE_ID: the namespace ID that you createdearlier.
  • POOL_ID: the workload identity pool ID that youcreated earlier.

Your managed workload identity ID is the SPIFFE identifier, which isformatted as follows:

spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID

Define a workload attestation policy

This section describes how to set up anattestation policy.This policy determines which attributes are used forGoogle Cloud IAMto verify the identity of the workload. After verification, the calling workloadcan receive a credential. Verification is based on one of the followingattributes of the workload:

  • VM instance ID
  • Attached service account email address
  • Attached service account UID
Deprecated: Workload sources are deprecated as of October 11, 2024. As of this date, you canno longer create new workload sources. Existing workload sources will be removed on or afterApril 24, 2025. Attestations based on workload sources will fail. To prevent disruption, werecommend that you attest using another method described later in this document.To learn how to list previously configured workload sources, use the followingcommand:gcloud iam workload-identity-pools managed-identities workload-sources list --help.

Define a workload attestation policy with attestation rules

To create an attestation policy that allows your workload to use themanaged identity, do the following:

  1. Decide whether you want to create an attestation policy that allows yourworkload to attest the managed identity by using its attached serviceaccount or by using its instance ID.

  2. Create a JSON-formatted attestation policy file.

    1. (Optional) To receive X.509 credentials on your Compute Engineinstance, you must enable an attached service account. We recommendthat you attach a new service account to your workload by firstcreating it using the following command:

      gcloud iam service-accounts createSERVICE_ACCOUNT_NAME

      ReplaceSERVICE_ACCOUNT_NAME with the name ofthe service account

    2. Create a JSON-formatted attestation policy file that attests based onthe service account email address, service account UID, or instance ID.

      Service account email address

      To create an attestation policy file that attests based on the serviceaccount email address, create a file with the following contents:

      {   "attestationRules": [      {         "googleCloudResource": "//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/type/Instance/attached_service_account.email/SERVICE_ACCOUNT_EMAIL"      }   ],}

      Replace the following:

      • WORKLOAD_PROJECT_NUMBER: the number of the project that contains the VM instance or service account

      To get the project number of the project that contains the managedidentity or the service account that you just created, run the followingcommand:

         gcloud projects describe $(gcloud config get-value project) \      --format="value(projectNumber)"
      • SERVICE_ACCOUNT_EMAIL: the email address of the service account attached to the VM

      Service account UID

      To create an attestation policy file that attests based on the serviceaccount UID, create a file with the following contents:

      {   "attestationRules": [      {         "googleCloudResource": "//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/type/Instance/attached_service_account.uid/SERVICE_ACCOUNT_UID"      }   ],}

      Replace the following:

      • WORKLOAD_PROJECT_NUMBER: the number of the project that contains the VM instance or service account

      To get the project number of the project that contains the managedidentity or the service account that you just created, run thefollowing command:

         gcloud projects describe $(gcloud config get-value project) \      --format="value(projectNumber)"
      • SERVICE_ACCOUNT_UID: the UID of the service account attached to the VM

      Instance ID

      To create an attestation policy file that attests based on the instanceID, create a file with the following contents:

      {   "attestationRules": [      {         "googleCloudResource": "//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/uid/zones/ZONE/instances/INSTANCE_ID"      }   ],}

      Replace the following:

      • WORKLOAD_PROJECT_NUMBER: the number of the project that contains the VM instance or service account

      To get the project number of the project that contains the managedidentity or the service account that you just created, run the followingcommand:

         gcloud projects describe $(gcloud config get-value project) \      --format="value(projectNumber)"
      • INSTANCE_ID: the Compute Engine VM instance ID

      The value for an instance ID must come from an existingCompute Engine instance. To obtain your instance ID, run thefollowing command:

      gcloud compute instances describeINSTANCE_NAME --zone=ZONE --format="get(id)"
      • INSTANCE_NAME: the Compute Engine VM instance name
      • ZONE: the Compute Engine VM zone

  3. Create the attestation policy using the policy JSON file that you createdearlier in this document:

    gcloud iam workload-identity-pools managed-identities set-attestation-rulesMANAGED_IDENTITY_ID \   --namespace=NAMESPACE_ID \   --workload-identity-pool=POOL_ID \   --policy-file=PATH_TO_POLICY_JSON_FILE \   --location=global

    Replace the following:

    • MANAGED_IDENTITY_ID: the unique ID for the managedidentity. The ID must be between 2 and 63 characters, contain only lowercasealphanumeric characters and dashes, and start and end with an alphanumericcharacter. After you create a managed workload identity, you cannot changeits ID.
    • NAMESPACE_ID: the namespace ID that you createdearlier.
    • POOL_ID: the workload identity pool ID that youcreated earlier.
    • PATH_TO_POLICY_JSON_FILE: Path to the JSONfile representing the attestation policy that you created earlier.

    You can also update the policy by adding or removing attestation rulesindividually. To add an attestation to your attestation policy, run thefollowing command:

    gcloud iam workload-identity-pools managed-identities add-attestation-ruleMANAGED_IDENTITY_ID \   --namespace=NAMESPACE_ID \   --workload-identity-pool=POOL_ID \   --google-cloud-resource='//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/type/Instance/attached_service_account.uid/SERVICE_ACCOUNT_UID' \   --location=global

  4. To learn about how to list or remove the attestation rules, run thefollowing commands:

    gcloud iam workload-identity-pools managed-identities list-attestation-rules --helpgcloud iam workload-identity-pools managed-identities remove-attestation-rule --help

Configure Certificate Authority Service to issue certificates for managed workload identities

Create the recommended set up for root and subordinate certificate authorities(CAs) usingCertificate Authority Service pools.The subordinate CA pool issues the X.509 workload identity certificates to VMs.

Note: The CA pools configured to issue certificates forCompute Engine VMs using managed workload identities must reside in the sameregion as the VM. If you want to design amulti-region architecture for resilience to regional outages,we recommend that you configure a subordinate Certificate Authority Service CA pool foreach of your workload's regions, so that each of your Compute EngineVMs can reference an in-region subordinate Certificate Authority Service CA pool.

After configuring the CA pools, you then authorize the managed workloadidentities to request and receive the signed certificates from the CA pools.

Configure the root CA pool

Use the Google Cloud CLI interface to Certificate Authority Service to configure a root CApool.

Note: You cannot move or export a CA pool after it has been created.

gcloud

Create the root CA pool.

  1. Create the root CA pool in theEnterprise tier, which is meant forlong-lived, low-volume certificate issuance using thegcloud privateca pools create command.

    gcloud privateca pools createROOT_CA_POOL_ID \   --location=REGION \   --tier=enterprise

    Replace the following:

    • ROOT_CA_POOL_ID: a unique ID for the root CA pool. The IDcan be up to 64 characters in length and must contain only lower anduppercase alphanumeric characters, underscores, or hyphens. The pool IDmust be unique within the region.
    • REGION: the region where the root CA pool islocated.

    For more information, seeCreating CA pools.

  2. Create a root CA in the root CA pool using thegcloud privateca roots create command.You might be prompted toenable the root CAif this is the only CA in the root CA Pool.

    For example, you might use a command similar to the following tocreate a root CA.

    gcloud privateca roots createROOT_CA_ID \   --pool=ROOT_CA_POOL_ID \   --subject "CN=ROOT_CA_CN, O=ROOT_CA_ORGANIZATION" \   --key-algorithm="ec-p256-sha256" \   --max-chain-length=1 \   --location=REGION

    Replace the following:

    • ROOT_CA_ID: a unique name for the root CA. The CA namecan be up to 64 characters in length and must contain only lower anduppercase alphanumeric characters, underscores, or hyphens. The CA namemust be unique within the region.
    • ROOT_CA_POOL_ID: the ID of the root CA pool.
    • ROOT_CA_CN: the common name of the root CA.
    • ROOT_CA_ORGANIZATION: the organization of the root CA.
    • REGION: the region where the root CA pool islocated.

    For more information, seeCreate a root certificate authority.For more information about thesubject fields for the CA, seeSubject.

  3. Optional: Repeat the previous steps to create an additional root CA inthe root CA pool. This can be useful forroot CA rotation.

Configure the subordinate CAs

Use the Google Cloud CLI interface to Certificate Authority Service to create a subordinateCA pool and subordinate CA.

If you have multiple certificate issuance scenarios, you can create asubordinate CA for each of those scenarios. Also, adding multiple subordinateCAs in a CA pool helps you achieve better load-balancing of certificaterequests.

gcloud

Use thegcloud privateca pools create commandto create a subordinate CA pool.

  1. Create the subordinate CA pool in theDevOps tier, which is meantfor high volume, short-lived certificate issuance .

    gcloud privateca pools createSUBORDINATE_CA_POOL_ID \   --location=REGION \   --tier=devops

    Replace the following:

    • SUBORDINATE_CA_POOL_ID: a unique ID for the subordinateCA pool. The ID can be up to 64 characters in length and mustcontain only lowercase and uppercase alphanumeric characters,underscores, or hyphens. The pool ID must be unique within the region.
    • REGION: the region in which to createthe subordinate CA pool.

    For more information, seeCreating CA pools.

  2. Create a subordinate CA in the subordinate CA pool using thegcloud privateca subordinates create command.Don't change the defaultconfig-based issuance mode.

    For example, you might use a command similar to the following tocreate a subordinate CA.

    gcloud privateca subordinates createSUBORDINATE_CA_ID \   --pool=SUBORDINATE_CA_POOL_ID \   --location=REGION \   --issuer-pool=ROOT_CA_POOL_ID \   --issuer-location=REGION \   --subject="CN=SUBORDINATE_CA_CN, O=SUBORDINATE_CA_ORGANIZATION" \   --key-algorithm="ec-p256-sha256" \   --use-preset-profile=subordinate_mtls_pathlen_0

    Replace the following:

    • SUBORDINATE_CA_ID: a unique name for the subordinate CA.The name can be up to 64 characters in length and must contain onlylowercase and uppercase alphanumeric characters, underscores, or hyphens.The pool name must be unique within the region.
    • SUBORDINATE_CA_POOL_ID: the name of the subordinate CA pool.
    • REGION: the region where the subordinateCA pool is located.
    • ROOT_CA_POOL_ID: the ID of the root CA pool.
    • REGION: the region of the root CA pool.
    • SUBORDINATE_CA_CN: the common name of the subordinate CA.
    • SUBORDINATE_CA_ORGANIZATION: the name of the subordinateCA issuing organization.

    For more information, seeCreating CA pools.For more information about thesubject fields for the CA, seeSubject.

Authorize managed workload identities to request certificates from the CA pool

The managed workload identities require permissions to request certificatesfrom the CA Service and get the public certificates.

gcloud

  1. Grant theCA Service Workload Certificate Requester (roles/privateca.workloadCertificateRequester)IAM role on each subordinate CA pool to the managedworkload identity. The followinggcloud privateca pools add-iam-policy-binding commandauthorizes the managed workload identity to request certificates fromthe CA Service certificate chains.

    gcloud privateca pools add-iam-policy-bindingSUBORDINATE_CA_POOL_ID \ --location=REGION \ --role=roles/privateca.workloadCertificateRequester \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*"

    Replace the following:

    • SUBORDINATE_CA_POOL_ID: the ID for the subordinateCA pool.
    • REGION: the region of thesubordinate CA pool.
    • PROJECT_NUMBER: the project number of the projectthat contains the workload identity pool.
    • POOL_ID: the ID of the workload identity pool.

  2. Grant theCA Service Pool Reader (roles/privateca.poolReader)IAM role on the subordinate CA pools to the managedworkload identity. This authorizes the managed workload identity to getthe signed X.509 certificates from the CA's certificate chains.

    gcloud privateca pools add-iam-policy-bindingSUBORDINATE_CA_POOL_ID \ --location=REGION \ --role=roles/privateca.poolReader \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*"

    Replace the following:

    • SUBORDINATE_CA_POOL_ID: the ID for the subordinateCA pool.
    • REGION: the region of thesubordinate CA pool.
    • PROJECT_NUMBER: the project number of the projectthat contains the workload identity pool.
    • POOL_ID: the ID of the workload identity pool.

Define the trust and certificate issuance config

You use this information to create a JSON file that is uploaded as partnerdata when creating a VM.

Define the certificate issuance config

The followingcertificate issuance configis required to enable managed workload identities for Compute Engine.

{  "primary_certificate_authority_config": {    "certificate_authority_config": {      "ca_pool": "projects/SUBORDINATE_CA_POOL_PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"    }  },  "key_algorithm": "ALGORITHM",  "workload_certificate_lifetime_seconds":DURATION,  "rotation_window_percentage":ROTATION_WINDOW_PERCENTAGE}

Replace the following:

  • SUBORDINATE_CA_POOL_PROJECT_ID: the ID of the project thatcontains the subordinate CA pool.
  • REGION: the region where the subordinate CA pool is located.
  • SUBORDINATE_CA_POOL_ID: the name of the subordinate CA pool
  • ALGORITHM: the encryption algorithm used to generate theprivate key. Valid values arersa-2048 (default),rsa-3072,rsa-4096,ecdsa-p256 andecdsa-p384.
  • DURATION: Optional: The leaf certificate validity duration, inseconds. The value must be between 3600 and 315360000. If not specified, thedefault value of 86400 is used. The actually validity of the issuedcertificate also depends on the issuing CA, because it may restrict thelifetime of the issued certificate.
  • ROTATION_WINDOW_PERCENTAGE: Optional: The percentage of thecertificate's lifetime at which a renewal triggers. Value must be between50 and 80. The default value is 50 percent. You must set the rotation windowpercentage in relation to the certificate lifetime so that certificaterenewal occurs at least 7 days after the certificate has been issued and atleast 7 days before it expires.

Define the trust config

Thetrust config contains the set of trust anchors for validating peercertificates. This includes the following:

  • Trusted CA pool resource URIs: A set of CA pool resource URIs that aretrusted to issue certificates in the same trust domain as the VMs belongsto.
  • PEM formatted CA certificates: A set of PEM-formatted CA certificatestrusted to issue certificates in the same trust domain as the VMs belongsto.
Note: The trust config must contain an entry for the SPIFFE trust domainPOOL_ID.global.PROJECT_NUMBER.workload.id.goog,which corresponds to the SPIFFE trust domain of managed identity assigned tothe VM. Not specifying this would result in provisioning failure of workloadcertificates.
{  "POOL_ID.global.PROJECT_NUMBER.workload.id.goog": {    "trust_anchors": [      {        "ca_pool": "projects/SUBORDINATE_CA_POOL_PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"      },      {        "pem_certificate": "PEM_ENCODED_CERTIFICATE"      }    ]  }}

Replace the following:

  • POOL_ID: the ID of the workload identity pool
  • PROJECT_NUMBER: the project number of the project thatthat contains the workload identity pool
  • SUBORDINATE_CA_POOL_PROJECT_ID: the ID of the project thatcontains the subordinate CA pool.
  • REGION: the region where the subordinate CA pool is located
  • SUBORDINATE_CA_POOL_ID: the ID of the subordinate CA pool

  • PEM_ENCODED_CERTIFICATE: Optional: a set of additionalPEM-formatted CA certificates trusted to issue certificates in the same trustdomain that the VMs belongs to. These certificates will be added to thesubordinate CA pool's list of trust anchors. The following command can beused to encode a PEM-formattedtrust-anchor.pem file into a one-linestring:

    cattrust-anchor.pem|sed's/^[ ]*//g'|sed-z'$ s/\n$//'|tr'\n'$|sed's/\$/\\n/g'

Create a configuration file to upload the partner metadata for a VM

Create a JSON file that contains the following:

Save this file asCONFIGS.json. This file is used when creating VMs torun applications that use managed workload identities.

Note: The format of the JSON and the values provided must be valid. TheVM creation will fail if the file provides invalid input.

YourCONFIGS.json file should be similar to the following:

{"wc.compute.googleapis.com":{"entries":{"certificate-issuance-config":{"primary_certificate_authority_config":{"certificate_authority_config":{"ca_pool":"projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"}},"key_algorithm":"ALGORITHM"},"trust-config":{"POOL_ID.global.PROJECT_NUMBER.workload.id.goog":{"trust_anchors":[{"ca_pool":"projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID"}]}}}},"iam.googleapis.com":{"entries":{"workload-identity":"spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID"}}}

What's next

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Get started for free

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.