Skip to main content
Version: v2.5

Managing GKE Clusters


Some setup in Google Kubernetes Engine is required.

Service Account Token

Create a service account using Google Kubernetes Engine. GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication.

The service account requires the following roles:

  • Compute Viewer: roles/compute.viewer
  • Project Viewer: roles/viewer
  • Kubernetes Engine Admin: roles/container.admin
  • Service Account User: roles/iam.serviceAccountUser

Google Documentation: Creating and Enabling Service Accounts

For help obtaining a private key for your service account, refer to the Google cloud documentation here. You will need to save the key in JSON format.

Google Project ID

Your cluster will need to be part of a Google Project.

To create a new project, refer to the Google cloud documentation here.

To get the project ID of an existing project, refer to the Google cloud documentation here.

Provisioning a GKE Cluster

Note Deploying to GKE will incur charges.

1. Create a Cloud Credential

  1. In the upper right corner, click the user profile dropdown menu and click Cloud Credentials.
  2. Click Add Cloud Credential.
  3. Enter a name for your Google cloud credentials.
  4. In the Cloud Credential Type field, select Google.
  5. In the Service Account text box, paste your service account private key JSON, or upload the JSON file.
  6. Click Create.

Result: You have created credentials that Rancher will use to provision the new GKE cluster.

2. Create the GKE Cluster

Use Rancher to set up and configure your Kubernetes cluster.

  1. From the Clusters page, click Add Cluster.
  2. Under With a hosted Kubernetes provider, click Google GKE.
  3. Enter a Cluster Name.
  4. Optional: Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
  5. Optional: Add Kubernetes labels or annotations to the cluster.
  6. Enter your Google project ID and your Google cloud credentials.
  7. Fill out the rest of the form. For help, refer to the GKE cluster configuration reference.
  8. Click Create.

Result: You have successfully deployed a GKE cluster.

Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

You can access your cluster after its state is updated to Active.

Active clusters are assigned two Projects:

  • Default, containing the default namespace
  • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

Private Clusters

Private GKE clusters are supported. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see this section.

Configuration Reference

For details on configuring GKE clusters in Rancher, see this page.

Updating Kubernetes Version

The Kubernetes version of a cluster can be upgraded to any version available in the region or zone for the GKE cluster. Upgrading the master Kubernetes version does not automatically upgrade worker nodes. Nodes can be upgraded independently.

Note GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the Google documentation. After this, the Kubernetes version can be updated to 1.19+ via Rancher.


The GKE provisioner can synchronize the state of a GKE cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

For information on configuring the refresh interval, see this section.