Tutorial: Implementar aplicações usando GitOps com Argo CD

Este tutorial descreve como usar GitOps com Argo CD em clusters Kubernetes habilitados para Azure Arc ou clusters Azure Kubernetes Service (AKS). O GitOps com Argo CD está ativado como uma extensão de cluster que te permite usar o teu repositório Git como fonte de verdade para configuração de clusters e implementação de aplicações. O Argo CD também suporta outras fontes de ficheiros comuns, como repositórios Helm e Open Container Initiative (OCI).

Pré-requisitos

Para implementar aplicações usando GitOps, precisa de um cluster Kubernetes compatível com Azure Arc ou de um cluster AKS.

Clusters do Kubernetes compatíveis com o Azure Arc

• Um cluster Kubernetes conectado ao Azure Arc que está em execução.

  Aprenda a ligar um cluster Kubernetes ao Azure Arc. Se precisar de se ligar através de um proxy outbound, certifique-se de instalar os agentes Arc com definições de proxy.

• Permissões de Microsoft.Kubernetes/connectedClusters leitura e gravação no tipo de recurso.

Clusters do Serviço Kubernetes do Azure

• Um cluster do AKS baseado numa Identidade de Serviço Gerida (MSI) em execução. Precisas de criar o cluster AKS com MSI, e não com Service Principal Name (SPN), para que esta extensão funcione.

  • Para novos clusters AKS criados com az aks create, o cluster é baseado em MSI por predefinição.
  • Para converter clusters baseados em SPN em MSI, execute az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity.
  • Para obter mais informações, consulte Usar uma identidade gerenciada no AKS.

• Permissões de Microsoft.ContainerService/managedClusters leitura e gravação no tipo de recurso.

Comum a ambos os tipos de cluster

Para instalar a extensão Argo CD, é necessário o papel de Contribuidor da Extensão Kubernetes . Depois de implementar o Argo CD, pode definir políticas RBAC do Argo CD, configurar namespaces e criar projetos de aplicação que regulem o comportamento do Argo CD. Também pode conceder a si próprio privilégios de administrador do CD Argo. Ao usar o acesso de administrador do Argo CD, pode implementar e gerir aplicações em qualquer namespace configurado no cluster. Na prática, o acesso de administrador fornece capacidades que são efetivamente equivalentes aos privilégios de administrador do cluster.

• Permissões de leitura e escrita no tipo de recurso: Microsoft.KubernetesConfiguration/extensions

• CLI do Azure, versão 2.15 ou posterior. Instale a CLI do Azure ou use os seguintes comandos para atualizar para a versão mais recente:

  az version
  az upgrade
  

• O cliente de linha de comando do Kubernetes, kubectl. kubectl já está instalado se você usar o Azure Cloud Shell.

  Instale kubectl localmente usando o az aks install-cli comando:

  az aks install-cli
  

• Registo dos seguintes fornecedores de recursos do Azure:

  az provider register --namespace Microsoft.Kubernetes
  az provider register --namespace Microsoft.ContainerService
  az provider register --namespace Microsoft.KubernetesConfiguration
  

  O registo é um processo assíncrono e deve terminar dentro de 10 minutos. Para monitorar o processo de registro, use o seguinte comando:

  az provider show -n Microsoft.KubernetesConfiguration -o table
  
  Namespace                          RegistrationPolicy    RegistrationState
  ---------------------------------  --------------------  -------------------
  Microsoft.KubernetesConfiguration  RegistrationRequired  Registered
  

• Embora a fonte deste tutorial seja um repositório Git, o Argo CD suporta outras fontes comuns de ficheiros, como repositórios Helm e Open Container Initiative (OCI).

Suporte a versões e regiões

O GitOps é atualmente suportado em regiões públicas.

Requisitos de rede

Os agentes GitOps precisam de ligações TCP de saída para a origem do repositório, pela porta 22 (SSH) ou 443 (HTTPS), para funcionarem. Os agentes também precisam de acesso às seguintes URLs de saída:

Habilitar extensões de CLI

Instale os pacotes de extensão CLI mais recentes k8s-configuration e k8s-extension:

az extension add -n k8s-configuration
az extension add -n k8s-extension

Para atualizar estes pacotes para as versões mais recentes:

