> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/gcp-gke

Easily manage your Google Kubernetes Engine (GKE) clusters and node pools.

## Commands

### create-cluster

Creates a GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container clusters create" |
| `autopilot` | boolean | false | Create your GKE cluster in Autopilot mode. Autopilot clusters are managed and pre-configured with an optimized, production-ready cluster configuration.
 |
| `cluster` | string |  | Name of the GKE cluster to be created
 |
| `no_output_timeout` | string | 10m | Elapsed time that the cluster creation command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |

### create-node-pool

Creates a node pool in a running GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container node-pools create" |
| `cluster` | string |  | Name of the GKE cluster
 |
| `no_output_timeout` | string | 20m | Elapsed time that the node pool creation command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `node_pool` | string |  | Name of the node pool to be created
 |

### delete-cluster

Deletes a GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container clusters delete" |
| `cluster` | string |  | Name of the GKE cluster to be deleted
 |
| `no_output_timeout` | string | 10m | Elapsed time that the cluster deletion command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |

### delete-node-pool

Deletes a node pool in a running GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container node-pools delete" |
| `cluster` | string |  | Name of the GKE cluster
 |
| `no_output_timeout` | string | 15m | Elapsed time that the node pool deletion command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `node_pool` | string |  | Name of the node pool to be deleted
 |

### rollout-image

Update a deployment's Docker image.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `container` | string |  | The Kubernetes container name. |
| `deployment` | string |  | The Kubernetes deployment name. |
| `dry_run` | enum | none | Must be "none", "server", or "client".
If client strategy, only print the object that would be sent, without sending it.
If server strategy, submit server-side request without persisting the resource.
 |
| `image` | string |  | A fully-qualified name for your docker image |
| `namespace` | string |  | The Kubernetes namespace name. |
| `tag` | string | latest | Docker image tag |
| `workload_type` | enum | deployment | Workload type to rollout image.
Must be "pod", "replicationcontroller", "deployment", "daemonset", "statefulset", "cronjob", or "replicaset".
 |

### update-kubeconfig-with-credentials

Allows the kubectl client to work with a GKE cluster. Updates the kubectl configuration file with GKE cluster access credentials.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container clusters get-credentials" |
| `cluster` | string |  | The name of the cluster for which to create a kubeconfig entry.
 |
| `use_gke_cloud_auth_plugin` | boolean | true | If true, use the gke-gcloud-auth-plugin to authenticate with the cluster. See more at: https://cloud.google.com/blog/products/containers-kubernetes/kubectl-auth-changes-in-gke
 |

## Jobs

### create-cluster

Creates a GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container clusters create" |
| `autopilot` | boolean | false | Create your GKE cluster in Autopilot mode. Autopilot clusters are managed and pre-configured with an optimized, production-ready cluster configuration.
 |
| `cluster` | string |  | Name of the GKE cluster to be created
 |
| `executor` | executor | default | Executor to use for this job
 |
| `gcloud_service_key` | env_var_name | GCLOUD_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project.
Only required if not using OIDC i.e. "use_oidc" is false.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials.
Required if "use_oidc" is set to true.
 |
| `google_compute_region` | env_var_name | GOOGLE_COMPUTE_REGION | Name of environment variable storing the Google compute region to set as
default for the gcloud CLI.
 |
| `google_compute_zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to set as
default for the gcloud CLI.
 |
| `google_project_id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID to set as
default for the gcloud CLI.
 |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number used to configure OIDC.
Required if "use_oidc" is set to true.
 |
| `no_output_timeout` | string | 10m | Elapsed time that the cluster creation command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email.
Required if "use_oidc" is set to true.
 |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
Required if "use_oidc" is set to true.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
Required if "use_oidc" is set to true.
 |

### create-node-pool

Creates a node pool in a running GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container node-pools create" |
| `cluster` | string |  | Name of the GKE cluster
 |
| `executor` | executor | default | Executor to use for this job
 |
| `gcloud_service_key` | env_var_name | GCLOUD_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project.
Only required if not using OIDC i.e. "use_oidc" is false.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials.
Required if "use_oidc" is set to true.
 |
