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, Anthos clusters on AWS (GKE on AWS).

Before you begin

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

Installing Config Connector

To install Config Connector on another Kubernetes environment, after you've created or identified a Kubernetes cluster, create a 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 allows you to 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.

Creating a service account

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

  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:

    gsutil cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
    
  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
    

    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

Upgrading Config Connector

To upgrade Config Connector, download and install the latest version of the Config Connector operator:

gsutil 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

Troubleshooting

The following section provides you with troubleshooting tips for your Config Connector installation.

Troubleshooting permissions for resource reconciliations

If Google Cloud can't reconcile resources successfully, the logs contain the following error message: The caller does not have permission, forbidden.

To investigate this error, complete the following steps:

  1. Open a shell with the cloud-sdk image:
    kubectl run -it \
        --image google/cloud-sdk:slim \
        --serviceaccount cnrm-controller-manager \
        --namespace cnrm-system \
        workload-identity-test
  2. List your identity:
    gcloud auth list
  3. Verify that the identity listed matches the Google service account bound to your resources.
  4. Verify that the Google service account has the needed roles to manage the Google Cloud resources.

What's next