Installing, upgrading, and uninstalling Config Connector

This topic describes how to install Config Connector on your cluster.

Before you begin

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

Ensure that you have enabled the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

Ensure that you have installed the Cloud SDK.

Set up default gcloud settings using one of the following methods:

Using gcloud init, if you want to be walked through setting defaults.
Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

Run gcloud init and follow the directions:
```
gcloud init
```
If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:
```
gcloud init --console-only
```
Follow the instructions to authorize gcloud to use your Google Cloud account.
Create a new configuration or select an existing one.
Choose a Google Cloud project.
Choose a default Compute Engine zone.

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region flags.

Using gcloud config

Set your default project ID:
```
gcloud config set project project-id
```
If you are working with zonal clusters, set your default compute zone:
```
gcloud config set compute/zone compute-zone
```
If you are working with regional clusters, set your default compute region:
```
gcloud config set compute/region compute-region
```
Update gcloud to the latest version:
```
gcloud components update
```

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region flags.

Select a Google Cloud project where you will install Config Connector.

Choosing your installation type

You can install Config Connector in one of the following ways:

Using a Google Cloud Identity Service Account,
Using a GKE Workload Identity, or
Using Namespaced mode, to support managing multiple projects, each with their own Google Cloud identities.

For more information on these installation types, see Choosing an installation type.

Select a tab below to choose your installation type.

GCP Identity

Prerequisites

Before you can install Config Connector, perform the following steps:

Creating a ClusterRoleBinding

Config Connector needs permission to create Kubernetes Roles before it can create resources.

Verify that you can create Roles by running the following command.

kubectl auth can-i create roles

If the output is yes, continue to Create an Identity.

If the output is no, create a ClusterRoleBinding in your cluster. This allows you to create Roles. Replace [ACCOUNT_EMAIL] with the email associated with your Google Cloud account.

kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole cluster-admin \
--user [ACCOUNT_EMAIL]

The outputs should contain the phrase cluster-admin-binding created. If it does not, contact your Google Cloud account or GKE cluster administrator about permissions.

Creating an identity

A Config Connector cluster needs a Google Cloud identity to communicate with other resources. To set up the identity, you create an Cloud Identity and Access Management (Cloud IAM) Service Account and Service Account Key. After that, you import the Key's credentials as a Secret in each cluster that runs Config Connector.

Creating a service account

Create the cnrm-system Service Account with gcloud:
```
gcloud iam service-accounts create cnrm-system
```
Give the IAM Service Account elevated permissions on your project. Replace [HOST_PROJECT_ID] with your project ID.

Note: If you prefer to grant editor access to the project replace roles/owner with roles/editor. Granting the editor role allows most Config Connector functionality except [project/organization] wide configurations such as Cloud IAM modifications.
```
gcloud projects add-iam-policy-binding [HOST_PROJECT_ID] \
--member serviceAccount:cnrm-system@[HOST_PROJECT_ID].iam.gserviceaccount.com \
--role roles/owner
```
Create a Service Account Key and export its credentials to a file named key.json. Replace [HOST_PROJECT_ID] with your project ID and run the following:
```
gcloud iam service-accounts keys create --iam-account \
cnrm-system@[HOST_PROJECT_ID].iam.gserviceaccount.com key.json
```

Applying credentials to your cluster

Apply the credentials to each cluster where you will run Config Connector.

Create the cnrm-system namespace.
```
kubectl create namespace cnrm-system
```
Import the key's credentials as a Secret.
```
kubectl create secret generic gcp-key --from-file key.json --namespace cnrm-system
```
Note: The file must be named key.json to create a valid Secret.
Remove the credentials from your system.
```
rm key.json
```

Installing Config Connector

To manually install Config Connector, download the installation tar file and extract it, then apply the contents to your cluster.

Download the latest installation bundle tar file:
```
gsutil cp gs://cnrm/latest/release-bundle.tar.gz release-bundle.tar.gz
```
Note: You need the bundle for upgrading or uninstalling Config Connector. Keep a copy of the installation bundle for later use.
Extract the tar file:
```
tar zxvf release-bundle.tar.gz
```

Apply the manifests to your cluster:

kubectl apply -f install-bundle-gcp-identity/

Workload Identity

Prerequisites

Before you install Config Connector to a cluster, perform the following steps.

