Opções de instalação avançada

Neste tópico, você verá duas outras opções de instalação do Config Connector no cluster do Google Kubernetes Engine (GKE):

  • Instalação manual: as atualizações oferecidas pelo método manual de instalação são mais rápidas que as do complemento. Esse método também oferece mais opções de configuração. Por exemplo, é possível aumentar o limite da CPU do operador do Config Connector.
  • Modo com namespace: este método é uma extensão da instalação do Config Connector. O modo com namespace é compatível com o gerenciamento de vários projetos, cada um com as próprias identidades do Google Cloud.

Para mais informações sobre esses tipos de instalação, consulte Como escolher um tipo de instalação.

Como instalar manualmente o operador do Config Connector

Nas seções a seguir, mostramos como instalar manualmente o operador do Config Connector.

Antes de começar

Antes de instalar manualmente o operador do Config Connector, conclua as etapas a seguir:

Como instalar o operador do Config Connector

O Config Connector usa um Operador do Kubernetes para manter a própria instalação atualizada. Para instalar esse operador, conclua as etapas a seguir:

  1. Faça o download do arquivo .tar mais recente do operador do Config Connector:

    gsutil cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
    
  2. Extraia o arquivo tar:

    tar zxvf release-bundle.tar.gz
    
  3. Instale o operador do Config Connector no cluster:

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

Como criar uma identidade

O Config Connector cria e gerencia recursos do Google Cloud usando a autenticação com uma conta de serviço de gerenciamento de identidade e acesso (IAM) e a Identidade da carga de trabalho do GKE para vincular contas de serviço do IAM a contas de serviço do Kubernetes.

Para criar a identidade, conclua as etapas a seguir:

  1. Criar uma conta de serviço do IAM Se você quiser, poderá usar uma conta de serviço atual e pular esta etapa.

    Para criar a conta de serviço, use o seguinte comando:
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
    Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço.
  2. Para saber mais sobre como criar contas de serviço, consulte Como criar e gerenciar contas de serviço.

  3. Conceda à Conta de serviço do IAM permissões elevadas no projeto:
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/owner"
    Substitua:
    • PROJECT_ID pelo código do projeto;
    • SERVICE_ACCOUNT_NAME pelo nome da conta de serviço.
  4. Crie uma vinculação de política do IAM entre a conta de serviço do IAM e a conta de serviço predefinida do Kubernetes que o Config Connector executa:
    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"
    Substitua:
    • SERVICE_ACCOUNT_NAME pelo nome da conta de serviço;
    • PROJECT_ID pelo código do projeto;

Como configurar o Config Connector

Para concluir a instalação, crie um arquivo de configuração para oConfigConnector Recurso personalizado e aplique-o usando okubectl apply. O operador do Config Connector instala as CRDs do Google Cloud Resource e os componentes do Config Connector no cluster.

Para configurar o operador, conclua as seguintes etapas:

  1. Copie o seguinte arquivo do YAML para um arquivo chamado 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"
    
    Substitua:
    • SERVICE_ACCOUNT_NAME pelo nome da conta de serviço;
    • PROJECT_ID pelo código do projeto;
  2. Aplique a configuração ao cluster com kubectl apply:
      kubectl apply -f configconnector.yaml

Como especificar o local para criar os recursos

O Config Connector pode organizar recursos por projeto, pasta ou organização, da mesma forma que você organizaria recursos com o Google Cloud.

Antes de criar recursos com o Config Connector, você precisa configurar onde criar seus recursos. Para determinar onde criar o recurso, o Config Connector usa uma anotação na configuração do recurso ou em um namespace atual. Para mais informações, consulte Como organizando recursos.

Se você não tiver um namespace para essa finalidade, crie um com kubectl.
kubectl create namespace NAMESPACE

Substitua NAMESPACE pelo nome do namespace. Por exemplo: config-connector.

Selecione uma guia para escolher onde quer que o Config Connector crie recursos.

Projeto

Para criar recursos em determinado projeto, execute o seguinte comando:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

Substitua:

  • NAMESPACE pelo nome do namespace;
  • PROJECT_ID pelo ID do projeto do Google Cloud.

Pasta

Para criar recursos em determinada pasta, execute o seguinte comando:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

Substitua:

  • NAMESPACE pelo nome do namespace;
  • FOLDER_ID pelo ID da pasta do Google Cloud.

Organização

Para criar recursos em determinada organização, execute o seguinte comando:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

Substitua:

  • NAMESPACE pelo nome do namespace;
  • ORGANIZATION_ID pelo ID da organização do Google Cloud.

Quando você anota o namespace, o Config Connector cria recursos no projeto, na pasta ou na organização correspondente. Para saber mais sobre como o Config Connector usa namespaces do Kubernetes, consulte Namespaces do Kubernetes e projetos do Google Cloud.

Como verificar a instalação

Todos os componentes do Config Connector são executados em um namespace chamado cnrm-system. Para verificar se os pods estão prontos, execute o comando a seguir:

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

Se o Config Connector estiver instalado corretamente, o resultado será semelhante a este:

pod/cnrm-controller-manager-0 condition met

