Installing on other Kubernetes distributions

---

This page shows you how to install Config Connector on a Kubernetes distribution other than Google Kubernetes Engine (GKE) on Google Cloud, for example GKE on AWS.

Before you begin

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

• Select or create a Google Cloud project to install Config Connector.
• Ensure that you have permissions to create and download a service account for the project.
• Create or identify a Kubernetes cluster where you have not yet installed Config Connector.

• Configure kubectl to connect to your cluster.

  Note: If you are installing Config Connector on a cluster not hosted on Google Cloud, you might need different kubectl configuration steps. Contact your Kubernetes provider for details.

Installing Config Connector

To install Config Connector on another Kubernetes environment, after you've created or identified a Kubernetes cluster, create an Identity and Access Management (IAM) service account, and then install the Config Connector components on your cluster.

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 the Creating an identity section.

If the output is no, create a ClusterRoleBinding in your cluster, which lets you create roles:

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

Replace ACCOUNT_EMAIL with the email you use to login to your Cloud Billing account.

The output should contain the phrase cluster-admin-binding created. If that phrase does not appear, contact your Cloud Billing account or GKE cluster administrator about permissions.

Creating an identity

Config Connector needs a Cloud Identity to communicate with other resources. To set up the identity, you create an 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.

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

In the next set of instructions, you'll import a Google Cloud Service Account Credentials key into the Kubernetes cluster. Importing Service Account Credentials directly into a cluster is generally considered insecure, especially if you run third party or custom workloads in the same cluster. This approach can potentially take advantage of node to cluster escalation loopholes and impersonate the Google Cloud service account through this secret. If you're using a GKE cluster, we recommend using Workload Identity Federation for GKE.

Creating a service account

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

To create a service account, complete the following steps:

1. Create an IAM service account. If you have an existing service account, you can use it instead of creating a new service account.

   Use the gcloud CLI to create the service account by running the following command:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
   

   Replace SERVICE_ACCOUNT_NAME with your service account's name.

   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/owner"
   

   Replace the following:

   • PROJECT_ID with your Google Cloud project ID.
   • SERVICE_ACCOUNT_NAME with your service account's name.
   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 and organization wide configurations such as IAM modifications.

3. Create a service account key and export its credentials to a file named key.json:

   gcloud iam service-accounts keys create --iam-account \
       SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com key.json
   

   Replace the following:

   • SERVICE_ACCOUNT_NAME with your service account's name.
   • PROJECT_ID with your Google Cloud project ID.

Applying the credentials to your cluster

To apply the credentials to the cluster where you want to run Config Connector, complete the following steps:

1. Create the cnrm-system namespace:

   kubectl create namespace cnrm-system
   

2. Import the key's credentials as a Secret.

   kubectl create secret generic SECRET_NAME \
       --from-file key.json \
       --namespace cnrm-system
   

   Replace SECRET_NAME with the name you want to give your Secret.

   Important: The file must be named key.json to create a valid Secret.

3. Remove the credentials from your system:

   rm key.json
   

Installing Config Connector Operator

Complete the following steps to install the Config Connector Operator:

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: You need the bundle for uninstalling Config Connector so keep a copy of the installation bundle for later use.

2. Extract the tar file:

   tar zxvf release-bundle.tar.gz
   

3. Install the Config Connector Operator on your cluster:

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

Configuring Config Connector

To configure Config Connector using the operator, you create a configuration file for the ConfigConnector CustomResource, then apply it using the kubectl apply command.

To configure Config Connector using the operator:

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

   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnector
   metadata:
     # the name is restricted to ensure that there is only ConfigConnector
     # instance installed in your cluster
     name: configconnector.core.cnrm.cloud.google.com
   spec:
     mode: cluster
     credentialSecretName: SECRET_NAME
     stateIntoSpec: Absent
   

   Replace SECRET_NAME with the name of the Secret that you created earlier.

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

Important: Downgrading directly is not supported. To downgrade Config Connector, you must uninstall, reinstall Config Connector, then re-apply your resources.

To upgrade Config Connector, download and install the latest version of the 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

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

What's next

• Learn more about choosing an installation type.
• Learn how to troubleshoot Config Connector.