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 #

If you have already created an identity pool for the Platform Orchestrator OIDC provider in the past and now wish to add another identity for another Cloud Account, you can re-use the same identity pool. In that case, skip forward to creating the Cloud Account .

2. Create a workload identity pool :

   gcloud iam workload-identity-pools create humanitec-wif-pool \
   --location="global" \
   --project ${GCP_PROJECT_ID}
   

3. 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 #

4. 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}
   

5. 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
   

6. 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
   

7. 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:

   • CLI
   • Terraform

   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.

8. 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.

9. 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.

   • CLI

   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

This Cloud Account type uses static credentials. For superior security , we recommend using the GCP service account impersonation Cloud Account type with temporary credentials instead.

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:

   • CLI
   • Terraform

   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.

   • CLI

   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