Create or identify a GKE cluster where Config Connector has not yet been installed.
Set up Workload Identity on the cluster where you will install Config Connector.
Configure kubectl to connect to your cluster.

Create an Identity

Setting up the identity includes:

Creating an Cloud IAM Service Account.
Creating a binding between the Cloud IAM Service Account and Config Connector's Kubernetes service account.

Create the cnrm-system Service Account with gcloud:
```
gcloud iam service-accounts create cnrm-system
```
Give the IAM Service Account elevated permissions on your project. Replace [PROJECT_ID] with your project ID.

Note: If you prefer to grant editor access to the project replace roles/owner with roles/editor. Granting the editor role allows most Config Connector functionality except [project/organization] wide configurations such as Cloud IAM modifications.
```
gcloud projects add-iam-policy-binding [PROJECT_ID] \
--member="serviceAccount:cnrm-system@[PROJECT_ID].iam.gserviceaccount.com" \
--role="roles/owner"
```

Create a Cloud IAM policy binding between the IAM Service Account and the predefined Kubernetes service account run by Config Connector. Replace [PROJECT_ID] with your project ID.

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

Deploying Config Connector

Download the latest installation bundle tar file:
```
 gsutil cp gs://cnrm/latest/release-bundle.tar.gz release-bundle.tar.gz
```
Note: You need the bundle for upgrading or uninstalling Config Connector. Keep a copy of the installation bundle for later use.
Extract the tar file.
```
tar zxvf release-bundle.tar.gz
```
Provide your project ID in the controller's installation manifest. Before running the following command, replace [PROJECT_ID] with your project ID.
```
sed -i.bak 's/${PROJECT_ID?}/[PROJECT_ID]/' install-bundle-workload-identity/0-cnrm-system.yaml
```

Apply the manifests to your cluster.

kubectl apply -f install-bundle-workload-identity/

Namespaced mode

Namespaced mode is an extension of the Workload Identity installation. It allows you to manage multiple projects with multiple Google service accounts bound to your your Config Connector cluster. For more information, see Choosing an installation type.

Prerequisites

For the rest of this section, the Google Cloud project where you install Config Connector is known as the host project, or [HOST_PROJECT_ID]. The other projects where you manage resources are known as the managed projects, or [MANAGED_PROJECT_ID].

Before you install Config Connector to a cluster, perform the following steps.

Create or identify a GKE cluster where Config Connector has not yet been installed.
Set up Workload Identity on the cluster where you will install Config Connector.
Configure kubectl to connect to your cluster.

Install Config Connector

Download the latest installation bundle tar file:
```
gsutil cp gs://cnrm/latest/release-bundle.tar.gz release-bundle.tar.gz
```
Note: You need the bundle for upgrading or uninstalling Config Connector. Keep a copy of the installation bundle for later use.
Extract the tar file.
```
tar zxvf release-bundle.tar.gz
```
Replace ${PROJECT_ID?} in the installation manifest with your host project ID. Before running the following command, replace [HOST_PROJECT_ID] with your project ID.
```
sed -i.bak 's/${PROJECT_ID?}/[HOST_PROJECT_ID]/' install-bundle-namespaced/0-cnrm-system.yaml
```

Install the common Config Connector components on your cluster.

kubectl apply -f install-bundle-namespaced/0-cnrm-system.yaml \
 -f install-bundle-namespaced/crds.yaml

Set up your namespaces

Next, set up a namespace and a service account for each managed project.

