Skip to main content
Version: v2.9

Creating a GKE Cluster

Prerequisites​

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​

caution

Deploying to GKE will incur charges.

1. Create a Cloud Credential​

  1. Click ☰ > Cluster Management.
  2. In the left navigation bar, click Cloud Credentials.
  3. Click Create.
  4. Enter a name for your Google cloud credentials.
  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. To successfully create a GKE cluster with Rancher, your GKE must be in Standard mode. GKE has two modes of operation when creating a Kubernetes cluster, Autopilot and Standard mode. The cluster configuration for Autopilot mode has restrictions on editing the kube-system namespace. However, Rancher needs to create resources in the kube-system namespace during installation. As a result, you will not be able to create a GKE cluster in Autopilot mode. For more information about the difference between GKE Autopilot mode and Standard mode, visit Compare GKE Autopilot and Standard.

  1. Click ☰ > Cluster Management.
  2. On the Clusters page, click Create.
  3. Click Google GKE.
  4. Enter a Cluster Name.
  5. 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.
  6. Optional: Add Kubernetes labels or annotations to the cluster.
  7. Enter your Google project ID and your Google cloud credentials.
  8. Fill out the rest of the form. For help, refer to the GKE cluster configuration reference.
  9. 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.

Syncing​

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.

Programmatically Creating GKE Clusters​

The most common way to programmatically deploy GKE clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.