Tutorial: Implementar configurações com o GitOps num cluster do Kubernetes compatível com o Azure Arc

Artigo
05/08/2023

Importante

Este tutorial destina-se ao GitOps com o Flux v1. O GitOps com o Flux v2 está agora disponível para clusters do Kubernetes e Azure Kubernetes Service (AKS) compatíveis com o Azure Arc; aceda ao tutorial do GitOps com o Flux v2. Recomendamos que migre para o Flux v2 o mais rapidamente possível.

O suporte para recursos de configuração de clusters baseados no Flux v1 criados antes de 1 de janeiro de 2024 terminará a 24 de maio de 2025. A partir de 1 de janeiro de 2024, não poderá criar novos recursos de configuração do cluster baseado no Flux v1.

Neste tutorial, irá aplicar configurações com o GitOps num cluster do Kubernetes compatível com o Azure Arc. Vai aprender a:

Crie uma configuração num cluster do Kubernetes compatível com o Azure Arc com um repositório Git de exemplo.
Confirme que a configuração foi criada com êxito.
Aplicar a configuração a partir de um repositório Git privado.
Valide a configuração do Kubernetes.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Um cluster ligado do Kubernetes compatível com o Azure Arc existente.
- Se ainda não ligou um cluster, veja o guia de início rápido Ligar um cluster do Kubernetes compatível com o Azure Arc.
Uma compreensão dos benefícios e da arquitetura desta funcionalidade. Leia mais no artigo Configurações e GitOps – Kubernetes compatível com o Azure Arc.
Instale a k8s-configuration extensão da CLI do Azure da versão >= 1.0.0:
```
az extension add --name k8s-configuration
```
Dica

Se a k8s-configuration extensão já estiver instalada, pode atualizá-la para a versão mais recente com o seguinte comando – az extension update --name k8s-configuration

Criar uma configuração

O repositório de exemplo utilizado neste artigo está estruturado em torno da persona de um operador de cluster. Os manifestos neste repositório aprovisionam alguns espaços de nomes, implementam cargas de trabalho e fornecem alguma configuração específica da equipa. A utilização deste repositório com o GitOps cria os seguintes recursos no cluster:

Espaços de nomes: cluster-config, , team-ateam-b
Implementação: arc-k8s-demo
ConfigMap: team-a/endpoints

O config-agent Azure consulta as configurações novas ou atualizadas. Esta tarefa demorará até 5 minutos.

Se estiver a associar um repositório privado à configuração, conclua os passos abaixo em Aplicar configuração a partir de um repositório Git privado.

Utilizar a CLI do Azure

Utilize a extensão da CLI do Azure para k8s-configuration ligar um cluster ligado ao repositório Git de exemplo.

Atribua o nome a esta configuração cluster-config.
Instrua o agente para implementar o operador no cluster-config espaço de nomes.

Dê permissões ao operador cluster-admin .

az k8s-configuration create --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --operator-instance-name cluster-config --operator-namespace cluster-config --repository-url https://github.com/Azure/arc-k8s-demo --scope cluster --cluster-type connectedClusters

{
  "complianceStatus": {
  "complianceState": "Pending",
  "lastConfigApplied": "0001-01-01T00:00:00",
  "message": "{\"OperatorMessage\":null,\"ClusterState\":null}",
  "messageLevel": "3"
  },
  "configurationProtectedSettings": {},
  "enableHelmOperator": false,
  "helmOperatorProperties": null,
  "id": "/subscriptions/<sub id>/resourceGroups/<group name>/providers/Microsoft.Kubernetes/connectedClusters/<cluster name>/providers/Microsoft.KubernetesConfiguration/sourceControlConfigurations/cluster-config",
  "name": "cluster-config",
  "operatorInstanceName": "cluster-config",
  "operatorNamespace": "cluster-config",
  "operatorParams": "--git-readonly",
  "operatorScope": "cluster",
  "operatorType": "Flux",
  "provisioningState": "Succeeded",
  "repositoryPublicKey": "",
  "repositoryUrl": "https://github.com/Azure/arc-k8s-demo",
  "resourceGroup": "MyRG",
  "sshKnownHostsContents": "",
  "systemData": {
    "createdAt": "2020-11-24T21:22:01.542801+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2020-11-24T21:22:01.542801+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
  },
  "type": "Microsoft.KubernetesConfiguration/sourceControlConfigurations"
}

