Install Config Connector manually
This page explains how to manually install Config Connector.
For more information about the different installation options, see Choosing an installation type.
Installing with the manual method provides you with faster updates than using the add-on.
Config Connector is configured as cluster mode in the instructions below, which means there will be one global Config Connector controller that is impersonated as a single Google Cloud IAM service account. As you add more Config Connector resources and introduce more Kubernetes namespaces in the same cluster, you might want to consider switching to namespaced mode, which is more scalable and offers better IAM permission isolation for multi-tenant use cases, for example managing resources from multiple Google Cloud projects.
Before you begin
Before you manually install Config Connector Operator, complete the following steps:
- Create or identify a GKE cluster where Config Connector has not yet been installed and that has Workload Identity and Kubernetes Engine Monitoring enabled.
- Configure
kubectl
to connect to your cluster.
Installing the Config Connector Operator
Config Connector uses a Kubernetes Operator to keep its installation up to date. To install this Operator, complete the following steps:
Download the latest Config Connector Operator tar file:
gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
Extract the tar file:
tar zxvf release-bundle.tar.gz
Install the Config Connector operator on your cluster:
For GKE Autopilot clusters:
kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
For GKE Standard clusters:
kubectl apply -f operator-system/configconnector-operator.yaml
Creating an identity
Config Connector creates and manages Google Cloud resources by authenticating with a 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:
-
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: Replacegcloud iam service-accounts create SERVICE_ACCOUNT_NAME
SERVICE_ACCOUNT_NAME
with a name for your service account. -
Give the IAM service account elevated permissions on your project:
Replace the following:gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/editor"
PROJECT_ID
with your project ID.SERVICE_ACCOUNT_NAME
with your service account's name.
-
Create an IAM policy binding between the IAM
service account and the predefined Kubernetes service account that
Config Connector runs:
Replace the following: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"
SERVICE_ACCOUNT_NAME
with your service account's name.PROJECT_ID
with your project ID.
To learn more about creating service accounts, see Creating and managing service accounts.
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:
-
Copy the following YAML file into a file named
configconnector.yaml
: Replace the following:# 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
SERVICE_ACCOUNT_NAME
with your service account's name.PROJECT_ID
with your project ID.
-
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.
If you do not have a Namespace for this purpose, create one withkubectl
.
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.
Project
To create resources in a certain project, run the following command:
kubectl annotate namespace \ NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID
Replace the following:
NAMESPACE
with your namespace name.PROJECT_ID
with your Google Cloud project ID.
Folder
To create resources in a certain folder, run the following command:
kubectl annotate namespace \ NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID
Replace the following:
NAMESPACE
with your namespace name.FOLDER_ID
with your Google Cloud folder ID.
Organization
To create resources in a certain organization, run the following command:
kubectl annotate namespace \ NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID
Replace the following:
NAMESPACE
with your namespace name.ORGANIZATION_ID
with your Google Cloud 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
To download and install the latest version of Config Connector operator:
gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
tar zxvf release-bundle.tar.gz
kubectl apply -f operator-system/configconnector-operator.yaml
Uninstalling Config Connector
Don't use the following the steps to uninstall a Config Controller cluster.
Use kubectl delete
to remove the Config Connector CRDs along with
controller components:
kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
--wait=true
To uninstall the Config Connector operator, run the following command:
kubectl delete -f operator-system/configconnector-operator.yaml --wait=true
Upgrading from non-operator installations
Config Connector version 1.33.0 and higher only supports installation with the GKE add-on, or the operator.
To upgrade to the operator (and retain all Config Connector resources), you must remove all Config Connector system components except the CRDs, and then install the operator.
Run the following commands to remove Config Connector system non-CRD 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
Install Config Connector with the GKE add-on, or the operator.
Switching from the add-on to a manual installation
When installed as an add-on, the version of Config Connector is directly tied to the GKE version that is installed.
The manual installation allows for faster updates at the cost of manual upgrades.
To switch while safely keeping all resources:
Disable the addon without deleting any
ConfigConnector
orConfigConnectorContext
objects:gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
Replace
CLUSTER_NAME
with the name of the cluster that you installed Config Connector on.Follow the instructions to install the manual operator of the desired version.
What's next
- Get started with Config Connector.
- Learn about best practices for Config Connector.