Instale o Config Connector manualmente

Esta página explica como instalar manualmente o Config Connector. A instalação manual é uma opção flexível que lhe dá controlo sobre a versão instalada e o agendamento da atualização.

Para mais informações sobre as diferentes opções de instalação, consulte o artigo Escolher um tipo de instalação.

Para a maioria dos exemplos de utilização, recomendamos que instale manualmente o Config Connector no modo com espaço de nomes. A alternativa é o modo de cluster. O modo com espaço de nomes é mais escalável e oferece um melhor isolamento das autorizações, o que é ideal para exemplos de utilização multi-inquilinos ou quando gere recursos de vários projetos.

Se preferir uma única conta de serviço ao nível do cluster, siga as instruções de instalação no modo de cluster.

Antes de começar

Antes de instalar manualmente o operador do Config Connector, conclua os seguintes passos:

Instale o operador do Config Connector

O Config Connector usa um operador do Kubernetes para manter a respetiva instalação atualizada. A instalação do operador é necessária, quer instale o Config Connector no modo de espaço de nomes ou no modo de cluster.

Para instalar o operador do Config Connector, conclua os passos seguintes:

  1. Transfira o ficheiro .tar do operador do Config Connector mais recente:

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

  2. Extraia o ficheiro TAR:

    tar zxvf release-bundle.tar.gz

  3. Instale o operador do Config Connector no cluster:

    Piloto automático 

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

    Standard 

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

  4. Para configurar o operador do Config Connector para ser executado no modo de espaço de nomes, conclua os seguintes passos:

    1. Crie um manifesto com o nome configconnector.yaml com o seguinte conteúdo:

      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
  stateIntoSpec: Absent

    2. Aplique o manifesto ao cluster:

      kubectl apply -f configconnector.yaml

Instale o Config Connector no modo com espaço de nomes

Nas secções seguintes, o projeto onde instala o Config Connector é o projeto anfitrião. Os outros projetos nos quais pode ter o Config Connector a gerir recursos são projetos geridos. O projeto anfitrião e o projeto gerido podem ser o mesmo projeto se quiser que o Config Connector crie apenas recursos no mesmo projeto que o seu cluster.

Crie um espaço de nomes

Crie um novo espaço de nomes executando o seguinte comando:

kubectl create namespace NAMESPACE

Substitua NAMESPACE por um nome para o espaço de nomes.

Crie uma identidade

Crie uma conta de serviço de gestão de identidade e de acesso (IAM) e crie uma associação entre a conta de serviço de IAM e a conta de serviço do Kubernetes do Config Connector através dos seguintes passos:

  1. Crie uma conta de serviço do IAM. Se tiver uma conta de serviço existente, pode usá-la em vez de criar uma nova conta de serviço. 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 o seguinte:

    • NAMESPACE_GSA com o nome da conta de serviço Google (GSA) associada ao seu espaço de nomes.
    • HOST_PROJECT_ID com o ID do projeto anfitrião.

    Para saber mais sobre como criar contas de serviço, consulte o artigo Criar e gerir contas de serviço.

  2. Conceda autorizações elevadas à conta de serviço de IAM no seu projeto gerido:

    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 seu projeto gerido.

  3. Crie uma associação de políticas de IAM entre a conta de serviço de IAM e a conta de serviço do Kubernetes do Config Connector:

    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"

  4. Conceda autorizações à conta de serviço do IAM para publicar métricas do Prometheus no Google Cloud Observability no seu projeto de anfitrião:

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

Crie um ConfigConnectorContext

Para criar Google Cloud recursos, configure o Config Connector para monitorizar o seu espaço de nomes adicionando um objeto ConfigConnectorContext nesse espaço de nomes.