Utilizar um repositório git público

Parâmetro	Formato
`--repository-url`	http[s]://servidor/repositório[.git]

Utilizar um repositório Git privado com SSH e chaves criadas com o Flux

Adicione a chave pública gerada pelo Flux à conta de utilizador no seu fornecedor do serviço Git. Se a chave for adicionada ao repositório em vez da conta de utilizador, utilize git@ em vez de user@ no URL.

Aceda à secção Aplicar configuração a partir de um repositório Git privado para obter mais detalhes.

Parâmetro	Formato	Notas
`--repository-url`	ssh://user@server/repo[.git] ou user@server:repo[.git]	`git@` pode substituir `user@`

Utilizar um repositório Git privado com SSH e chaves fornecidas pelo utilizador

Forneça a sua própria chave privada diretamente ou num ficheiro. A chave tem de estar no formato PEM e terminar com newline (\n).

Adicione a chave pública associada à conta de utilizador no fornecedor do serviço Git. Se a chave for adicionada ao repositório em vez da conta de utilizador, utilize git@ em vez de user@.

Aceda à secção Aplicar configuração a partir de um repositório Git privado para obter mais detalhes.

Parâmetro	Formato	Notas
`--repository-url`	ssh://user@server/repo[.git] ou user@server:repo[.git]	`git@` pode substituir `user@`
`--ssh-private-key`	Chave codificada com base64 no formato PEM	Fornecer a chave diretamente
`--ssh-private-key-file`	caminho completo para o ficheiro local	Indique o caminho completo para o ficheiro local que contém a chave de formato PEM

Utilizar um anfitrião Git privado com SSH e anfitriões conhecidos fornecidos pelo utilizador

O operador Flux mantém uma lista dos anfitriões Git comuns no respetivo ficheiro de anfitriões conhecidos para autenticar o repositório Git antes de estabelecer a ligação SSH. Se estiver a utilizar um repositório Git incomum ou o seu próprio anfitrião Git, pode fornecer a chave de anfitrião para que o Flux possa identificar o seu repositório.

Tal como as chaves privadas, pode fornecer o conteúdo known_hosts diretamente ou num ficheiro. Ao fornecer o seu próprio conteúdo, utilize a known_hosts especificações de formato de conteúdo, juntamente com qualquer um dos cenários de chave SSH acima.

Parâmetro	Formato	Notas
`--repository-url`	ssh://user@server/repo[.git] ou user@server:repo[.git]	`git@` pode substituir `user@`
`--ssh-known-hosts`	codificado em base64	Fornecer conteúdo de anfitriões conhecidos diretamente
`--ssh-known-hosts-file`	caminho completo para o ficheiro local	Fornecer conteúdo de anfitriões conhecidos num ficheiro local

Utilizar um repositório Git privado com HTTPS

Parâmetro	Formato	Notas
`--repository-url`	https://server/repo[.git]	HTTPS com autenticação básica
`--https-user`	codificado em raw ou base64	Nome de utilizador HTTPS
`--https-key`	codificado em raw ou base64	Token ou palavra-passe de acesso pessoal HTTPS

Nota

O gráfico de operador helm versão 1.2.0+ suporta a autenticação privada de versão do Helm de HTTPS.
A versão do Helm https não é suportada para clusters geridos pelo AKS.
Se precisar do Flux para aceder ao repositório Git através do seu proxy, terá de atualizar os agentes do Azure Arc com as definições de proxy. Para obter mais informações, veja Ligar através de um servidor proxy de saída.

Parâmetros Adicionais