Como fazer upgrade do Config Connector

Para fazer o download e instalar a versão mais recente do operador do Config Connector:

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

Como desinstalar o Config Connector

Use kubectl delete para remover as CRDs do Config Connector e os componentes do controlador:

kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
    --wait=true

Para desinstalar o operador do Config Connector, execute o seguinte comando:

kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true

Como instalar o Config Connector usando o modo com namespace

As seções a seguir mostram como ativar o modo com namespace.

Antes de começar

Antes de configurar o Config Connector para ser executado no modo com namespace, ative o complemento Config Connector do GKE ou instale manualmente o operador do Config Connector.

Configure o Config Connector para ser executado no modo com namespace

Para ativar o modo com namespace, siga estas etapas:

  1. Copie o seguinte manifesto do YAML para um arquivo chamado configconnector.yaml:

    apiVersion: core.cnrm.cloud.google.com/v1beta1
    kind: ConfigConnector
    metadata:
      # the name is restricted to ensure that there is only ConfigConnector resource installed in your cluster
      name: configconnector.core.cnrm.cloud.google.com
    spec:
     mode: namespaced
    
  2. Aplique a configuração ao cluster com kubectl apply:

    kubectl apply -f configconnector.yaml
    

Configurar o Config Connector para gerenciar recursos nos seus namespaces

Nas seções a seguir, o projeto do Google Cloud em que você instala o Config Connector é conhecido como projeto host ou HOST_PROJECT_ID. Os outros projetos em que você gerencia recursos são conhecidos como projetos gerenciados ou MANAGED_PROJECT_ID. Eles podem ser os mesmos projetos se você pretender usar o Config Connector apenas para criar recursos do Google Cloud no mesmo projeto do seu cluster.

Como criar um namespace

É possível ignorar essa etapa se você tiver um namespace para organizar os recursos do Google Cloud.

Use kubectl para criar um novo namespace executando o seguinte comando:

kubectl create namespace NAMESPACE

Substitua NAMESPACE por um namespace.

Como criar uma identidade

Crie uma conta de serviço de gerenciamento de identidade e acesso (IAM, na sigla em inglês) e vincule a conta de serviço do IAM e a conta de serviço do Config Connector do Kubernetes.

  1. Criar uma conta de serviço do IAM Se você tiver uma conta de serviço atual, poderá usá-la em vez de criar uma nova. Use gcloud para criar a conta de serviço executando o seguinte comando:

    gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
    

    Substitua:

    • NAMESPACE_GSA pelo nome da conta de serviço do Google (GSA), vinculada ao namespace;
    • HOST_PROJECT_ID pelo ID do projeto host.

    Para saber mais sobre como criar contas de serviço, consulte Como criar e gerenciar contas de serviço.

  2. Conceda à conta de serviço do IAM permissões elevadas no projeto gerenciado.

    gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
        --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/owner"
    

    Substitua:

    • MANAGED_PROJECT_ID pelo ID do projeto gerenciado;
    • NAMESPACE_GSA pelo nome da conta de serviço do Google, vinculada ao namespace;
    • HOST_PROJECT_ID pelo ID do projeto host.
  3. Crie uma vinculação de política do IAM entre a conta de serviço do IAM e a conta de serviço do Config Connector do Kubernetes. Para vincular as contas de serviço, execute o seguinte comando gcloud:

    gcloud iam service-accounts add-iam-policy-binding \
    NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
        --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
        --role="roles/iam.workloadIdentityUser" \
        --project HOST_PROJECT_ID
    

    Substitua:

    • HOST_PROJECT_ID pelo ID do projeto host;
    • NAMESPACE_GSA pelo nome da conta de serviço do Google, vinculada ao namespace;
    • NAMESPACE pelo namespace.
  4. Conceda à conta de serviço do IAM permissões para publicar métricas do Prometheus no pacote de operações do Google Cloud no projeto host.

    gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
        --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/monitoring.metricWriter"
    

    Substitua:

    • HOST_PROJECT_ID pelo ID do projeto host;
    • NAMESPACE_GSA pelo nome da conta de serviço do Google, vinculada ao namespace;

Como criar um ConfigConnectorContext

Para criar recursos do Google Cloud, você precisa configurar o Config Connector para observar seu namespace adicionando um objeto ConfigConnectorContext no namespace que quer usar.

