Conceder acesso do Config Sync ao repositório Git

Nesta página, descrevemos como autenticar o Config Sync no seu repositório Git. O Config Sync exige acesso somente leitura à sua fonte da verdade para ler as configurações, aplicá-las aos clusters e mantê-las sincronizadas.

Escolher um método de autenticação

O método de autenticação usado depende do que é compatível com seu tipo de fonte.

A tabela a seguir resume os métodos de autenticação que podem ser usados com o Config Sync:

Método Fontes compatíveis Descrição Limitações
Sem autenticação Git, OCI, Helm Não é necessário fazer nenhuma configuração adicional. Só funciona se sua fonte de verdade for pública.
Par de chaves SSH Git Compatível com a maioria dos provedores do Git. Requer gerenciamento de chaves. Não é compatível com OCI ou Helm.
token Git, Helm Compatível com a maioria dos provedores do Git. Uma boa alternativa se sua organização não permitir o uso de chaves SSH. Compatível com nome de usuário e senha para Helm. Exige gerenciamento de tokens. Os tokens podem expirar. Não é compatível com a 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. Exige que a federação de identidade da carga de trabalho do GKE esteja ativada no cluster. Não é compatível com o Git.
Conta de serviço do Google Git Usa o IAM, o que evita o armazenamento de credenciais em secrets do Kubernetes. Recomendado para o Secure Source Manager e o Cloud Source Repositories. Exige que a federação de identidade da carga de trabalho do GKE esteja ativada no cluster. Requer configuração antes e depois da instalação do Config Sync nos clusters. Não é compatível com repositórios hospedados fora do Secure Source Manager ou do Cloud Source Repositories.
App GitHub Git Integração direta com o GitHub. Permite permissões detalhadas. Só é compatível com repositórios hospedados no GitHub. Compatível apenas com o Config Sync versão 1.19.1 e mais recentes.

O Config Sync também é compatível com os seguintes métodos de autenticação. No entanto, eles só são recomendados se você não puder usar uma das opções listadas na tabela anterior:

  • cookiefile pode não ser compatível com todos os provedores do Git. Não é compatível com OCI ou Helm.
  • Conta de serviço padrão do Compute Engine (gcenode): não é recomendada porque esse método só funciona se a federação de identidade da carga de trabalho para o GKE estiver desativada. Compatível com Git, OCI e Helm.
  • Conta de serviço do Google para Helm e OCI:compatível, mas não recomendado porque o método de conta de serviço do Kubernetes exige menos configuração.

Autenticação com pacotes da frota

Se você usa pacotes de frota, não precisa seguir as instruções nesta página. Os pacotes de frota usam o Cloud Build para autenticar no Git, o que permite autenticar uma vez por projeto para que não seja necessário conceder acesso sempre que você instala o Config Sync em um cluster.

Antes de começar

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

Usar um par de chaves SSH

Um par de chaves SSH consiste em dois arquivos, uma chave pública e uma chave privada. O Config Sync não é compatível com a criação de senhas longas. Dependendo dos seus requisitos de segurança e conformidade, é possível usar um único par de chaves para todos os clusters ou um par de chaves por cluster.

Para conceder acesso somente leitura do Config Sync ao repositório Git usando um par de chaves SSH, conclua as seguintes etapas:

  1. Crie ou peça ao administrador de segurança para fornecer um par de chaves SSH. Se você precisar criar um par de chaves SSH, execute o comando a seguir para criar uma chave RSA de 4096 bits:

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

    Substitua:

    • GIT_REPOSITORY_USERNAME: o nome de usuário que você quer que o Config Sync use para se autenticar no repositório. Se você usa um host de repositório Git de terceiros, como o GitHub, ou quer usar uma conta de serviço com o Secure Source Manager, recomendamos que você use uma conta separada para autenticação.
    • /path/to/KEYPAIR_FILENAME: o caminho para o arquivo do par de chaves.

  2. Configure o repositório para reconhecer a chave pública recém-criada. Consulte a documentação do seu provedor de hospedagem Git. Confira instruções para alguns provedores de hospedagem Git comuns na lista a seguir:

  3. Crie o Secret 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 hosts conhecidos ao usar a autenticação SSH, adicione a chave de hosts conhecidos ao campo data.known_hosts no secret git_creds.

    1. Para adicionar a chave de hosts conhecida, 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 hosts conhecidos.

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

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

Ao inserir o URL do repositório Git, ele precisa usar o formato do protocolo SSH. O formato do URL varia de acordo com o provedor do Git.

Usar um cookiefile

O processo para adquirir um cookiefile depende da configuração no repositório. Geralmente, as credenciais são armazenadas em um arquivo .gitcookies em um diretório principal ou são fornecidas por um administrador de segurança.

Para conceder acesso somente leitura do Config Sync ao seu repositório Git usando um cookiefile, siga estas etapas:

Depois de criar ou conseguir o cookiefile, adicione-o a um novo Secret no cluster. Recomendamos que você 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 arquivo.

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

Usar um token

Se sua organização não permitir o uso de chaves SSH, talvez você prefira usar um token.

Para conceder acesso somente leitura do Config Sync ao seu repositório Git usando um token, siga estas etapas:

  1. Gere um token do seu provedor Git. Consulte a documentação do seu provedor de hospedagem Git para ver as instruções. Confira instruções para alguns provedores de hospedagem Git comuns na lista a seguir:

  2. Depois de criar ou receber um token, adicione-o a um novo secret no cluster. Recomendamos que você 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:

    • USERNAME: o nome de usuário que você quer usar.
    • TOKEN: o token criado na etapa anterior.

