Conceda acesso do Config Sync ao seu repositório Git

Esta página descreve como autenticar o Config Sync no seu repositório Git. O Config Sync requer acesso só de leitura à sua fonte de verdade para poder ler as suas configurações, aplicá-las aos seus clusters e mantê-las sincronizadas.

Escolha um método de autenticação

O método de autenticação que usa depende do que é suportado para o seu tipo de origem.

A tabela seguinte resume os métodos de autenticação que pode usar com a sincronização de configuração:

Método Fontes suportadas Descrição Limitações
Sem autenticação Git, OCI e Helm Não é necessária nenhuma configuração adicional. Só funciona se a sua fonte de informação fidedigna for pública.
Par de chaves SSH Git Suportado pela maioria dos fornecedores de Git. Requer gestão de chaves. Não suportado para OCI nem Helm.
token Git, Helm Suportado pela maioria dos fornecedores de Git. Boa alternativa se a sua organização não permitir a utilização de chaves SSH. Suporta nome de utilizador e palavra-passe para o Helm. Requer gestão de tokens. Os tokens podem expirar. Não suportado para OCI.
Conta de serviço do Kubernetes OCI, Helm Usa o IAM para conceder acesso ao Artifact Registry diretamente a uma conta de serviço do Kubernetes. Requer que a Workload Identity Federation para o GKE esteja ativada no seu cluster. Não suportado para o Git.
Conta de serviço Google Git Usa o IAM, o que evita o armazenamento de credenciais em segredos do Kubernetes. Recomendado para o Secure Source Manager e os Cloud Source Repositories. Requer que a Workload Identity Federation para o GKE esteja ativada no seu cluster. Requer configuração antes e depois de instalar o Config Sync nos seus clusters. Não suportado para repositórios alojados fora do Secure Source Manager ou dos Cloud Source Repositories.
App GitHub Git Integração direta com o GitHub. Permite autorizações detalhadas. Apenas suportado para repositórios alojados no GitHub. Apenas suportado na versão 1.19.1 e posteriores do Config Sync.

A sincronização de configuração também suporta os seguintes métodos de autenticação. No entanto, estes métodos só são recomendados se não conseguir usar uma das opções indicadas na tabela anterior:

  • cookiefile: pode não ser suportado para todos os fornecedores do Git. Não suportado para OCI nem Helm.
  • Conta de serviço predefinida do Compute Engine (gcenode): não recomendado porque este método só funciona se a federação de identidades da carga de trabalho para o GKE estiver desativada. Suportado para Git, OCI e Helm.
  • Conta de serviço Google para Helm e OCI: suportada, mas não recomendada porque o método de conta de serviço do Kubernetes requer menos configuração.

Autenticação com pacotes de frotas

Se usar pacotes de frotas, não precisa de concluir as instruções nesta página. Os pacotes do Fleet usam o Cloud Build para autenticar no Git, o que permite autenticar uma vez por projeto para não ter de conceder acesso sempre que instala o Config Sync num cluster.

Antes de começar

Antes de conceder acesso só de leitura ao Config Sync ao seu repositório Git, conclua as seguintes tarefas:

Use um par de chaves SSH

Um par de chaves SSH consiste em dois ficheiros: uma chave pública e uma chave privada. O Config Sync não suporta a criação de frases secretas. Consoante os seus requisitos de segurança e conformidade, pode usar um único par de chaves para todos os clusters ou um par de chaves por cluster.

Para conceder acesso só de leitura ao Config Sync ao seu repositório Git através de um par de chaves SSH, conclua os seguintes passos:

  1. Crie ou peça ao seu administrador de segurança que lhe faculte um par de chaves SSH. Se precisar de criar um par de chaves SSH, crie uma chave RSA de 4096 bits executando o seguinte comando:

    ssh-keygen -t rsa -b 4096 \
  -C "GIT_REPOSITORY_USERNAME" \
  -N '' \
  -f /path/to/KEYPAIR_FILENAME

    Substitua o seguinte:

    • GIT_REPOSITORY_USERNAME: o nome de utilizador que quer que o Config Sync use para autenticar no repositório. Se usar um anfitrião de repositório Git de terceiros, como o GitHub, ou quiser usar uma conta de serviço com o Secure Source Manager, recomendamos que use uma conta separada para autenticação.
    • /path/to/KEYPAIR_FILENAME: o caminho para o ficheiro do par de chaves.

  2. Configure o seu repositório para reconhecer a chave pública recém-criada. Consulte a documentação do seu fornecedor de alojamento Git. Pode encontrar instruções para alguns fornecedores de alojamento Git comuns na seguinte lista:

  3. Crie o segredo git-creds com a chave privada:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    Substitua /path/to/KEYPAIR_PRIVATE_KEY_FILENAME pelo nome da chave privada.

  4. Opcional, mas recomendado: para configurar a verificação de anfitriões conhecidos quando usar a autenticação SSH, adicione a chave de anfitriões conhecidos ao campo data.known_hosts no segredo git_creds.

    1. Para adicionar a chave de anfitriões conhecidos, execute o seguinte comando:

      kubectl edit secret git-creds --namespace=config-management-system

    2. Para adicionar a entrada known_hosts em data, execute o seguinte comando:

        known_hosts: KNOWN_HOSTS_KEY

      Substitua KNOWN_HOSTS_KEY pela chave de anfitriões conhecidos.

    Para desativar a verificação known_hosts, remova o campo known_hosts do segredo.

