Partilhar via

Tutorial: Implantar aplicativos usando GitOps com ArgoCD

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

Importante

O GitOps com ArgoCD está atualmente disponível em versão de pré-lançamento. Consulte os Termos de Utilização Suplementares das Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão em versão beta, pré-visualização ou ainda não disponibilizadas para disponibilidade geral. Para suporte à extensão GitOps de produção, experimente a extensão GitOps usando o Flux.

Sugestão

Embora a fonte neste tutorial seja um repositório Git, o ArgoCD suporta outras fontes de arquivos comuns, como 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 um cluster AKS:

Clusters do Kubernetes compatíveis com o Azure Arc

Clusters do Serviço Kubernetes do Azure

  • Um cluster AKS baseado em MSI que está em funcionamento.

    Importante

    O cluster AKS precisa ser criado com a Identidade de Serviço Gerenciado (MSI), e não com o Nome da Entidade de Serviço (SPN), para que essa 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

  • Permissões de leitura e gravação nestes tipos de recursos:

    • 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

Suporte a versões e regiões

Atualmente, há suporte para o GitOps em todas as regiões suportadas pelo Kubernetes habilitado para Azure Arc. O GitOps é suportado atualmente num subconjunto das regiões suportadas pelo AKS. O serviço GitOps está adicionando novas regiões suportadas em uma cadência regular.

Requisitos de rede

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

Ponto final (DNS) Descrição
https://management.azure.com É necessário que o agente comunique com o serviço de Configuração do Kubernetes.
https://<region>.dp.kubernetesconfiguration.azure.com Ponto final do plano de dados para que o agente atualize o estado e obtenha as informações de configuração. Depende de <region> (as regiões suportadas mencionadas anteriormente).
https://login.microsoftonline.com É necessário obter e atualizar os tokens do Azure Resource Manager.
https://mcr.microsoft.com Necessário para extrair imagens de contêiner para controladores.

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 (ArgoCD) (instalação simples)

A instalação do GitOps ArgoCD suporta multilocação no modo de alta disponibilidade (HA) e suporta identidade de carga de trabalho.

Importante

O modo HA é a configuração padrão e requer três nós no cluster para poder ser instalado. O comando abaixo adiciona --config deployWithHighAvailability=false para que a extensão seja instalada em um único nó.

Este comando cria a configuração mais simples instalando os componentes do ArgoCD em um novo argocd namespace com acesso em todo o cluster. O acesso em todo o cluster permite que as definições do aplicativo ArgoCD sejam detetadas em qualquer namespace listado na configuração do mapa de configuração do ArgoCD 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 \
--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 os --config namespaceInstall=true parâmetros juntamente 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 de aplicativo ArgoCD nesta configuração só funcionam no <namespace> namespace.

Criar extensão GitOps (ArgoCD) 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. Esse método permite que você use identidades de ID do Microsoft Entra para autenticar recursos do Azure sem precisar gerenciar segredos ou credenciais em seu repositório Git. Esta instalação utiliza a autenticação de identidade de carga de trabalho habilitada na versão OSS 3.0.0-rc2 ou posterior do ArgoCD.

Importante

O modo HA é a configuração padrão e requer três nós no cluster para poder ser instalado. Adicione --config deployWithHighAvailability=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 ssoWorkloadIdentityClientId = '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-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.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 com suporte para AKS ou Arc.

workloadIdentityClientId e ssoWorkloadIdentityClientId são os IDs de cliente da identidade gerenciada desejados para serem usados para identidade de carga de trabalho. O ssoWorkloadIdentityClientId é usado para a autenticação para a interface do usuário do ArgoCD e o workloadIdentityClientId é usado para a identidade da carga de trabalho para os componentes do ArgoCD. Visite Microsoft Entra ID App Registration Auth using OIDC para obter informações adicionais sobre a instalação geral e configuração do ssoWorkloadIdentityClientId.

url é o IP público da interface do usuário do ArgoCD. 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. Em caso afirmativo, a regra de entrada precisa ser adicionada à interface do usuário do ArgoCD após a implantação.

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

policy variável são as argocd-rbac-cm configmap configurações do ArgoCD. g, replace-me##-argocd-ui-entra-group-admin-id é o ID de grupo do Microsoft Entra que dá acesso de administrador à interface do usuário do ArgoCD. O ID do grupo do Microsoft Entra pode ser encontrado 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. O ID de utilizador do Microsoft Entra pode ser encontrado no portal do Azure em Microsoft Entra ID > Utilizadores >your-user-name> 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 system:serviceaccount:"argocd":"source-controller" --audience api://AzureADTokenExchange

  4. Certifique-se de fornecer permissões adequadas para a identidade da carga de trabalho para o recurso que você deseja que o controlador de origem ou o controlador refletor de imagem extraia. Por exemplo, se estiver usando o Registro de Contêiner do Azure, verifique se Container Registry Repository Reader (para registros habilitados para ABAC) ou AcrPull (para registros não ABAC) foi aplicado.

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

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

Acesse a interface do usuário do ArgoCD

Se não houver nenhum controlador de entrada existente para o cluster AKS, a interface do usuário do ArgoCD poderá ser exposta diretamente usando um serviço LoadBalancer. O comando a seguir irá 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 o aplicativo ArgoCD

Agora que a extensão ArgoCD está instalada, você pode implantar um aplicativo usando a interface do usuário ou CLI do ArgoCD. O exemplo a seguir simplesmente usa kubectl apply para implantar o armazenamento AKS dentro de um aplicativo ArgoCD para o projeto ArgoCD padrão no argocd namespace.

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 da loja AKS foi instalado no pets namespace. Consulte a página da aplicação seguindo estas instruções. Certifique-se de visitar o endereço IP usando http e não https.

Atualizar configuração da extensão

ArgoCD configmaps pode ser atualizado após a instalação e outras definiçõ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 mapa de configuração do ArgoCD através da extensão, para que as configurações não sejam substituídas. A aplicação do modelo bicep é um método alternativo para atualizar a az cli 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