Para criar um ConfigConnectorContext, conclua os seguintes passos:

  1. Crie um manifesto com o nome configconnectorcontext.yaml com o seguinte conteúdo:

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

  2. Aplique o manifesto ao cluster:

    kubectl apply -f configconnectorcontext.yaml

  3. Verifique se o operador do Config Connector criou uma conta de serviço do Kubernetes para o seu espaço de nomes executando o seguinte comando:

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

  4. Verifique se o pod do controlador do Config Connector está em execução para o seu espaço de nomes:

    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

    Se o controlador do Config Connector estiver em execução, o resultado é semelhante ao seguinte:

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

Pare de gerir recursos num espaço de nomes

Se quiser que o Config Connector pare de gerir recursos num espaço de nomes, remova todos os recursos do Config Connector e o objeto ConfigConnectorContext nesse espaço de nomes.

  1. Para encontrar todos os recursos do Config Connector no seu espaço de nomes, para cada definição de recurso personalizado do Config Connector, liste todos os recursos.

    kubectl get gcp -n NAMESPACE

    O resultado deste comando apresenta todas as definições de recursos personalizados (CRDs) que representam um recurso gerido pelo Config Connector nesse espaço de nomes, incluindo o nome e o tipo do Kubernetes desse recurso.

  2. Para remover todos os recursos do Config Connector, para cada recurso no resultado do passo anterior, execute o seguinte comando:

    kubectl delete -n NAMESPACE KIND NAME

    Substitua o seguinte:

    • KIND: o tipo do Kubernetes do recurso.
    • NAME: o nome do recurso.

  3. Elimine o objeto ConfigConnectorContext no seu espaço de nomes.

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

Desinstale o Config Connector

Para desinstalar o Config Connector, conclua os seguintes passos:

  1. Para remover os CRDs e os componentes do controlador do Config Connector, execute o seguinte comando:

    kubectl delete ConfigConnectorContext --all -A –wait=false

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

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

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

Instale no modo de cluster

Pode preferir instalar e gerir o Config Connector no modo de cluster se quiser gerir recursos num único projeto e não precisar da separação de autorizações que o modo com espaços de nomes oferece.

Crie uma identidade

O Config Connector cria e gere Google Cloud recursos através da autenticação com uma conta de serviço de gestão de identidade e de acesso (IAM) e da utilização da Workload Identity Federation para o GKE para associar contas de serviço de IAM a contas de serviço do Kubernetes.

Para criar a identidade, conclua os seguintes passos:

  1. Crie uma conta de serviço do IAM. Se quiser usar uma conta de serviço existente, pode usar essa conta e ignorar este passo:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Substitua SERVICE_ACCOUNT_NAME por um nome para a sua conta de serviço.

    Para saber como criar contas de serviço, consulte o artigo Criar e gerir contas de serviço.

  2. Conceda autorizações elevadas à conta de serviço de IAM no seu projeto:

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/editor"

    Substitua PROJECT_ID pelo ID do seu projeto.

  3. Crie uma associação de política IAM entre a conta de serviço IAM e a conta de serviço Kubernetes predefinida 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"

Configure o Config Connector

Para concluir a instalação, crie um ficheiro de configuração para o ConfigConnector CustomResource e, em seguida, aplique-o com o comando kubectl apply. O operador do Config Connector instala CRDs de recursos e componentes do Config Connector no seu cluster.Google Cloud

Para configurar o operador como modo de cluster, conclua os seguintes passos:

  1. Copie o seguinte ficheiro YAML para um ficheiro com o nome 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
     Substitua o seguinte:
    • SERVICE_ACCOUNT_NAME com o nome da sua conta de serviço.
    • PROJECT_ID com o ID do seu projeto.
  2. Aplique a configuração ao cluster com kubectl apply: 
      kubectl apply -f configconnector.yaml

Especificar onde criar os recursos

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

Antes de criar recursos com o Config Connector, tem de configurar onde criar os seus recursos. Para determinar onde criar o recurso, o Config Connector usa uma anotação na configuração do recurso ou num espaço de nomes existente. Para mais informações, consulte o artigo Organizar recursos.