Quando instala o Config Sync, use o par de chaves SSH (ssh) como o tipo de autenticação.

Quando introduz o URL do seu repositório Git, o URL tem de usar o formato do protocolo SSH. O formato do URL difere consoante o fornecedor do Git.

Use um ficheiro de cookies

O processo de aquisição de um cookiefile depende da configuração do seu repositório. Geralmente, as credenciais são armazenadas num ficheiro .gitcookies num diretório principal ou são fornecidas por um administrador de segurança.

Para conceder acesso só de leitura ao Config Sync ao seu repositório Git através de um cookiefile, conclua os passos seguintes:

Depois de criar ou obter o cookiefile, adicione-o a um novo Secret no cluster. Recomendamos que use HTTPS por motivos de segurança:

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

Substitua /path/to/COOKIEFILE pelo caminho e nome do ficheiro.

Quando instalar o Config Sync, use cookiefile (cookiefile) como o tipo de autenticação.

Use um token

Se a sua organização não permitir a utilização de chaves SSH, pode preferir utilizar um token.

Para conceder acesso só de leitura do Config Sync ao seu repositório Git através de um token, conclua os seguintes passos:

  1. Gere um token a partir do seu fornecedor Git. Consulte a documentação do seu fornecedor de alojamento Git para ver instruções. Pode encontrar instruções para alguns fornecedores de alojamento Git comuns na seguinte lista:

  2. Depois de criar ou obter um token, adicione-o a um novo segredo no cluster. Recomendamos que use HTTPS por motivos de segurança:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    Substitua o seguinte:

    • USERNAME: o nome de utilizador que quer usar.
    • TOKEN: o token que criou no passo anterior.

Quando instala a sincronização de configuração, use o token (token) como o tipo de autenticação.

Use uma conta de serviço Google

Pode conceder acesso do Config Sync a um repositório no mesmo projeto que o cluster gerido através de uma conta de serviço Google. Tem de cumprir os seguintes requisitos:

Para conceder acesso só de leitura ao Config Sync ao seu repositório Git através de uma conta de serviço Google, conclua os seguintes passos:

  1. Para obter as autorizações de que precisa para criar uma associação de políticas, peça ao seu administrador para lhe conceder a função IAM de administrador da conta de serviço (roles/iam.serviceAccountAdmin) na conta de serviço. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

  2. Se ainda não tiver uma conta de serviço, crie uma conta de serviço.

  3. Conceda a função do IAM à conta de serviço Google, consoante o tipo de repositório que está a usar:

    Secure Source Manager

    Conceda as funções do IAM Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) e Secure Source Manager Repo Reader (roles/securesourcemanager.repoReader) à conta de serviço Google:

    • Conceda autorização ao nível do projeto se as mesmas autorizações se aplicarem a todos os repositórios no projeto:

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

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

      Substitua o seguinte:

      • PROJECT_ID: o ID do seu projeto.
      • GSA_NAME: o nome da conta de serviço Google que quer associar ao Secure Source Manager.

    • Para conceder autorização específica do repositório, consulte a documentação do Secure Source Manager para conceder funções ao nível do repositório aos utilizadores.

    Quando instalar o Config Sync, use o Workload Identity (gcpserviceaccount) como o tipo de autenticação. Também tem de adicionar o email da sua conta de serviço.

    O Secure Source Manager requer um formato específico para o URL do repositório: https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

    Cloud Source Repositories

    Conceda a função do IAM de leitor do Cloud Source Repositories à conta de serviço da Google:roles/source.reader

    • Conceda autorização ao nível do projeto se as mesmas autorizações se aplicarem a todos os repositórios no projeto:

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

      Substitua o seguinte:

      • PROJECT_ID: o ID do seu projeto.
      • GSA_NAME: o nome da conta de serviço Google que quer associar ao Cloud Source Repositories.

    • Conceda autorização específica do repositório quando quiser que as contas de serviço tenham diferentes níveis de acesso para cada repositório no seu projeto:

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

      Substitua o seguinte:

      • PROJECT_ID: o ID do seu projeto.
      • REPOSITORY: o nome do repositório.
      • POLICY_FILE: o ficheiro JSON ou YAML que contém a política de gestão de identidade e de acesso.

    Quando instalar o Config Sync, use o Workload Identity (gcpserviceaccount) como o tipo de autenticação. Também tem de adicionar o email da sua conta de serviço.