Ao instalar o Config Sync, use o token (token) como o tipo de autenticação.

Usar uma conta de serviço do Google

É possível conceder ao Config Sync acesso a um repositório no mesmo projeto que o cluster gerenciado usando uma conta de serviço do Google. Você precisa atender aos seguintes requisitos:

Para conceder ao Config Sync acesso somente leitura ao seu repositório Git usando uma conta de serviço do Google, siga estas etapas:

  1. Para receber as permissões necessárias para criar uma vinculação de política, peça ao administrador para conceder a você o papel do IAM de Administrador da conta de serviço (roles/iam.serviceAccountAdmin) na conta de serviço. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

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

  3. Conceda o papel do IAM à conta de serviço do Google, dependendo do tipo de repositório que você está usando:

    Secure Source Manager

    Conceda os papéis do IAM Acessador da instância do Secure Source Manager (roles/securesourcemanager.instanceAccessor) e Leitor do repositório do Secure Source Manager (roles/securesourcemanager.repoReader) à conta de serviço do Google:

    • Conceda permissão a todo o projeto se as mesmas permissõ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:

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

    • Para conceder permissões específicas do repositório, consulte a documentação do Secure Source Manager sobre Conceder papéis no nível do repositório aos usuários.

    Ao instalar o Config Sync, use a Identidade da carga de trabalho (gcpserviceaccount) como o tipo de autenticação. Você também precisa adicionar o e-mail da sua conta de serviço.

    O Secure Source Manager exige 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 o papel do IAM de Leitor do Cloud Source Repositories (roles/source.reader) à conta de serviço do Google:

    • Conceda permissão a todo o projeto se as mesmas permissõ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:

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

    • Conceda permissã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 projeto:

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

      Substitua:

      • PROJECT_ID: o ID do projeto.
      • REPOSITORY: o nome do repositório.
      • POLICY_FILE: o arquivo JSON ou YAML que contém a política do Identity and Access Management.

    Ao instalar o Config Sync, use a Identidade da carga de trabalho (gcpserviceaccount) como o tipo de autenticação. Você também precisa adicionar o e-mail da sua conta de serviço.

A etapa a seguir precisa ser concluída depois de configurar o Config Sync porque a conta de serviço do Kubernetes não é criada até que você configure o Config Sync pela primeira vez. Você só precisa fazer isso uma vez por frota. Para criar a vinculação que permite que a conta de serviço do Kubernetes atue como a conta de serviço do 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:

  • FLEET_HOST_PROJECT_ID: se você usa a Federação de Identidade da Carga de Trabalho para GKE, o valor é o mesmo que PROJECT_ID. Se você usa a Federação de Identidade da Carga de Trabalho para GKE da frota, use o ID do projeto da frota em que o cluster está registrado como o valor.
  • GSA_NAME: a conta de serviço personalizada do Google que você quer usar para se conectar ao Secure Source Manager ou ao Cloud Source Repositories.
  • KSA_NAME: a conta de serviço do Kubernetes do reconciliador. Na maioria dos casos, o valor é root-sync porque o Config Sync cria automaticamente um objeto RootSync chamado root-sync quando instalado com o console Google Cloud ou a Google Cloud CLI. Caso contrário, use root-reconciler-ROOT_SYNC_NAME como o valor.

Se você tiver problemas para se conectar ao Config Sync com uma conta de serviço do Google, consulte Resolver problemas de permissão com uma conta de serviço do Google.

Usar uma conta de serviço padrão do Compute Engine

Como alternativa a uma conta de serviço do Google, se a federação de identidade da carga de trabalho para GKE não estiver ativada, use uma conta de serviço do Compute Engine para autenticar. Esse método é compatível apenas com repositórios no Secure Source Manager e no Cloud Source Repositories.

Para conceder ao Config Sync acesso somente leitura ao seu repositório usando uma conta de serviço padrão do Compute Engine, conceda à conta de serviço padrão o papel roles/source.reader:

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

Substitua:

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

Ao instalar o Config Sync, use o Google Cloud Repository (gcenode) como o tipo de autenticação.

Usar um app GitHub

Se o repositório estiver no GitHub, use o app GitHub para conectá-lo ao Config Sync:

  1. Siga as instruções no GitHub para provisionar um app do GitHub e conceder a ele permissão para ler seu repositório.

  2. Adicione a configuração do GitHub App a um novo Secret no cluster usando o ID do cliente ou do aplicativo:

    ID do 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 do cliente do app GitHub.
    • Substitua INSTALLATION_ID pelo ID de instalação do app GitHub.
    • Substitua /path/to/GITHUB_PRIVATE_KEY pelo nome do arquivo que contém a chave privada.
    • Substitua BASE_URL pelo URL base do endpoint de API do GitHub. Esse valor só é necessário quando o repositório não está hospedado em www.github.com. Caso contrário, o argumento pode ser omitido e o padrão é https://api.github.com/.

    ID do aplicativo 

    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 do aplicativo do GitHub.
    • Substitua INSTALLATION_ID pelo ID de instalação do app GitHub.
    • Substitua /path/to/GITHUB_PRIVATE_KEY pelo nome do arquivo que contém a chave privada.
    • Substitua BASE_URL pelo URL base do endpoint de API do GitHub. Esse valor só é necessário se o repositório não estiver hospedado em www.github.com. Caso contrário, o argumento pode ser omitido e o padrão será https://api.github.com/.

Ao instalar o Config Sync, use o app GitHub (githubapp) como o tipo de autenticação.

Solução de problemas

Para resolver problemas relacionados à conexão do Config Sync com sua fonte de verdade, consulte os seguintes tópicos de solução de problemas:

A seguir