Se não tiver um espaço de nomes para este fim, crie um com kubectl. 
kubectl create namespace NAMESPACE

Substitua NAMESPACE pelo nome do seu espaço de nomes. Por exemplo config-connector.

Selecione um separador para escolher onde quer que o Config Connector crie recursos.

Projeto

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

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

Substitua o seguinte:

  • NAMESPACE com o nome do seu espaço de nomes.
  • PROJECT_ID com o ID do seu Google Cloud projeto.

Pasta

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

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

Substitua o seguinte:

  • NAMESPACE com o nome do seu espaço de nomes.
  • FOLDER_ID com o ID da sua Google Cloud pasta.

Organização

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

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

Substitua o seguinte:

  • NAMESPACE com o nome do seu espaço de nomes.
  • ORGANIZATION_ID com o ID da sua Google Cloud organização.

Quando anota o seu espaço de nomes, o Config Connector cria recursos no projeto, na pasta ou na organização correspondente. Para saber mais sobre como o Config Connector usa os espaços de nomes do Kubernetes, consulte os artigos Espaços de nomes do Kubernetes e Google Cloud projetos.

Valide a instalação

O Config Connector executa todos os respetivos componentes num espaço de nomes denominado cnrm-system. Pode verificar se os pods estão prontos executando o seguinte comando: 

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

Se o Config Connector estiver instalado corretamente, o resultado é semelhante ao seguinte: 

pod/cnrm-controller-manager-0 condition met

Desinstale o Config Connector

Para desinstalar o Config Connector, conclua os seguintes passos:

  1. Para remover os CRDs e os componentes do controlador do Config Connector, execute o seguinte comando:

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

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

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

Atualize o Config Connector

Para transferir e instalar a versão mais recente do operador do Config Connector, execute o seguinte comando:

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

Faça o downgrade do Config Connector

A alteração completa do Config Connector para uma versão anterior não é suportada. Para reverter o operador do Config Connector e os CRDs, tem de desinstalar e reinstalar o Config Connector e, em seguida, voltar a aplicar os seus recursos.

Na versão 1.123.1 e posteriores do Config Connector, pode reverter a versão do operador para instalações que usam o modo com espaço de nomes. Em cada espaço de nomes que tenha um operador para o qual quer reverter, defina o campo spec.version no objeto ConfigConnectorContext para a versão anterior do Config Connector.

Pode reverter o controlador do Config Connector para um máximo de 3 versões secundárias. Tem sempre de reverter para a versão de patch mais recente de uma determinada versão secundária.

Atualize a partir de instalações não pertencentes a operadores

A versão 1.33.0 e superior do Config Connector só suporta a instalação com o suplemento do GKE ou o operador.

Para atualizar para o operador (e reter todos os recursos do Config Connector), tem de remover todos os componentes do sistema do Config Connector, exceto os CRDs, e, em seguida, instalar o operador.

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

    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 com o suplemento do GKE ou o operador.

Mude do suplemento para uma instalação manual

Quando instalado como um suplemento, a versão do Config Connector está diretamente associada à versão do GKE instalada.

A instalação manual permite atualizações mais rápidas, mas requer atualizações manuais.

Para mudar os métodos de instalação e manter os seus recursos em segurança, conclua os seguintes passos:

  1. Desative o suplemento sem eliminar objetos ConfigConnector ou ConfigConnectorContext:

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

    Substitua CLUSTER_NAME pelo nome do cluster no qual instalou o Config Connector.

  2. Instale o operador manual da versão escolhida.

    Para evitar potenciais erros de validação de CRD (por exemplo, KNV2009: Invalid value: "v1beta1": must appear in spec.versions), a versão escolhida do operador manual tem de ser igual ou posterior à versão que estava a usar para o suplemento. A desatualização da versão do operador manual pode causar erros (por exemplo, KNV2009) porque o suplemento do GKE pode já ter atualizado determinados CRDs para uma versão posterior do Config Connector.

O que se segue?