| `google_compute_region` | env_var_name | GOOGLE_COMPUTE_REGION | Name of environment variable storing the Google compute region to set as
default for the gcloud CLI.
 |
| `google_compute_zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to set as
default for the gcloud CLI.
 |
| `google_project_id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID to set as
default for the gcloud CLI.
 |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number used to configure OIDC.
Required if "use_oidc" is set to true.
 |
| `no_output_timeout` | string | 20m | Elapsed time that the node pool creation command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `node_pool` | string |  | Name of the node pool to be created
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email.
Required if "use_oidc" is set to true.
 |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
Required if "use_oidc" is set to true.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
Required if "use_oidc" is set to true.
 |

### delete-cluster

Deletes a GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container clusters delete" |
| `cluster` | string |  | Name of the GKE cluster to be deleted
 |
| `executor` | executor | default | Executor to use for this job
 |
| `gcloud_service_key` | env_var_name | GCLOUD_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project.
Only required if not using OIDC i.e. "use_oidc" is false.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials.
Required if "use_oidc" is set to true.
 |
| `google_compute_region` | env_var_name | GOOGLE_COMPUTE_REGION | Name of environment variable storing the Google compute region to set as
default for the gcloud CLI.
 |
| `google_compute_zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to set as
default for the gcloud CLI.
 |
| `google_project_id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID to set as
default for the gcloud CLI.
 |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number used to configure OIDC.
Required if "use_oidc" is set to true.
 |
| `no_output_timeout` | string | 10m | Elapsed time that the cluster deletion command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email.
Required if "use_oidc" is set to true.
 |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
Required if "use_oidc" is set to true.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
Required if "use_oidc" is set to true.
 |

### delete-node-pool

Deletes a node pool in a running GKE cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Additional arguments to "gcloud container node-pools delete" |
| `cluster` | string |  | Name of the GKE cluster
 |
| `executor` | executor | default | Executor to use for this job
 |
| `gcloud_service_key` | env_var_name | GCLOUD_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project.
Only required if not using OIDC i.e. "use_oidc" is false.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials.
Required if "use_oidc" is set to true.
 |
| `google_compute_region` | env_var_name | GOOGLE_COMPUTE_REGION | Name of environment variable storing the Google compute region to set as
default for the gcloud CLI.
 |
| `google_compute_zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to set as
default for the gcloud CLI.
 |
| `google_project_id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID to set as
default for the gcloud CLI.
 |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number used to configure OIDC.
Required if "use_oidc" is set to true.
 |
| `no_output_timeout` | string | 15m | Elapsed time that the node pool deletion command can run on CircleCI without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `node_pool` | string |  | Name of the node pool to be deleted
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email.
Required if "use_oidc" is set to true.
 |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
Required if "use_oidc" is set to true.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
Required if "use_oidc" is set to true.
 |

### publish-and-rollout-image

Update cluster with new Docker image.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster` | string |  | The Kubernetes cluster name. |
| `container` | string |  | The Kubernetes container name. |
| `deployment` | string |  | The Kubernetes deployment name. |
| `docker_context` | string | . | Path to the directory containing your build context, defaults to . (working directory)
 |
| `dockerfile_dir` | string | . | Path to the directory containing your Dockerfile, defaults to . (working directory)
 |
| `dockerfile_name` | string | Dockerfile | Name of dockerfile to use, defaults to Dockerfile |
| `dry_run` | enum | none | Used for image rollout. Must be "none", "server", or "client". If client strategy, only print the object that would be sent, without sending it.
If server strategy, submit server-side request without persisting the resource.
 |
| `executor` | executor | default | Executor to use for this job
 |
| `extra_build_args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build
 |
| `gcloud_service_key` | env_var_name | GCLOUD_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project.
Only required if not using OIDC i.e. "use_oidc" is false.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials.
Required if "use_oidc" is set to true.
 |
