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:

1. Download the latest Config Connector Operator tar file:

   gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
   

   Note: Keep a copy of the installation bundle as you need this bundle to uninstall Config Connector.

2. Extract the tar file:

   tar zxvf release-bundle.tar.gz
   

3. Install the Config Connector operator on your cluster:

   1. For GKE Autopilot clusters:

      kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
      

   2. 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 an Identity and Access Management (IAM) service account and using GKE's Workload Identity to bind IAM service accounts with Kubernetes service accounts.

Note: You only need to perform these steps once per cluster.

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.
   Note: Granting the editor role allows most Config Connector functionality except project and organization wide configurations such as IAM modifications. In a production environment, we recommend that you set more granular permissions. For more information about IAM roles, see Understanding roles.
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.

If you do not have a Namespace for this purpose, create one with kubectl.

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

Note: The controller Pod can take several minutes to start.

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

Downgrading Config Connector

Fully downgrading Config Connector is not supported. To downgrade both the Config Connector operator and CRDs, you must uninstall, reinstall Config Connector, and then re-apply your resources.

In Config Connector version 1.123.1 and later, you can roll back the operator version for installations that use namespaced mode. In each namespace that has an operator you want to roll back, set the spec.version field in the ConfigConnectorContext object to the previous Config Connector version.

You can roll back the Config Connector controller by a maximum of 3 minor versions. You must always roll back to the latest patch version for a given minor version.

Uninstalling Config Connector

Caution: 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.

1. 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
   

2. 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:

1. Disable the addon without deleting any ConfigConnector or ConfigConnectorContext 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.

2. Follow the instructions to install the manual operator of the desired version.

Note: Because the namespace-id ConfigMap in the configconnector-operator-system namespace is deleted as part of disabling the addon, old cnrm-controller-manager StatefulSets are recreated.

What's next

• Get started with Config Connector.
• Learn about best practices for Config Connector.