GCP

Prerequisites

To manage any Cloud Account using the instructions below, you need:

  • The humctl CLI installed

  • Authentication against the Platform Orchestrator via humctl login

  • The gcloud CLI installed

  • These environment variables set:

    export HUMANITEC_ORG=<your-humanitec-org-id>
    

GCP Service account impersonation

Credentials: temporary

Available Inputs/Outputs: see the Cloud Account types reference

How it works

GCP temporary credentials make use of IAM Service account impersonation in conjunction with OIDC-based Workload identity federation. You need to first create a workload identity pool and then add a policy binding between the pool principal and a GCP service account.

The setup involves the Humanitec Platform Orchestrator OIDC provider.

Prepare your environment

  1. Define the Google Cloud project ID where to create the IAM objects:

    export GCP_PROJECT_ID=<my-gcp-project-id>
    

Create an identity pool

  1. Create a workload identity pool:

    gcloud iam workload-identity-pools create humanitec-wif-pool \
    --location="global" \
    --project ${GCP_PROJECT_ID}
    
  2. Create a new OIDC workload identity pool provider in that pool:

    gcloud iam workload-identity-pools providers create-oidc humanitec-wif \
        --location="global" \
        --workload-identity-pool="humanitec-wif-pool"  \
        --issuer-uri="https://idtoken.humanitec.io" \
        --attribute-mapping="google.subject=assertion.sub" \
        --project=${GCP_PROJECT_ID}
    

Create the Cloud Account for temporary credentials

  1. Create a GCP service account to be used by the Humanitec Cloud Account:

    Define the service account name:

    export SERVICE_ACCOUNT_NAME=my-gcp-temp-cloud-account
    

    Create the service account:

    gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \
        --description="Used by Humanitec Platform Orchestrator Cloud Account" \
        --display-name=${SERVICE_ACCOUNT_NAME} \
        --project=${GCP_PROJECT_ID}
    
  2. Define the naming of the new Cloud Account:

    export CLOUD_ACCOUNT_NAME="My GCP Temporary Cred Account"
    export CLOUD_ACCOUNT_ID=my-gcp-temp-cloud-account
    
  3. Add this policy binding between the service account and workload identity federation principal to enable it for service account impersonation:

    export GCP_PROJECT_NUMBER=$(gcloud projects describe ${GCP_PROJECT_ID} --format='get(projectNumber)')
    
    gcloud iam service-accounts add-iam-policy-binding ${SERVICE_ACCOUNT_NAME}@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
        --member=principal://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/humanitec-wif-pool/subject/${HUMANITEC_ORG}/${CLOUD_ACCOUNT_ID} \
        --role=roles/iam.workloadIdentityUser \
        --format=json
    
  4. Create a Cloud Account in the Platform Orchestrator.

    If you haven’t already done so (see Prerequisites), define these environment variables:

    export HUMANITEC_ORG=<your-humanitec-org-id>
    

    Create the Cloud Account:

    Create a file defining the Cloud Account you want to create:

    cat << EOF > gcp-identity-cloudaccount.yaml
    apiVersion: entity.humanitec.io/v1b1
    kind: Account
    metadata:
      id: ${CLOUD_ACCOUNT_ID}
    entity:
      name: ${CLOUD_ACCOUNT_NAME}
      type: gcp-identity
      credentials:
        gcp_service_account: ${SERVICE_ACCOUNT_NAME}@${GCP_PROJECT_ID}.iam.gserviceaccount.com
        gcp_audience: //iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/humanitec-wif-pool/providers/humanitec-wif
    EOF
    

    Use the humctl create command to create the Cloud Account in the Organization defined by your configured context:

    humctl apply -f gcp-identity-cloudaccount.yaml
    rm gcp-identity-cloudaccount.yaml
    

    Using the Humanitec Terraform Provider:

    resource "humanitec_resource_account" "gcp-identity" {
      id   = var.gcp_service_account_temporary_account_id
      name = var.gcp_service_account_temporary_account_name
      type = "gcp-identity"
      credentials = jsonencode({
        "gcp_service_account" = "${var.gcp_service_account_temporary_account_id}@${var.gcp_project_id}.iam.gserviceaccount.com"
        "gcp_audience"        = "//iam.googleapis.com/projects/${var.gcp_project_number}/locations/global/workloadIdentityPools/humanitec-wif-pool/providers/humanitec-wif"
      })
    }
    

    Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.

  5. Assign the required roles to the Service Account.

    The Cloud Account is now ready for use by any Drivers supporting the gcp-identity Account type. Remember to assign the required permissions to the Service Account on the target GCP services depending on the kind of operations it needs to perform.

    For access to a GKE cluster, refer to the Kubernetes page for guidance.

  6. Test the Cloud Account.

    The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type gcp-identity, the GCP IAM Principal identifier will be displayed.

    The check operation can be called using the specific CLI command.

    humctl resources check-account ${CLOUD_ACCOUNT_ID}
    

    Note that this check does not validate permissions assigned to the Service Account that may be used to provision or connect infrastructure during deployments.