Personalize a configuração com os seguintes parâmetros opcionais:

Parâmetro	Description
`--enable-helm-operator`	Mude para ativar o suporte para implementações de gráficos Helm.
`--helm-operator-params`	Valores de gráfico para o operador Helm (se ativado). Por exemplo, `--set helm.versions=v3`.
`--helm-operator-chart-version`	Versão do gráfico para o operador Helm (se ativado). Utilize a versão 1.2.0+. Predefinição: "1.2.0".
`--operator-namespace`	Nome do espaço de nomes do operador. Predefinição: "predefinição". Máx. : 23 carateres.
`--operator-params`	Parâmetros para operador. Tem de ser dada dentro de plicas. Por exemplo, `--operator-params='--git-readonly --sync-garbage-collection --git-branch=main'`

Opções suportadas em `--operator-params`:

Opção	Descrição
`--git-branch`	Ramo do repositório Git a utilizar para manifestos do Kubernetes. A predefinição é "master". Os repositórios mais recentes têm um ramo de raiz com o nome `main`, caso em que tem de definir `--git-branch=main`.
`--git-path`	Caminho relativo no repositório Git do Flux para localizar manifestos do Kubernetes.
`--git-readonly`	O repositório Git será considerado só de leitura. O Flux não vai tentar escrever-lhe.
`--manifest-generation`	Se estiver ativado, o Flux procurará .flux.yaml e executará o Kustomize ou outros geradores de manifestos.
`--git-poll-interval`	Período no qual pretende consultar o repositório Git para obter novas consolidações. A predefinição é `5m` (5 minutos).
`--sync-garbage-collection`	Se estiver ativado, o Flux eliminará os recursos que criou, mas deixará de estar presente no Git.
`--git-label`	Etiqueta para controlar o progresso da sincronização. Utilizado para etiquetar o ramo Git. A predefinição é `flux-sync`.
`--git-user`	Nome de utilizador da consolidação do Git.
`--git-email`	Email a utilizar para a consolidação do Git.

Se não quiser que o Flux escreva no repositório e --git-user não --git-email estiver definido, --git-readonly será definido automaticamente.

Para obter mais informações, veja a documentação do Flux.

Nota

A predefinição do Flux é sincronizada a master partir do ramo do repositório git. No entanto, os repositórios git mais recentes têm o ramo de raiz denominado main, caso em que tem de definir --git-branch=main em --operator-params.

Dica

Pode criar uma configuração no portal do Azure no separador GitOps do recurso kubernetes compatível com o Azure Arc.

Validar a configuração

Utilize a CLI do Azure para validar que a configuração foi criada com êxito.

az k8s-configuration show --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --cluster-type connectedClusters

O recurso de configuração será atualizado com informações de estado de compatibilidade, mensagens e depuração.

{
  "complianceStatus": {
    "complianceState": "Installed",
    "lastConfigApplied": "2020-12-10T18:26:52.801000+00:00",
    "message": "...",
    "messageLevel": "Information"
  },
  "configurationProtectedSettings": {},
  "enableHelmOperator": false,
  "helmOperatorProperties": {
    "chartValues": "",
    "chartVersion": ""
  },
  "id": "/subscriptions/<sub id>/resourceGroups/AzureArcTest/providers/Microsoft.Kubernetes/connectedClusters/AzureArcTest1/providers/Microsoft.KubernetesConfiguration/sourceControlConfigurations/cluster-config",
  "name": "cluster-config",
  "operatorInstanceName": "cluster-config",
  "operatorNamespace": "cluster-config",
  "operatorParams": "--git-readonly",
  "operatorScope": "cluster",
  "operatorType": "Flux",
  "provisioningState": "Succeeded",
  "repositoryPublicKey": "...",
  "repositoryUrl": "git://github.com/Azure/arc-k8s-demo.git",
  "resourceGroup": "AzureArcTest",
  "sshKnownHostsContents": null,
  "systemData": {
    "createdAt": "2020-12-01T03:58:56.175674+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2020-12-10T18:30:56.881219+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
},
  "type": "Microsoft.KubernetesConfiguration/sourceControlConfigurations"
}