az extension update -n k8s-configuration
az extension update -n k8s-extension

Para ver uma lista de todas as extensões da CLI do Azure instaladas e suas versões, use o seguinte comando:

az extension list -o table

Experimental   ExtensionType   Name                   Path                                                       Preview   Version
-------------  --------------  -----------------      -----------------------------------------------------      --------  --------
False          whl             connectedk8s           C:\Users\somename\.azure\cliextensions\connectedk8s         False     1.10.7
False          whl             k8s-configuration      C:\Users\somename\.azure\cliextensions\k8s-configuration    False     2.2.0
False          whl             k8s-extension          C:\Users\somename\.azure\cliextensions\k8s-extension        False     1.6.4

Criar extensão GitOps (Argo CD) (instalação simples)

A instalação do GitOps Argo CD suporta multitenância em modo de alta disponibilidade (HA) e suporta identidade de carga de trabalho.

O modo HA é a configuração padrão e requer quatro nós no cluster para instalar. O comando seguinte adiciona --config "redis-ha.enabled=false" para instalar a extensão num único nó.

Este comando cria a configuração mais simples ao instalar os componentes do CD Argo num novo argocd namespace com acesso a todo o cluster. O acesso a nível de cluster permite que definições de aplicações Argo CD sejam detetadas em qualquer namespace listado na configuração do mapa-configuração do Argo CD no cluster. Por exemplo: namespace1,namespace2

az k8s-extension create --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --cluster-type managedClusters \
  --name argocd \
  --extension-type Microsoft.ArgoCD \
  --config "redis-ha.enabled=false" \
  --config "configs.params.application\.namespaces=namespace1,namespace2"

pt-PT: Este comando de instalação cria um novo <namespace> namespace e instala os componentes do Argo CD no <namespace>. As definições de aplicações Argo CD nesta configuração funcionam apenas no <namespace> namespace.

Para opções adicionais de configuração, como limites de recursos, consulte values.yaml. Use estas configurações no seu comando CLI do Azure ao configurar a extensão.

Criar extensão GitOps (Argo CD) com identidade de carga de trabalho

Um método de instalação alternativo recomendado para uso em produção é a identidade de carga de trabalho. Este método utiliza identidades do Microsoft Entra ID para autenticar nos recursos do Azure, por isso não precisa de gerir segredos ou credenciais no seu repositório Git. Esta instalação utiliza autenticação de identidade de carga de trabalho ativada na versão OSS 3.0.0-rc2 ou posterior do Argo CD.

O modo HA é a configuração padrão e requer quatro nós no cluster para instalar. Uso 'redis-ha.enabled': false para instalar a extensão num único nó.

Para criar a extensão com identidade de carga de trabalho, primeiro substitua as seguintes variáveis por seus próprios valores neste modelo Bicep:

var clusterName = '<aks-or-arc-cluster-name>'

var workloadIdentityClientId = 'replace-me##-##-###-###'
var ssoApplicationClientId = 'replace-me##-##-###-###'

var url = 'https://<public-ip-for-argocd-ui>/'
var oidcConfig = '''
name: Azure
issuer: https://login.microsoftonline.com/<your-tenant-id>/v2.0
clientID: <same-value-as-ssoApplicationClientId>
azure:
  useWorkloadIdentity: true
requestedIDTokenClaims:
  groups:
    essential: true
requestedScopes:
  - openid
  - profile
  - email
'''

var defaultPolicy = 'role:readonly'
var policy = '''
p, role:org-admin, applications, *, */*, allow
p, role:org-admin, clusters, get, *, allow
p, role:org-admin, repositories, get, *, allow
p, role:org-admin, repositories, create, *, allow
p, role:org-admin, repositories, update, *, allow
p, role:org-admin, repositories, delete, *, allow
g, replace-me##-argocd-ui-entra-group-admin-id, role:org-admin
'''

resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' existing = {
  name: clusterName
}