Tem de concluir o passo seguinte depois de configurar o Config Sync, porque a conta de serviço do Kubernetes só é criada quando configura o Config Sync pela primeira vez. Só tem de fazer isto uma vez por frota. Para criar a associação que permite à conta de serviço do Kubernetes atuar como a conta de serviço Google, execute o seguinte comando:

gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Substitua o seguinte:

  • FLEET_HOST_PROJECT_ID: se usar a Workload Identity Federation para o GKE, o valor é o mesmo que PROJECT_ID. Se usar a Workload Identity Federation da frota para o GKE, use o ID do projeto da frota no qual o cluster está registado como valor.
  • GSA_NAME: a conta de serviço Google personalizada que quer usar para se ligar ao Secure Source Manager ou aos Cloud Source Repositories.
  • KSA_NAME: a conta de serviço do Kubernetes para o reconciliador. Na maioria dos casos, o valor é root-sync porque o Config Sync cria automaticamente um objeto RootSync denominado root-sync quando instalado com a consola ou a CLI Google Cloud. Google Cloud Caso contrário, use root-reconciler-ROOT_SYNC_NAME como valor.

Se tiver problemas ao estabelecer ligação à sincronização de configuração com uma conta de serviço Google, consulte o artigo Resolva problemas de autorização com uma conta de serviço Google.

Use uma conta de serviço predefinida do Compute Engine

Como alternativa a uma conta de serviço Google, se não tiver a Workload Identity Federation para o GKE ativada, pode usar uma conta de serviço do Compute Engine para autenticar. Este método só é suportado para repositórios no Secure Source Manager e nos Cloud Source Repositories.

Para conceder acesso só de leitura ao Config Sync ao seu repositório através de uma conta de serviço predefinida do Compute Engine, conceda à conta de serviço predefinida a função roles/source.reader:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Substitua o seguinte:

  • PROJECT_ID: o ID do seu projeto
  • PROJECT_NUMBER: com o número do seu projeto.

Quando instalar o Config Sync, use o repositório do Google Cloud (gcenode) como o tipo de autenticação.

Use uma app GitHub

Se o seu repositório estiver no GitHub, pode usar a app GitHub para associar o seu repositório ao Config Sync:

  1. Siga as instruções no GitHub para aprovisionar uma app GitHub e conceder-lhe autorização para ler a partir do seu repositório.

  2. Adicione a configuração da app GitHub a um novo segredo no cluster através do ID do cliente ou da aplicação:

    ID de cliente 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=github-app-client-id=CLIENT_ID \
  --from-literal=github-app-installation-id=INSTALLATION_ID \
  --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
  --from-literal=github-app-base-url=BASE_URL
    • Substitua CLIENT_ID pelo ID de cliente da app GitHub.
    • Substitua INSTALLATION_ID pelo ID de instalação da app GitHub.
    • Substitua /path/to/GITHUB_PRIVATE_KEY pelo nome do ficheiro que contém a chave privada.
    • Substitua BASE_URL pelo URL base do ponto final da API GitHub. Este valor só é necessário quando o repositório não está alojado em www.github.com. Caso contrário, o argumento pode ser omitido e o valor predefinido é https://api.github.com/.

    ID da aplicação 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-literal=github-app-application-id=APPLICATION_ID \
    --from-literal=github-app-installation-id=INSTALLATION_ID \
    --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
    --from-literal=github-app-base-url=BASE_URL
    • Substitua APPLICATION_ID pelo ID da aplicação para a app GitHub.
    • Substitua INSTALLATION_ID pelo ID de instalação da app GitHub.
    • Substitua /path/to/GITHUB_PRIVATE_KEY pelo nome do ficheiro que contém a chave privada.
    • Substitua BASE_URL pelo URL base do ponto final da API GitHub. Este valor só é necessário se o repositório não estiver alojado em www.github.com. Caso contrário, o argumento pode ser omitido e tem como predefinição https://api.github.com/.

Quando instala o Config Sync, use a app GitHub (githubapp) como o tipo de autenticação.

Resolução de problemas

Para obter ajuda na resolução de problemas relacionados com a ligação do Config Sync à sua fonte de dados fidedigna, reveja os seguintes tópicos de resolução de problemas:

O que se segue?