Create a service account for the Namespace in the host project. Replace [HOST_PROJECT_ID] with your host project ID and [NAMESPACE] with your Namespace name.
```
gcloud iam service-accounts create cnrm-system-[NAMESPACE] --project [HOST_PROJECT_ID]
```
Give the Cloud IAM Service Account elevated permissions on the managed project. Replace:
- [NAMESPACE] with your Namespace name,
- [MANAGED_PROJECT_ID] with your managed project's ID, and
- [HOST_PROJECT_ID] with your host project ID.
Note: If you prefer to grant editor access to the project replace roles/owner with roles/editor. Granting the editor role allows most Config Connector functionality except Project or Organization wide configurations such as Cloud IAM modifications.
```
gcloud projects add-iam-policy-binding [MANAGED_PROJECT_ID] \
--member="serviceAccount:cnrm-system-[NAMESPACE]@[HOST_PROJECT_ID].iam.gserviceaccount.com" \
--role="roles/owner"
```
Create a Cloud IAM policy binding between the IAM Service Account and the Kubernetes service account created by Config Connector. Replace [HOST_PROJECT_ID] with your host project ID and [NAMESPACE] with your Namespace name.
```
gcloud iam service-accounts add-iam-policy-binding cnrm-system-[NAMESPACE]@[HOST_PROJECT_ID].iam.gserviceaccount.com \
--member="serviceAccount:[HOST_PROJECT_ID].svc.id.goog[cnrm-system/cnrm-controller-manager-[NAMESPACE]]" \
--role="roles/iam.workloadIdentityUser" \
--project [HOST_PROJECT_ID]
```
Note: You might need to enable APIs for the resources you manage in both the host and managed projects.
If the Namespace doesn't exist, create it with kubectl. Replace [NAMESPACE] with your Namespace name.
```
kubectl create namespace [NAMESPACE]
```

Set up the Config Connector namespace components for the Namespace. Replace [HOST_PROJECT_ID] with your host project ID and [NAMESPACE] with your Namespace name.

sed -e 's/${HOST_PROJECT_ID?}/[HOST_PROJECT_ID]/' \
-e 's/${NAMESPACE?}/[NAMESPACE]/' \
install-bundle-namespaced/per-namespace-components.yaml > install-bundle-namespaced/per-namespace-components-[NAMESPACE].yaml

Install the Config Connector namespace components for your Namespace. Replace [NAMESPACE] with your Namespace name.
```
kubectl apply -f install-bundle-namespaced/per-namespace-components-[NAMESPACE].yaml
```
Set the project ID annotation for the Namespace. Config Connector uses this to map resources in this Namespace to the project ID. Replace [MANAGED_PROJECT_ID] with your managed project's ID and [NAMESPACE] with your Namespace name.
```
kubectl annotate namespace [NAMESPACE] cnrm.cloud.google.com/project-id=[MANAGED_PROJECT_ID]
```

Verify Your Installation

GCP and Workload Identity

Config Connector runs a single system process named cnrm-system. You can verify the pod for this process has a STATUS of Running, by executing the following command:

kubectl wait -n cnrm-system \
--for=condition=Initialized pod \
cnrm-controller-manager-0

Namespaced mode

If you installed Config Connector in Namespaced mode, run the following command once per Namespace. Replace [NAMESPACE] with your Namespace name.

kubectl wait -n cnrm-system \
--for=condition=Initialized pod \
cnrm-controller-manager-[NAMESPACE]-0

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

pod/cnrm-controller-manager-0 condition met

Setting your default namespace

You can simplify commands and avoid adding `--namespace` to each `kubectl` command by changing the default context's Namespace. To do so, run the following command, replacing [NAMESPACE_NAME] with your Namespace name:

kubectl config set-context --current --namespace [NAMESPACE_NAME]

Troubleshooting

CRD instances can be created, but nothing seems to happen. There are no events.

Check the logs from the Config Connector controller:

kubectl logs cnrm-controller-manager-0 --namespace=cnrm-system

Troubleshooting Google Cloud identity installations

If the pod with name like cnrm-controller-manager-X does not have status Running, try reinstalling the Google Cloud Service Account credentials by first deleting the existing secret (kubectl --namespace=cnrm-system delete secret gcp-key) and then following the instructions to create the Secret. Then, delete the controller pod to trigger a restart:

kubectl delete pod --namespace=cnrm-system cnrm-controller-manager-0

Manually uninstall Config Connector

To manually uninstall Config Connector, remove all artifacts from your cluster:

kubectl delete sts,po -n cnrm-system -l cnrm.cloud.google.com/component=cnrm-controller-manager --wait=true
  kubectl delete crds -l cnrm.cloud.google.com/system=true --wait=true
  kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
  kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
  kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
  kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
  kubectl delete namespace cnrm-system --ignore-not-found --wait=true

Upgrading Config Connector

Upgrading Config Connector will preserve the state of the Google Cloud resources in your cluster while upgrading the system components.

To upgrade Config Connector:

Remove the system components:

kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true

Run the manual install steps

What's next

Get started with Config Connector.