| `google_compute_region` | env_var_name | GOOGLE_COMPUTE_REGION | Name of environment variable storing the Google compute region to set as
default for the gcloud CLI.
 |
| `google_compute_zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to set as
default for the gcloud CLI.
 |
| `google_project_id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID to set as
default for the gcloud CLI.
 |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number used to configure OIDC.
Required if "use_oidc" is set to true.
 |
| `image` | string |  | A name for your docker image |
| `namespace` | string |  | The Kubernetes namespace name. |
| `registry_url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io, or an artifact registry url from [GOOGLE_COMPUTE_REGION, us, eu, asia]-docker.pkg.dev |
| `remote_docker_version` | string |  | Setup a version for remote Docker engine. If left blank, the latest version will be used.
 |
| `repository` | string |  | The Artifact Registry requires a HOST-NAME/PROJECT-ID/REPOSITORY/IMAGE format. If pushing to the Artifact Registry, the repository to push the image to
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email.
Required if "use_oidc" is set to true.
 |
| `tag` | string | latest | A docker image tag |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `use_remote_docker` | boolean | true | Setup a remote Docker engine for Docker commands? Only required if using a Docker-based executor
 |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
Required if "use_oidc" is set to true.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
Required if "use_oidc" is set to true.
 |
| `workload_type` | enum | deployment | Workload type to rollout image.
Must be "pod", "replicationcontroller", "deployment", "daemonset", "statefulset", "cronjob", or "replicaset".
 |

## Executors

### default

The docker container to use when running this orb's jobs


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image` | string | cimg/python | Docker image name |
| `tag` | string | 3.8 | Image tag |

## Examples

### create-cluster

Create a GKE cluster.
Recommendation: Clusters created using this command are meant to be ephemeral. Therefore they must be deleted by the end of the pipeline.


```yaml
version: '2.1'
orbs:
  gke: circleci/gcp-gke@3.0
workflows:
  main:
    jobs:
      - gke/create-cluster:
          cluster: gcp-testing
      - steps:
          run: gcloud container clusters list
      - gke/delete-cluster:
          cluster: gcp-testing
```

### create-node-pool-for-windows

Create a node pool for Windows container usage


```yaml
version: '2.1'
orbs:
  gke: circleci/gcp-gke@3.0
workflows:
  main:
    jobs:
      - gke/create-cluster:
          additional_args: '--cluster-version=1.22.12-gke.2300 --enable-ip-alias --num-nodes=1'
          cluster: gcp-testing
      - gke/create-node-pool:
          additional_args: >-
            --image-type=WINDOWS_LTSC_CONTAINERD --no-enable-autoupgrade
            --machine-type=n1-standard-2 --num-nodes=1
          cluster: gcp-testing
          node-pool: my-windows-node-pool
          requires:
            - gke/create-cluster
```

### delete-cluster

Delete a GKE cluster


```yaml
version: '2.1'
orbs:
  gke: circleci/gcp-gke@3.0
workflows:
  main:
    jobs:
      - gke/delete-cluster:
          cluster: gcp-testing
```

### publish-and-rollout-artifact-image

"The example of using this Orb when using Artifact Registry instead of Container Registry. Logs into GCP, builds and publishes a Docker image into Artifact Registry, and then rolls the image out to a GKE cluster."


```yaml
version: '2.1'
orbs:
  gke: circleci/gcp-gke@3.0
workflows:
  main:
    jobs:
      - gke/publish-and-rollout-image:
          cluster: gcp-testing
          container: app
          deployment: demo
          image: myimage
          registry_url: us-docker.pkg.dev
          repository: docker-repositories
          tag: $CIRCLE_SHA1
```

### publish-and-rollout-image

"The simplest example of using this Orb. Logs into GCP, builds and publishes a Docker image, and then rolls the image out to a GKE cluster."


```yaml
version: '2.1'
orbs:
  gke: circleci/gcp-gke@3.0
workflows:
  main:
    jobs:
      - gke/publish-and-rollout-image:
          cluster: gcp-testing
          container: app
          deployment: demo
          image: myimage
          tag: $CIRCLE_SHA1
```