This topic describes how to install Config Connector on your cluster.
Before you begin
To prepare for this task, perform the following steps:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
- 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
- You must configure
kubectl
to connect to your clusters. Follow the steps for GKE clusters or GKE On-Prem clusters.
Choosing your installation method
You can install Config Connector with either a Google Cloud Identity Service Account or a GKE Workload Identity.
GCP Identity
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 account or 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 withgcloud
:gcloud iam service-accounts create cnrm-system
Give the IAM Service Account elevated permissions on your project. Replace [PROJECT_ID] with your project ID.
gcloud projects add-iam-policy-binding [PROJECT_ID] \
--member serviceAccount:cnrm-system@[PROJECT_ID].iam.gserviceaccount.com \ --role roles/ownerCreate a Service Account Key and export its credentials to a file. Replace [PROJECT_ID] with your project ID and run the following:
gcloud iam service-accounts keys create --iam-account \
cnrm-system@[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
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:
curl -X GET -sLO \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ --location-trusted \ https://us-central1-cnrm-eap.cloudfunctions.net/download/latest/infra/install-bundle.tar.gz
Extract the tar file:
tar zxvf install-bundle.tar.gz
Apply the manifests to your cluster:
kubectl apply -f install-bundle/
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.
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 withgcloud
:gcloud iam service-accounts create cnrm-system
Give the IAM Service Account elevated permissions on your project. Replace [PROJECT_ID] with your project ID.
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 KCC.
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 tarball:
curl -X GET -sLO \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ --location-trusted \ https://us-central1-cnrm-eap.cloudfunctions.net/download/latest/infra/install-bundle-with-workload-identity.tar.gz
Extract the tar file.
tar zxvf install-bundle-with-workload-identity.tar.gz
Replace ${PROJECT_ID?} with your project ID in the installation manifest.
sed -i 's/${PROJECT_ID?}/[PROJECT_ID]/' install-bundle/0-cnrm-system.yaml
Apply the manifests to your cluster.
kubectl apply -f install-bundle/
Verify Your Installation
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
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
The installation bundle or samples archive is empty or seems to be corrupted.
Verify your authorization token with gcloud auth print-access-token
. A
valid token is a long string beginning with text similar to
ya29.XXXXXXX...X
.
gcloud auth print-access-token
If the token is not valid, re-authenticate to Google Cloud.
After authenticating, re-deploy Config Connector.
Manually uninstall Config Connector
To manually uninstall Config Connector, delete the installation bundle from your cluster.
From the same folder containing the contents of the unpacked tar file from the manual installation, run this command to delete:
kubectl delete -f install-bundle/crds.yaml \
kubectl delete -f install-bundle/0-cnrm-system.yaml
Upgrading Config Connector
To manually upgrade Config Connector:
- Run the manual uninstall steps
- Run the manual install steps
What's next
Get started with Config Connector.