Para criar um ConfigConnectorContext, conclua as etapas a seguir.

  1. Copie o seguinte manifesto do YAML para um arquivo chamado configconnectorcontext.yaml:

    apiVersion: core.cnrm.cloud.google.com/v1beta1
    kind: ConfigConnectorContext
    metadata:
      # you can only have one ConfigConnectorContext per namespace
      name: configconnectorcontext.core.cnrm.cloud.google.com
      namespace: NAMESPACE
    spec:
      googleServiceAccount: "NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com"
    

    Substitua:

    • NAMESPACE pelo nome do namespace;
    • NAMESPACE_GSA pelo nome da conta de serviço do Google, vinculada ao namespace;
    • HOST_PROJECT_ID pelo ID do projeto host.
  2. Aplique o arquivo ao cluster com kubectl:

    kubectl apply -f configconnectorcontext.yaml
    
  3. Verifique se o operador do Config Connector criou uma conta de serviço do Kubernetes para o namespace com kubectl. Para isso, execute o seguinte comando:

    kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
    

    Substitua NAMESPACE pelo nome do namespace.

  4. Verifique se o pod do controlador do Config Connector está em execução para seu namespace com kubectl. Para isso, execute o seguinte comando:

    kubectl wait -n cnrm-system \
        --for=condition=Ready pod \
        -l cnrm.cloud.google.com/component=cnrm-controller-manager \
        -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE
    

    Substitua NAMESPACE pelo nome do namespace.

    Se o controlador do Config Connector estiver em execução, a saída será semelhante a:

    cnrm-controller-manager-abcdefghijk-0 condition met.
    

Configure o Config Connector para não gerenciar mais recursos no seu namespace

Para configurar o Config Connector para não gerenciar mais seu namespace, remova todos os recursos do Config Connector no namespace e exclua o ConfigConnectorContext no namespace.

Remover os recursos do Config Connector no seu namespace

Para finalizar a remoção de ConfigConnectorContext, remova todos os recursos do Config Connector do seu namespace.

  1. Para descobrir todos os recursos do Config Connector no seu namespace, liste todos os recursos para cada definição de recurso personalizada do conector de configuração.

    kubectl get crds --selector cnrm.cloud.google.com/managed-by-kcc=true \
    -o=jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | xargs -n 1 \
    kubectl get -o jsonpath='{range .items[*]}{" Kind: "}{@.kind}{"Name: "}{@.metadata.name}{"\n"}{end}' \
    --ignore-not-found -n NAMESPACE
    

    Substitua NAMESPACE pelo nome do namespace.

  2. Para remover todos os recursos do Config Connector, para cada recurso na saída da etapa anterior, emita um comando de exclusão.

    kubectl delete -n NAMESPACE KIND NAME
    

    Substitua:

    • NAMESPACE: o nome do namespace.
    • KIND: o tipo do recurso descoberto na etapa anterior
    • NAME: o nome do recurso descoberto na etapa anterior

Remover o ConfigConnectorContext

Para configurar o Config Connector para não gerenciar mais os recursos do Config Connector no seu namespace, exclua ConfigConnectorContext no seu namespace.

  kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com

Substitua NAMESPACE pelo nome do namespace.

A exclusão de ConfigConnectorContext não será concluída até que todos os recursos do Config Connector sejam removidos do namespace.

Como fazer upgrade de instalações que não são de operador

O Config Connector 1.33.0 e versões mais recentes são compatíveis apenas com a instalação por meio do complemento do GKE ou do operador.

Para fazer upgrade para o operador (e manter todos os recursos do Config Connector), é preciso remover todos os componentes do sistema do Config Connector, exceto os CRDs, e instalar o operador.

  1. Execute os seguintes comandos para remover os componentes do sistema do Config Connector que não são CRD:

    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. Instale o Config Connector usando o complemento do GKE ou o operador.

Como migrar do complemento para uma instalação manual

Quando instalada como um complemento, a versão do Config Connector está diretamente vinculada à versão do GKE instalada.

A instalação manual permite atualizações mais rápidas com o custo dos upgrades manuais.

Para alterar enquanto mantém todos os recursos:

  1. Desative o complemento sem excluir nenhum objeto ConfigConnector ou ConfigConnectorContext:

    gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
    

    Substitua CLUSTER_NAME pelo nome do cluster em que você configurou o Config Connector.

  2. Siga as instruções para instalar o operador manual da versão desejada.

Solução de problemas

Na seção a seguir, você verá dicas de solução de problemas para a instalação do Config Connector.

Solução de problemas de permissões para reconciliações de recursos

Se o Config Connector não reconciliar recursos e os registros contiverem a mensagem de erro The caller does not have permission, forbidden., talvez a identidade da carga de trabalho não esteja ativada no cluster do GKE e/ou pool de nós.

Para investigar, siga estas etapas:

  1. Salve a seguinte configuração de pod como wi-test.yaml:
    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: cnrm-system
    spec:
      containers:
      - image: google/cloud-sdk:slim
        name: workload-identity-test
        command: ["sleep","infinity"]
      serviceAccountName: cnrm-controller-manager
    
  2. Crie o pod no cluster do GKE:
    kubectl apply -f wi-test.yaml
    
  3. Abra uma sessão interativa no pod:
    kubectl exec -it workload-identity-test \
      --namespace cnrm-system \
      -- /bin/bash
    
  4. Liste sua identidade:
    gcloud auth list
    
  5. Verifique se a identidade listada corresponde à conta de serviço do Google vinculada aos seus recursos.

    Se aparecer a conta de serviço padrão do Compute Engine, isso significa que a identidade da carga de trabalho não está ativada no cluster do GKE e/ou no pool de nós.

  6. Saia da sessão interativa e exclua o pod do cluster do GKE:
    kubectl delete pod workload-identity-test \
    --namespace cnrm-system
    

A seguir