Quando uma configuração é criada ou atualizada, ocorrem algumas coisas:

O Azure Arc config-agent monitoriza o Azure Resource Manager para configurações novas ou atualizadas (Microsoft.KubernetesConfiguration/sourceControlConfigurations) e repara na nova Pending configuração.
O config-agent lê as propriedades de configuração e cria o espaço de nomes de destino.
O Azure Arc controller-manager cria uma conta de serviço do Kubernetes e mapeia-a para ClusterRoleBinding ou RoleBinding para obter as permissões adequadas (cluster ou namespace âmbito). Em seguida, implementa uma instância de flux.
Se utilizar a opção SSH com chaves geradas pelo Flux, flux gera uma chave SSH e regista a chave pública.
O config-agent relatório devolve o estado ao recurso de configuração no Azure.

Enquanto o processo de aprovisionamento acontece, o recurso de configuração irá passar por algumas alterações de estado. Monitorize o progresso com o az k8s-configuration show ... comando acima:

Alteração de fase	Description
`complianceStatus`->`Pending`	Representa os estados iniciais e em curso.
`complianceStatus` ->`Installed`	`config-agent` o cluster foi configurado com êxito e implementado `flux` sem erros.
`complianceStatus` ->`Failed`	`config-agent` Ocorreu um erro ao `flux`implementar . Os detalhes são fornecidos no `complianceStatus.message` corpo da resposta.

Aplicar a configuração de um repositório Git privado

Se estiver a utilizar um repositório Git privado, terá de configurar a chave pública SSH no seu repositório. Fornece ou o Flux gera a chave pública SSH. Pode configurar a chave pública no repositório Git específico ou no utilizador do Git que tem acesso ao repositório.

Obter a sua chave pública

Se gerou as suas próprias chaves SSH, então já tem as chaves privadas e públicas.

Obter a chave pública com a CLI do Azure

Se as chaves forem geradas no Flux, utilize o seguinte na CLI do Azure.

az k8s-configuration show --resource-group <resource group name> --cluster-name <connected cluster name> --name <configuration name> --cluster-type connectedClusters --query 'repositoryPublicKey' 
"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAREDACTED"

Obter a chave pública no portal do Azure

Percorra o seguinte no portal do Azure se o Flux está a gerar as chaves.

No portal do Azure, navegue para o recurso do cluster ligado.
Na página de recursos, selecione "GitOps" e veja a lista de configurações para este cluster.
Selecione a configuração que utiliza o repositório Git privado.
Na janela de contexto que é aberta, na parte inferior da janela, copie a chave pública do Repositório.

Adicionar chave pública com o GitHub

Utilize uma das seguintes opções:

Opção 1: adicione a chave pública à conta de utilizador (aplica-se a todos os repositórios na conta):
1. Abra o GitHub e clique no ícone de perfil no canto superior direito da página.
2. Clique em Definições.
3. Clique em Chaves SSH e GPG.
4. Clique em Nova chave SSH.
5. Forneça um Título.
6. Cole a chave pública sem aspas.
7. Clique em Adicionar chave SSH.
Opção 2: adicione a chave pública como uma chave de implementação ao repositório Git (aplica-se apenas a este repositório):
1. Abra o GitHub e navegue para o seu repositório.
2. Clique em Definições.
3. Clique em Implementar chaves.
4. Clique em Adicionar chave de implementação.
5. Forneça um Título.
6. Selecione Permitir o acesso de escrito.
7. Cole a chave pública sem aspas.
8. Clique em Adicionar tecla.

Utilize um repositório do Azure DevOps para adicionar a chave pública

Utilize os seguintes passos para adicionar a chave às chaves SSH:

Em Definições do Utilizador no canto superior direito (junto à imagem do perfil), clique em Chaves públicas SSH.
Selecione + Nova Chave.
Indique um nome.
Cole a chave pública sem aspas.
Clique em Adicionar.