resource extension 'Microsoft.KubernetesConfiguration/extensions@2023-05-01' = {
  name: 'argocd'
  scope: cluster
  properties: {
    extensionType: 'Microsoft.ArgoCD'
    configurationSettings: {
      'redis-ha.enabled': 'true'
      'azure.workloadIdentity.enabled': 'true'
      'azure.workloadIdentity.clientId': workloadIdentityClientId
      'azure.workloadIdentity.entraSSOClientId': ssoApplicationClientId
      'configs.cm.oidc\\.config': oidcConfig
      'configs.cm.url': url
      'configs.rbac.policy\\.default': defaultPolicy
      'configs.rbac.policy\\.csv': policy
      'configs.params.application\\.namespaces': 'default, argocd'
   }
  }
}

Crie o modelo Bicep usando o seguinte comando:

az deployment group create --resource-group <resource-group> --template-file <bicep-file>

Para opções adicionais de configuração, como limites de recursos, consulte values.yaml. Use estas configurações no modelo Bicep ao configurar a extensão.

Parâmetros

clusterName é o nome do cluster Kubernetes com suporte para AKS ou Arc.

workloadIdentityClientId é o ID do cliente da identidade gerida atribuída pelo utilizador, usada pelos componentes do Argo CD para a identidade da carga de trabalho.

ssoApplicationClientId é o ID da aplicação (cliente) do registo da aplicação Microsoft Entra usado para a autenticação SSO OIDC na interface do CD Argo. Para obter mais informações sobre a instalação e configuração gerais de ssoApplicationClientId, consulte Autenticação de Registo de Aplicações do Microsoft Entra ID com OIDC.

url é a IP pública da interface do Argo CD. Não há IP público ou nome de domínio, a menos que o cluster já tenha um controlador de entrada fornecido pelo cliente. Se sim, precisas de adicionar a regra de entrada à interface do Argo CD após a implementação. A funcionalidade de ingresso requer o suplemento de encaminhamento de aplicações e só é suportada em clusters do AKS.

oidcConfig - substitua <your-tenant-id> pelo ID de locatário do seu ID do Microsoft Entra. Substitua <same-value-as-ssoApplicationClientId-above> pelo mesmo valor que ssoApplicationClientId.

policy variável são as argocd-rbac-cm configmap definições do Argo CD. g, replace-me##-argocd-ui-entra-group-admin-id é o ID de grupo Microsoft Entra que dá acesso de administrador à interface do Argo CD. Pode encontrar o ID do grupo Microsoft Entra no portal do Azure em Microsoft Entra ID > Grupos >o nome do seu grupo> Propriedades. Você pode usar o ID de usuário do Microsoft Entra em vez de um ID de grupo do Microsoft Entra. Pode encontrar o ID de utilizador do Microsoft Entra no portal do Azure em Microsoft Entra ID > Utilizadores >o seu nome de utilizador> Propriedades.

Criar credenciais de identidade para cargas de trabalho

Para configurar novas credenciais de identidade de carga de trabalho, siga estas etapas:

1. Recupere a URL do emissor OIDC para seu cluster AKS ou cluster Kubernetes habilitado para Arc.

2. Crie uma identidade gerenciada e anote sua ID de cliente e ID de locatário.

3. Estabeleça uma credencial de identidade federada para seu cluster AKS ou cluster Kubernetes habilitado para Arc. Por exemplo:

   # For source-controller
   az identity federated-credential create \
     --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} \
     --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
     --resource-group "${RESOURCE_GROUP}" \
     --issuer "${OIDC_ISSUER}" \
     --subject
   

4. Atribua as permissões corretas para a identidade da carga de trabalho ao recurso que pretende que argocd, o controlador image-reflector ou argocd-repo-server obtenham. Por exemplo, se usar o Azure Container Registry, certifique-se de que seja aplicado Container Registry Repository Reader (para registos com ABAC) ou AcrPull (para registos não-ABAC).

Conectar-se a registros ACR privados ou repositórios ACR usando a identidade da carga de trabalho

Para utilizar o registo privado do ACR ou os repositórios do ACR, siga as instruções na documentação oficial do CD da Argo para ligação a registos privados do ACR. As etapas Rotular os pods, Criar credencial de identidade federada e Adicionar anotação à conta de serviço nesse guia foram concluídas pela extensão com a implantação do Bicep e podem ser ignoradas.

Migrar do Argo CD OSS para a extensão gerida do Argo CD

Utilize estes passos para migrar de uma instalação Argo CD autogerida para a extensão Argo CD gerida pelo Azure.

Caminho de migração

Use a seguinte sequência para evitar conflitos de controladores e reduzir o risco de migração.

1. Revise a configuração e o inventário atuais do seu CD Argo:

   • Aplicações
   • ApplicationSets
   • AppProjects
   • Credenciais e modelos de repositório (repocreds)
   • Segredos do cluster

2. Dimensione os controladores Argo CD autogeridos para zero réplicas para evitar o comportamento de controlador duplo.

3. Instala a extensão Argo CD no cluster usando definições que correspondam à tua implementação atual.

4. A funcionalidade Aplicações em qualquer namespace permite ao Argo CD gerir recursos localizados fora do seu namespace central. Se o teu cluster já usa esta definição, não precisas de mover os teus recursos para um novo namespace. Só precisas de configurar a nova extensão para vigiar os namespaces da tua aplicação existente.

   Caso A: Se já utiliza a funcionalidade Aplicações em qualquer espaço de nomes:

   1. Deixe todos os recursos Application, ApplicationSet e AppProject nos seus namespaces atuais.
   2. Configure a nova extensão gerida para monitorizar esses namespaces externos através das definições da extensão.

   Caso B: Se mover os recursos para o novo espaço de nomes da extensão:

   • Migre Applications, ApplicationsSets e AppProjects para o namespace da extensão, se necessário.

5. Migrar credenciais de repositório, segredos de cluster e repocreds para o espaço de nomes da extensão.

6. Valida que as aplicações sincronizam e atingem o estado saudável esperado.

7. Remova a antiga implementação autogerida do Argo CD após a conclusão da validação.

A extensão gerida utiliza as mesmas APIs Argo CD e definições personalizadas de recursos (CRDs), por isso pode reutilizar a maioria dos manifestos existentes com alterações mínimas.

Limitações atuais

• Atualizações diretas para os Argo CD ConfigMaps não são suportadas.
• Use a API de configuração e as definições da extensão para aplicar alterações de configuração do Argo CD.

Configurar monitorização com Azure Managed Prometheus e Azure Managed Grafana

Pode publicar métricas do Argo CD no Azure Managed Prometheus e visualizá-las no Azure Managed Grafana.

1. Ative o Azure Managed Prometheus para o seu cluster. Consulte Ativar a monitorização para clusters do Azure Kubernetes Service (AKS).

2. Atualize a configuração da sua extensão para ativar métricas e ServiceMonitors.

   var clusterName = '<aks-or-arc-cluster-name>'
   
   resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' existing = {
     name: clusterName
   }
   
   resource extension 'Microsoft.KubernetesConfiguration/extensions@2023-05-01' = {
     name: 'argocd'
     scope: cluster
     properties: {
       extensionType: 'Microsoft.ArgoCD'
       configurationSettings: {
         // Keep your existing settings and add these metrics flags.
         'controller.metrics.enabled': 'true'
         'controller.metrics.serviceMonitor.enabled': 'true'
         'server.metrics.enabled': 'true'
         'server.metrics.serviceMonitor.enabled': 'true'
         'repoServer.metrics.enabled': 'true'
         'repoServer.metrics.serviceMonitor.enabled': 'true'
         'applicationSet.metrics.enabled': 'true'
         'applicationSet.metrics.serviceMonitor.enabled': 'true'
         'apiVersionOverrides.monitoring': 'azmonitoring.coreos.com/v1'
       }
     }
   }
   

3. Importa o dashboard Grafana 14584 para a tua instância Azure Managed Grafana.

4. Se os painéis mostrarem Sem dados, atualize as consultas do painel para ter em conta a nomenclatura de trabalhos do Azure Managed Prometheus.

5. Nos painéis de telemetria do controlador (Utilização da Memória, Utilização do CPU, goroutines), alterar:

   • De job="argocd-metrics"
   • A job=~"argocd.*-metrics"

6. Nos painéis do repo-server (Memória utilizada, goroutines), alterar:

   • De job="argocd-repo-server"
   • A job="argocd-repo-server-metrics"

7. Guarda o dashboard e verifica a ingestão de métricas.

Ativar o Argo CD no portal do Azure

Pode ativar o Argo CD no portal do Azure para ver o estado da candidatura e o estado da sincronização, e para aceder à interface do Argo CD. Para ativar o CD Argo no portal Azure, siga estes passos:

1. Vai ao teu cluster no portal do Azure.

2. No menu de serviço, em Configurações, selecione GitOps.

3. Selecione Ativar Argo CD (Pré-visualização).

4. Na seção Noções básicas :

   1. Define o namespace onde o CD do Argo corre. Por defeito, o namespace é argocd.
   2. Se desejar, ative o Redis High Availability (HA). Esta opção requer pelo menos quatro nós no cluster.
   3. Opcionalmente, adicione quaisquer namespaces extra a serem observados.
   4. Para clusters AKS apenas, opcionalmente ative o single log-on (SSO) para que os utilizadores possam iniciar sessão usando o Microsoft Entra ID, especificando uma Aplicação e um ou mais Grupos para permitir o acesso à interface do Argo CD.
   5. Se desejar, ative a identidade da carga de trabalho para permitir que o CD do Argo aceda aos serviços do Azure de forma segura sem armazenar segredos. Para o fazer, selecione a caixa Enable Workload Identity e especifique uma identidade gerida e um Azure Container Registry de onde extrair manifestos de aplicação ou artefactos de contentores.

   

5. Selecione Seguinte para continuar.

6. Para clusters AKS que ativaram o complemento de encaminhamento de aplicações, o separador Ingress permite-lhe criar um recurso Ingress para encaminhar tráfego para um serviço. Se desejar, selecione Ativar Entrada e insira o seu nome de entrada, detalhes do certificado e nome de domínio. Selecione Seguinte para continuar.

7. Na secção Rever + Implementar , revê as tuas definições e depois seleciona Implementar para ativar o Argo CD no cluster.

Aceda à interface do Argo CD

Se não houver controlador de entrada existente para o cluster AKS, podes expor diretamente a interface do Argo CD usando um serviço LoadBalancer. O comando seguinte expõe a interface do Argo CD nas portas 80 e 443.

kubectl -n argocd expose service argocd-server --type LoadBalancer --name argocd-server-lb --port 80 --target-port 8080

Para aceder à interface do Argo CD a partir do portal do Azure, aceda ao seu cluster. No menu de serviço, em Configurações, selecione GitOps. Depois, selecione o link mostrado para a interface do Argo CD.

Implementar a aplicação Argo CD

Depois de instalar a extensão Argo CD, pode implementar uma aplicação usando a interface ou CLI do Argo CD. O exemplo seguinte utiliza kubectl apply para implementar o AKS Store numa aplicação Argo CD no projeto predefinido do Argo CD no espaço de nomes argocd.

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: aks-store-demo
  namespace: argocd
spec:
  project: default
  source:
      repoURL: https://github.com/Azure-Samples/aks-store-demo.git
      targetRevision: HEAD
      path: kustomize/overlays/dev
  syncPolicy:
      automated: {}
  destination:
      namespace: argocd
      server: https://kubernetes.default.svc
EOF

A aplicação de demonstração da loja AKS está instalada no argocd namespace. Para consultar a página da candidatura, siga estas instruções. Certifique-se de visitar o endereço IP usando http e não https.

Atualizar configuração da extensão

Os mapas de configuração do Argo CD podem ser atualizados após a instalação e outras configurações de extensão usando o seguinte comando:

az k8s-extension update --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --cluster-type <cluster-type> \
  --name argocd \
  --config "configs.cm.url='https://<public-ip-for-argocd-ui>/auth/callback'"

Atualiza o configmap do Argo CD através da extensão, para que as definições não sejam sobrescritas. Aplicar o modelo Bicep é um método alternativo ao CLI do Azure para atualizar a configuração.

Excluir a extensão

Use os seguintes comandos para excluir a extensão.

az k8s-extension delete -g <resource-group> -c <cluster-name> -n argocd -t managedClusters --yes

Próximos passos

• Problemas de ficheiros e pedidos de funcionalidades no repositório Azure/AKS. Certifique-se de incluir a palavra ArgoCD na descrição ou título.
• Explore o exemplo de código de engenharia da AKS-Platform, que implementa o OSS Argo CD com Backstage e fornecedor da API do Cluster para Azure (CAPZ) ou Crossplane.