Installing with the GKE add-on

Standard

This page describes how to install Config Connector on a Google Kubernetes Engine (GKE) cluster using the Config Connector add-on.

For details on each installation options with their advantages and disadvantages, see Choosing an installation type.

Before you begin

Before you start, make sure that you have performed the following tasks:

Enable the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running the gcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.
Note: For existing gcloud CLI installations, make sure to set the compute/region property. If you use primarily zonal clusters, set the compute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

Select or create a Google Cloud project to install Config Connector in.
If you've previously manually installed Config Connector, uninstall it before installing the Config Connector add-on:
- Uninstalling cluster mode
- Uninstalling namespaced mode

Installing the Config Connector add-on

You use the Config Connector add-on by creating a new GKE cluster, or enabling it on an existing cluster. After installing the Config Connector add-on, you configure your Config Connector installation with your Google service accounts and your namespaces.

Requirements

The Config Connector add-on has the following requirements:

You must use a GKE version of:
- 1.15.11-gke.5 and later
- 1.16.8-gke.8 and later
- 1.17.4-gke.5 and later
You must enable a workload identity pool and Kubernetes Engine Monitoring on the clusters where you enable Config Connector.

Setting up a GKE cluster

You can use the Config Connector add-on on a new or existing cluster.

Creating a new cluster with the Config Connector add-on enabled

You can create a GKE cluster using the gcloud CLI or the Google Cloud console.

gcloud

To create a cluster with the Google Cloud CLI run the following command:

gcloud container clusters create CLUSTER_NAME \
    --release-channel CHANNEL \
    --addons ConfigConnector \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --logging=SYSTEM \
    --monitoring=SYSTEM

Replace the following:

CLUSTER_NAME with the name of your GKE cluster.
CHANNEL with a GKE release channel, rapid and regular are supported.
PROJECT_ID with your Google Cloud project ID.

Google Cloud console

To create a cluster with the Google Cloud console, perform the following steps:

Visit the Google Kubernetes Engine menu in Google Cloud console.

Visit the Google Kubernetes Engine menu
Click Create. The Create a Kubernetes cluster page appears.
Specify a Name for your cluster.
Choose a supported Master version.
Configure the rest of your cluster as you want.
From the navigation pane, under Cluster, click Security.
Select the Enable Workload Identity checkbox.
From the navigation pane on the left side, under Cluster, click Features.
Select the Enable Config Connector checkbox.
Click Create.

After you've created the cluster, move on to Creating an identity.

Enabling the Config Connector add-on on an existing cluster

You can enable the Config Connector add-on on an existing GKE cluster with gcloud or the Google Cloud console.

Prerequisites

Enabling the Config Connector add-on on an existing cluster has the following prerequisites:

You need a cluster that meets the requirements for the Config Connector add-on.
Set up Workload Identity Federation for GKE on the cluster where you want to install Config Connector.

Note: Enabling Workload Identity Federation for GKE on an existing cluster does not automatically enable Workload Identity Federation for GKE on the cluster's existing node pools. We recommend that you enable Workload Identity Federation for GKE on all your cluster's node pools since Config Connector could run on any of them.

To enable Workload Identity Federation for GKE for a node pool, use the gcloud command-line tool:

gcloud container node-pools update NODE_POOL \
    --workload-metadata=GKE_METADATA \
    --cluster CLUSTER_NAME

Replace the following:

NODE_POOL with your node pool's name
CLUSTER_NAME with your cluster's name

Enabling the Config Connector add-on

You can enable the Config Connector add-on in an existing GKE cluster with the Google Cloud CLI or the Google Cloud console.

gcloud

To enable the Config Connector add-on in an existing GKE cluster use the Google Cloud CLI:

gcloud container clusters update CLUSTER_NAME \
    --update-addons ConfigConnector=ENABLED

Replace CLUSTER_NAME with the name of your GKE cluster.

Google Cloud console

Visit the Google Kubernetes Engine menu in Google Cloud console.

Visit the Google Kubernetes Engine menu
Select the cluster that you want to install Config Connector on. The Cluster Details page appears.
Under the Features section, locate the Config Connector row and click Edit.
Select the Enable Config Connector checkbox and click