Installing with the GKE add-on

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 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 gcloud components update.

• 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 container clusters create CLUSTER_NAME \
    --release-channel CHANNEL \
    --addons ConfigConnector \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --logging=SYSTEM \
    --monitoring=SYSTEM

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 on the cluster where you want to install Config Connector.

To enable Workload Identity 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 container clusters update CLUSTER_NAME \
    --update-addons ConfigConnector=ENABLED

Creating an identity

Config Connector creates and manages Google Cloud resources by authenticating with an Identity and Access Management (IAM) service account and using GKE's Workload Identity to bind IAM service accounts with Kubernetes service accounts.

To create the identity, complete the following steps:

1. Create an IAM service account. If you want to use an existing service account, you can use that account and skip this step.
   
   To create the service account, use the following command:

     gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for your service account.

To learn more about creating service accounts, see Creating and managing service accounts.

2. Give the IAM service account elevated permissions on your project:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/editor"

   Replace the following:
   • PROJECT_ID with your project ID.
   • SERVICE_ACCOUNT_NAME with your service account's name.
3. Create an IAM policy binding between the IAM service account and the predefined Kubernetes service account that Config Connector runs:

   gcloud iam service-accounts add-iam-policy-binding \
   SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
       --role="roles/iam.workloadIdentityUser"

   Replace the following:
   • SERVICE_ACCOUNT_NAME with your service account's name.
   • PROJECT_ID with your project ID.

Configuring Config Connector

To complete the installation, create a configuration file for the ConfigConnector CustomResource, then apply it using the kubectl apply command. The Config Connector Operator installs Google Cloud resource CRDs and Config Connector components in your cluster.

To configure the operator as cluster mode, complete the following steps:

1. Copy the following YAML file into a file named configconnector.yaml:

   # configconnector.yaml
   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnector
   metadata:
     # the name is restricted to ensure that there is only one
     # ConfigConnector resource installed in your cluster
     name: configconnector.core.cnrm.cloud.google.com
   spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
     # Setting `stateIntoSpec` to `Absent` is recommended. It means setting `cnrm.cloud.google.com/state-into-spec`
     # annotation to `absent` for all Config Connector resources created in the cluster in the future.
     # It prevents Config Connector from populating unspecified fields into the spec.
     stateIntoSpec: Absent
   

   Replace the following:
   • SERVICE_ACCOUNT_NAME with your service account's name.
   • PROJECT_ID with your project ID.
2. Apply the configuration to your cluster with kubectl apply:

     kubectl apply -f configconnector.yaml

Specifying where to create your resources

Config Connector can organize resources by project, folder, or organization, which is the same way you would organize resources with Google Cloud.

Before creating resources with Config Connector, you must configure where to create your resources. To determine where to create the resource, Config Connector uses an annotation on either the resource configuration or an existing Namespace. For more information, see Organizing resources.

kubectl create namespace NAMESPACE

Replace NAMESPACE with your namespace name. For example config-connector.

Select a tab to choose where you want Config Connector to create resources.

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

When you annotate your namespace, Config Connector creates resources in the corresponding project, folder or organization. To learn more about how Config Connector uses Kubernetes namespaces, see Kubernetes Namespaces and Google Cloud projects.

Verifying your installation

Config Connector runs all of its components in a namespace named cnrm-system. You can verify the Pods are ready by running the following command:

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

If Config Connector is installed correctly, the output is similar to the following:

pod/cnrm-controller-manager-0 condition met

Upgrading Config Connector

Upgrades to your cluster's Config Connector add-on are managed by Google Cloud.

The resources in your cluster are preserved whenever an upgrade occurs.

Read about how Google Cloud manages Config Connector add-on upgrades, or skip to how to get the latest Config Connector version.

How Google Cloud manages Config Connector add-on upgrades

The Config Connector version that a GKE cluster gets depends entirely on the cluster's GKE minor version. For example:

As versions qualify, Google Cloud re-maps the newest GKE minor versions to a newly released Config Connector version. This is done for all the GKE minor versions that are new enough to not be available on the Regular or Stable release channels.

Since the Config Connector version that a cluster gets depends on the cluster's GKE minor version, there are two cases where a cluster's Config Connector add-on is automatically upgraded by Google Cloud:

1. The cluster is upgraded to a new GKE minor version that is mapped to a newer Config Connector version.

2. The cluster is on a GKE minor version that is new enough to not be available on the Regular or Stable release channels, and Google Cloud re-maps that GKE minor version to a new Config Connector version.

When Google Cloud re-maps a GKE minor version and upgrades existing clusters to a new Config Connector version, it is said to be "rolling out a new Config Connector version" to that GKE minor version.

Google Cloud does not roll out new Config Connector versions to GKE minor versions that are old enough to be available on the Regular or Stable release channels versions for stability reasons, except in emergency situations where a widespread issue has been detected.

How to get the latest Config Connector version

The version of Config Connector installed through the Config Connector add-on is often behind by up to 12 months or more. If you need the latest Config Connector version, we recommend switching to Config Controller or manually installing Config Connector and performing upgrades yourself. The migration instructions for each option are:

• To switch to Config Controller, follow the Config Controller migration instructions to migrate your existing Config Connector resources to a Config Controller instance.

• To manually install Config Connector, follow the instructions to switch from Config Connector add-on to Manual installation.

Uninstalling Config Connector

To uninstall Config Connector, complete the following steps:

1. Use kubectl delete to remove the Config Connector CRDs along with controller components:

   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com --wait=true
   

2. Disable the Config Connector add-on in your cluster using the gcloud CLI or the Google Cloud console:

   gcloud

   To disable the Config Connector add-on with gcloud, run the following command:

   gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
   

   Replace CLUSTER_NAME with the name of the cluster that has Config Connector add-on installed.

   Cloud console

   To disable the Config Connector add-on from the Google Cloud console, perform the following steps.

   1. Go to the Google Kubernetes Engine Clusters page on the Google Cloud console and select the cluster that you want to update.

      Visit the Google Kubernetes Engine menu

   2. Click Edit. The Edit clusters screen appears.

   3. Click Add-ons.

   4. Select Config Connector and choose Disabled.

   5. Click Save to update your cluster.

What's next

• Get started with Config Connector.
• Learn how to troubleshoot Config Connector.