Validar a configuração do Kubernetes

Depois de config-agent instalar a instância, os flux recursos mantidos no repositório Git devem começar a fluir para o cluster. Verifique se os espaços de nomes, implementações e recursos foram criados com o seguinte comando:

kubectl get ns --show-labels

NAME              STATUS   AGE    LABELS
azure-arc         Active   24h    <none>
cluster-config    Active   177m   <none>
default           Active   29h    <none>
itops             Active   177m   fluxcd.io/sync-gc-mark=sha256.9oYk8yEsRwWkR09n8eJCRNafckASgghAsUWgXWEQ9es,name=itops
kube-node-lease   Active   29h    <none>
kube-public       Active   29h    <none>
kube-system       Active   29h    <none>
team-a            Active   177m   fluxcd.io/sync-gc-mark=sha256.CS5boSi8kg_vyxfAeu7Das5harSy1i0gc2fodD7YDqA,name=team-a
team-b            Active   177m   fluxcd.io/sync-gc-mark=sha256.vF36thDIFnDDI2VEttBp5jgdxvEuaLmm7yT_cuA2UEw,name=team-b

Podemos ver que team-aos espaços de nomes , team-b, itopse cluster-config foram criados.

O flux operador foi implementado no cluster-config espaço de nomes, conforme indicado pelo recurso de configuração:

kubectl -n cluster-config get deploy  -o wide

NAME             READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES                         SELECTOR
cluster-config   1/1     1            1           3h    flux         docker.io/fluxcd/flux:1.16.0   instanceName=cluster-config,name=flux
memcached        1/1     1            1           3h    memcached    memcached:1.5.15               name=memcached

Mais exploração

Pode explorar os outros recursos implementados como parte do repositório de configuração com:

kubectl -n team-a get cm -o yaml
kubectl -n itops get all

Limpar os recursos

Elimine uma configuração com a CLI do Azure ou portal do Azure. Depois de executar o comando delete, o recurso de configuração será eliminado imediatamente no Azure. A eliminação total dos objetos associados do cluster deve ocorrer dentro de 10 minutos. Se a configuração estiver num estado de falha quando removida, a eliminação completa dos objetos associados pode demorar até uma hora.

Quando uma configuração com namespace âmbito é eliminada, o espaço de nomes não é eliminado pelo Azure Arc para evitar quebrar cargas de trabalho existentes. Se necessário, pode eliminar este espaço de nomes manualmente com kubectl.

az k8s-configuration delete --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --cluster-type connectedClusters

Nota

Quaisquer alterações ao cluster resultantes de implementações do repositório Git controlado não são eliminadas quando a configuração é eliminada.

Passos seguintes

Avance para o próximo tutorial para saber como implementar CI/CD com o GitOps.

Implementar CI/CD com o GitOps

Tutorial: Implementar configurações com o GitOps num cluster do Kubernetes compatível com o Azure Arc

Pré-requisitos

Criar uma configuração

Utilizar a CLI do Azure

Utilizar um repositório git público

Utilizar um repositório Git privado com SSH e chaves criadas com o Flux

Utilizar um repositório Git privado com SSH e chaves fornecidas pelo utilizador

Utilizar um anfitrião Git privado com SSH e anfitriões conhecidos fornecidos pelo utilizador

Utilizar um repositório Git privado com HTTPS

Parâmetros Adicionais

Opções suportadas em --operator-params:

Validar a configuração

Aplicar a configuração de um repositório Git privado

Obter a sua chave pública

Obter a chave pública com a CLI do Azure

Obter a chave pública no portal do Azure

Adicionar chave pública com o GitHub

Utilize um repositório do Azure DevOps para adicionar a chave pública

Validar a configuração do Kubernetes

Mais exploração

Limpar os recursos

Passos seguintes

Recursos adicionais

Opções suportadas em `--operator-params`: