Compartilhar via

Tutorial: Implantar aplicativos usando o GitOps com o ArgoCD

Este tutorial descreve como usar o GitOps em um cluster de Kubernetes. O GitOps com o ArgoCD está habilitado como uma extensão de cluster nos clusters do Azure Arc-enabled Kubernetes ou do AKS (Serviço de Kubernetes do Azure). Com o GitOps, você pode usar o repositório Git como a fonte de verdade para a configuração do cluster e a implantação do aplicativo.

Importante

O GitOps com o ArgoCD está atualmente em VERSÃO PRÉVIA. Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral. Para obter suporte à extensão gitops de produção, experimente a extensão GitOps usando o Flux.

Dica

Embora a origem neste tutorial seja um repositório Git, o ArgoCD dá suporte a outras fontes de arquivo comuns, como os repositórios Helm e Open Container Initiative (OCI).

Pré-requisitos

Para implantar aplicativos usando o GitOps, você precisa de um cluster kubernetes habilitado para Azure Arc ou de um cluster do AKS:

Clusters do Kubernetes habilitados para o Azure Arc

Clusters do Serviço de Kubernetes do Azure

  • Um cluster do AKS baseado em MSI que está funcionando.

    Importante

    O cluster do AKS precisa ser criado com MSI (Identidade de Serviço Gerenciado), não com o SPN (Nome da Entidade de Serviço) para que essa extensão funcione. Quanto aos novos clusters AKS criados com az aks create, o cluster é baseado em MSI por padrã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, confira Usar uma identidade gerenciada no AKS.

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

Comum a ambos os tipos de cluster

  • Permissões de leitura e de gravação nestes tipos 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 atualizá-la para a última versão:

    az version
az upgrade

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

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

    az aks install-cli

  • Registro dos provedores de recursos do Azure a seguir:

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

    O registro é um processo assíncrono e deve ser concluído em dez minutos. Use o seguinte código para monitorar o processo de registro:

    az provider show -n Microsoft.KubernetesConfiguration -o table

Namespace                          RegistrationPolicy    RegistrationState
---------------------------------  --------------------  -------------------
Microsoft.KubernetesConfiguration  RegistrationRequired  Registered

Suporte de versão e região

Atualmente, há suporte para o GitOps em todas as regiões às quais o Kubernetes habilitado para Azure Arc dá suporte. No momento, o GitOps tem suporte em um subconjunto das regiões às quais o AKS dá suporte. O serviço GitOps adiciona novas regiões com suporte em uma cadência regular.

Requisitos de rede

Os agentes do GitOps exigem conexões TCP de saída para a origem do repositório, utilizando a porta 22 (SSH) ou a porta 443 (HTTPS), para funcionar. Eles também exigem acesso às seguintes URLs de saída:

Ponto de extremidade (DNS) Descrição
https://management.azure.com Necessário para que o agente se comunique com o Serviço de Configuração de Kubernetes.
https://<region>.dp.kubernetesconfiguration.azure.com Ponto de extremidade do plano de dados para o agente enviar o status por push e buscar informações de configuração. Depende de <region> (as regiões com suporte mencionadas anteriormente).
https://login.microsoftonline.com Necessário para buscar e atualizar tokens do Azure Resource Manager.
https://mcr.microsoft.com Necessário para efetuar pull de imagens de contêiner para controladores.

Habilitar as extensões da CLI

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

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

Para atualizar esses 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 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 do GitOps (ArgoCD) (instalação simples)

A instalação do GitOps ArgoCD dá suporte a vários locatários no modo de alta disponibilidade (HA) e dá suporte à identidade da carga de trabalho.

Importante

O modo de HA é a configuração padrão e requer três nós no cluster para poder instalar. O comando a seguir adiciona --config deployWithHighAvailability=false para instalar a extensão em um único nó.

Esse comando cria a configuração mais simples que instala os componentes do ArgoCD em um novo argocd namespace com acesso em todo o cluster. O acesso em todo o cluster permite que definições de aplicativo ArgoCD sejam detectadas em qualquer namespace listado na configuração de configmap do ArgoCD no cluster. Por exemplo: namespace1,namespace2

az k8s-extension create --resource-group <resource-group> --cluster-names <cluster-name> \
--cluster-type managedClusters \
--name argocd \
--extension-type Microsoft.ArgoCD \
--auto-upgrade false \
--release-train preview \
--version 0.0.7-preview \
--config deployWithHightAvailability=false \
--config namespaceInstall=false \
–-config “config-maps.argocd-cmd-params-cm.data.application\.namespaces=namespace1,namespace2”

Se você quiser limitar o acesso do ArgoCD a um namespace específico, use o conjunto de parâmetros --config namespaceInstall=true junto com --target-namespace <namespace>. Este comando de instalação cria um novo <namespace> namespace e instala os componentes do ArgoCD no <namespace>. O comando de instalação também permite a capacidade de instalar várias instâncias do ArgoCD no mesmo cluster. As definições do aplicativo ArgoCD nessa configuração só funcionam no <namespace> namespace.

Criar extensão do GitOps (ArgoCD) com identidade de carga de trabalho

Um método de instalação alternativo recomendado para uso de produção é workload identity. Esse método permite que você use identidades de ID do Microsoft Entra para autenticar nos recursos do Azure sem a necessidade de gerenciar segredos ou credenciais em seu repositório Git. Essa instalação utiliza a autenticação de identidade de carga de trabalho habilitada na versão 3.0.0-rc2 ou posterior do OSS do ArgoCD.

Importante

O modo de HA é a configuração padrão e requer três nós no cluster para poder instalar. Adicione --config deployWithHighAvailability=false para instalar a extensão em um único nó.

Para criar a extensão com a identidade da 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 ssoWorkloadIdentityClientId = 'replace-me##-##-###-###'

var url = 'https://<public-ip-for-argocd-ui>/auth/callback'
var oidcConfig = '''
name: Azure
issuer: https://login.microsoftonline.com/<your-tenant-id>/v2.0
clientID: <same-value-as-ssoWorkloadIdentityClientId-above>
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-Microsoft 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'
    autoUpgradeMinorVersion: false
    releaseTrain: 'preview'
    version: '0.0.7-preview'
    configurationSettings: {
      'workloadIdentity.enable': 'true'
      'workloadIdentity.clientId': workloadIdentityClientId
      'workloadIdentity.Microsoft EntraSSOClientId': ssoWorkloadIdentityClientId
      'config-maps.argocd-cm.data.oidc\\.config': oidcConfig
      'config-maps.argocd-cm.data.url': url
      'config-maps.argocd-rbac-cm.data.policy\\.default': defaultPolicy
      'config-maps.argocd-rbac-cm.data.policy\\.csv': policy
      'config-maps.argocd-cmd-params-cm.data.application\\.namespaces': 'default, argocd'
    }
  }
}

O modelo Bicep pode ser criado usando este comando:

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

Parâmetros

clusterName é o nome do cluster Kubernetes habilitado por AKS ou Arc.

workloadIdentityClientId e ssoWorkloadIdentityClientId são as IDs de cliente da identidade gerenciada desejada para serem usadas para a identidade da carga de trabalho. O ssoWorkloadIdentityClientId é usado para a autenticação da interface do usuário do ArgoCD e o workloadIdentityClientId é usado para a identidade da carga de trabalho dos componentes do ArgoCD. Visite Autenticação de Registro de Aplicativo do Microsoft Entra ID usando o OIDC para obter mais informações sobre a configuração geral do ssoWorkloadIdentityClientId.

url é o IP público da interface do usuário do ArgoCD. Não há nenhum IP público ou nome de domínio, a menos que o cluster já tenha um controlador de entrada fornecido pelo cliente. Nesse caso, a regra de entrada precisa ser adicionada à interface do usuário do ArgoCD após a implantação.

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

A variável policy são as configurações argocd-rbac-cm configmap do ArgoCD. g, replace-me##-argocd-ui-entra-group-admin-id é a ID de grupo do Microsoft Entra que fornece acesso de administrador à interface do usuário do ArgoCD. A ID do grupo do Microsoft Entra pode ser encontrada no portal do Azure em Microsoft Entra ID> Grupos>o nome do seu grupo>Propriedades. Você pode usar a ID de usuário do Microsoft Entra em vez de uma ID de grupo do Microsoft Entra. O ID de usuário do Microsoft Entra pode ser encontrado no portal do Azure em Microsoft Entra ID > Usuários >seu-nome-de-usuário> Propriedades.

Criar credenciais de identidade de carga de trabalho

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

  1. Recupere a URL do emissor do OIDC para o cluster do AKS ou o cluster kubernetes habilitado para Arc.

  2. Crie uma identidade gerenciada e anote a ID do cliente e a ID do locatário.

  3. Estabeleça uma credencial de identidade federada para o cluster do AKS ou o 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 system:serviceaccount:"argocd":"source-controller" --audience api://AzureADTokenExchange

  4. Certifique-se de fornecer as permissões adequadas para a identidade da carga de trabalho do recurso que você deseja que o controlador de origem ou do refletor de imagens efetue pull. Por exemplo, se utilizar o Registro de Contêiner do Azure, são exigidas as permissões AcrPull.

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

Para utilizar o registro do ACR privado ou repositórios do ACR, siga as instruções na documentação oficial do ArgoCD para se conectar a registros 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.

Acessar a interface do usuário do ArgoCD

Se não houver nenhum controlador de entrada existente para o cluster do AKS, a interface do usuário do ArgoCD poderá ser exposta diretamente usando um serviço LoadBalancer. O comando a seguir exporá a interface do usuário do ArgoCD nas portas 80 e 443.

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

Implantar aplicativo ArgoCD

Agora que a extensão ArgoCD está instalada, você pode implantar um aplicativo usando a interface do usuário do ArgoCD ou a CLI. O exemplo a seguir simplesmente usa kubectl apply para implantar a loja AKS dentro de um aplicativo ArgoCD no projeto padrão do ArgoCD no namespace 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

O aplicativo de demonstração do repositório do AKS foi instalado no pets namespace. Consulte a página da Web do aplicativo seguindo estas instruções. Visite o endereço IP usando http e não https.

Atualizar configuração de extensão

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

az k8s-extension update --resource-group <resource-group> --cluster-name <cluster-name> --cluster-type <cluster-type> --name Microsoft.ArgoCD –-config "config-maps.argocd-cm.data.url='https://<public-ip-for-argocd-ui>/auth/callback'”

É importante atualizar o configmap do ArgoCD por meio da extensão, para que as configurações não fiquem substituídas. Aplicar o modelo do bicep é um método alternativo para o az cli atualizar a configuração.

Excluir a extensão

Use os comandos a seguir para excluir a extensão.

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

Próximas etapas

  • Last updated on