Example: connect to a GKE cluster using temporary credentials

This example Resource Definition uses the GKE cluster Driver to connect to an GKE cluster. It includes a Cloud Account of type gcp-identity via the driver_account setting. The Cloud Account credentials will be automatically picked up by the Driver with no further configuration required.


gke-temporary-credentials.yaml (view on GitHub) :

# Connect to a GKE cluster using temporary credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: gke-temporary-credentials
entity:
  name: gke-temporary-credentials
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "gcp-identity"
  # which needs to be configured for your Organization.
  driver_account: gcp-temporary-creds
  driver_type: humanitec/k8s-cluster-gke
  driver_inputs:
    values:
      loadbalancer: 35.10.10.10
      name: demo-123
      zone: europe-west2-a
      project_id: my-gcp-project

GCP Service account keys

Credentials: static

Available Inputs/Outputs: see the Cloud Account types reference

Create the Cloud Account for static credentials

  1. Create a GCP service account which will be used by the Humanitec Platform Orchestrator.

    export SERVICE_ACCOUNT_NAME="humanitec-sa"
    gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
      --description="Used by Humanitec Platform Orchestrator" \
      --display-name=$SERVICE_ACCOUNT_NAME
    
    export SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list --filter="displayName:$SERVICE_ACCOUNT_NAME" --format=json | jq -rM '.[0].email')
    
    gcloud iam service-accounts keys create key.json \
        --iam-account=$SERVICE_ACCOUNT_EMAIL
    

    Export the values needed for the Cloud Account:

    export SERVICE_ACCOUNT_KEY=$(yq -o yaml key.json | sed 's/^/    /')
    rm ./key.json
    
  2. Create a Cloud Account in the Platform Orchestrator.

    Define the name and id of the new Cloud Account:

    export CLOUD_ACCOUNT_NAME="My GCP Cred Account"
    export CLOUD_ACCOUNT_ID=my-gcp-cred
    

    If you haven’t already done so (see Prerequisites), define these environment variables:

    export HUMANITEC_ORG=<your-humanitec-org-id>
    

    Create the Cloud Account:

    Create a file defining the Cloud Account you want to create:

    cat << EOF > gcp-cloudaccount.yaml
    apiVersion: entity.humanitec.io/v1b1
    kind: Account
    metadata:
      id: ${CLOUD_ACCOUNT_ID}
    entity:
      name: ${CLOUD_ACCOUNT_NAME}
      type: gcp
      credentials:
    ${SERVICE_ACCOUNT_KEY}
    EOF
    

    Use the humctl create command to create the Cloud Account in the Organization defined by your configured context:

    humctl apply -f gcp-cloudaccount.yaml
    rm gcp-cloudaccount.yaml
    

    Using the Humanitec Terraform Provider:

    resource "humanitec_resource_account" "gcp" {
      id          = var.cloud_account_id
      name        = var.cloud_account_name
      type        = "gcp"
      credentials = jsonencode(var.service_account_key)
    }
    

    Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.

  3. Assign the required roles to the Service Account.

    The Cloud Account is now ready for use by any Drivers supporting the gcp Account type. Remember to assign the required permissions to the Service Account on the target GCP services depending on the kind of operations it needs to perform.

    For access to a GKE cluster, refer to the Kubernetes page for guidance.

  4. Test the Cloud Account.

    The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type gcp, the GCP IAM Principal identifier will be displayed.

    The check operation can be called using the specific CLI command.

    humctl resources check-account ${CLOUD_ACCOUNT_ID}
    

    Note that this check does not validate permissions assigned to the Service Account that may be used to provision or connect infrastructure during deployments.

Example: connect to a GKE cluster using static credentials

This example Resource Definition uses the GKE cluster Driver to connect to an GKE cluster. It includes a Cloud Account of type gcp via the driver_account setting. The Cloud Account credentials will be automatically picked up by the Driver with no further configuration required.


gke-static-credentials-cloudaccount.yaml (view on GitHub) :


# Connect to a GKE cluster using static credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: gke-static-credentials-cloudaccount
entity:
  name: gke-static-credentials-cloudaccount
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "gcp"
  # which needs to be configured for your Organization.
  driver_account: gcp-static-creds
  driver_type: humanitec/k8s-cluster-gke
  driver_inputs: 
    values: 
      loadbalancer: 35.10.10.10
      name: demo-123
      zone: europe-west2-a
      project_id: my-gcp-project
Top