Tutorial: Implementación de aplicaciones con GitOps con ArgoCD

En este tutorial, se explica cómo usar GitOps en un clúster de Kubernetes. GitOps con ArgoCD está habilitado como una extensión de clúster en clústeres de Kubernetes habilitados para Azure Arc o clústeres de Azure Kubernetes Service (AKS). Con GitOps, puede usar el repositorio de Git como único origen de información para la configuración de clústeres y la implementación de aplicaciones.

Prerrequisitos

Para implementar aplicaciones mediante GitOps, necesita un clúster de Kubernetes habilitado para Azure Arc o un clúster de AKS:

Clústeres de Kubernetes habilitados para Azure Arc

• Un clúster de Kubernetes habilitado para Azure Arc que esté conectado y en funcionamiento.

  Aprenda a conectar un clúster de Kubernetes a Azure Arc. Si necesita conectarse a través de un proxy de salida, asegúrese de instalar los agentes de Arc con la configuración del proxy.

• Permisos de lectura y escritura en el tipo de recurso Microsoft.Kubernetes/connectedClusters.

Clústeres de Azure Kubernetes Service

• Un clúster de AKS basado en MSI que esté en funcionamiento.

  Importante

  El clúster de AKS debe crearse con Identidad de Servicio Gestionado (MSI), no con el Nombre Principal de Servicio (SPN), para que esta extensión funcione. En el caso de los nuevos clústeres de AKS creados con az aks create, el clúster se basa en MSI de manera predeterminada. Para convertir clústeres basados en SPN en MSI, ejecute az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity. Para más información, consulte Uso de una identidad administrada en AKS.

• Permisos de lectura y escritura en el tipo de recurso Microsoft.ContainerService/managedClusters.

Común a los dos tipos de clúster

• Permisos de lectura y escritura en estos tipos de recurso:

  • Microsoft.KubernetesConfiguration/extensions

• Versión 2.15 o posterior de la CLI de Azure. Instale la CLI de Azure o use los siguientes comandos para actualizar a la versión más reciente:

  az version
  az upgrade
  

• El cliente de línea de comandos de Kubernetes, kubectl. kubectl ya está instalado si usa Azure Cloud Shell.

  Instale kubectl localmente mediante el comando az aks install-cli:

  az aks install-cli
  

• Registro de los siguientes proveedores de recursos de Azure:

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

  El registro es un proceso asincrónico y debe finalizar en 10 minutos. Para supervisar el proceso de registro, use el comando siguiente:

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

Soporte de versiones y regiones

GitOps se admite actualmente en todas las regiones que soporta Kubernetes con compatibilidad de Azure Arc. GitOps se admite actualmente en un subconjunto de las regiones que admite AKS. La disponibilidad del servicio GitOps se irá ampliando a nuevas regiones con regularidad.

Requisitos de red

Los agentes de GitOps requieren un TCP saliente (de salida) al origen del repositorio en el puerto 22 (SSH) o en el puerto 443 (HTTPS) para funcionar. Los agentes también requieren acceso a las siguientes direcciones URL de salida:

Habilitación de extensiones de la CLI

Instale los paquetes de extensión de la CLI k8s-configuration y k8s-extension más recientes:

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

Para actualizar estos paquetes a las versiones más recientes:

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

Para ver una lista de todas las extensiones de la CLI de Azure instaladas y sus versiones, utilice el siguiente 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

Creación de la extensión GitOps (ArgoCD) (instalación sencilla)

La Instalación de GitOps ArgoCD admite multiinquilino en modo de alta disponibilidad (HA) y admite la identidad de carga de trabajo.

Este comando crea la configuración más sencilla que instala los componentes de ArgoCD en un nuevo argocd espacio de nombres con acceso para todo el clúster. El acceso para todo el clúster permite detectar definiciones de aplicaciones ArgoCD en cualquier espacio de nombres que aparezca en la configuración de configmap de ArgoCD en el clúster. Por ejemplo: 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"

Si desea limitar el acceso de ArgoCD a un espacio de nombres específico, use los parámetros --config namespaceInstall=true junto con --target-namespace <namespace>. Este comando de instalación crea una nueva <namespace> namespace e instala los componentes ArgoCD en <namespace>. El comando de instalación también permite instalar varias instancias de ArgoCD en el mismo clúster. Las definiciones de aplicaciones de ArgoCD en esta configuración solo funcionan dentro del espacio de nombres <namespace>.

Creación de una extensión de GitOps (ArgoCD) con identidad de carga de trabajo

Un método de instalación alternativo recomendado para el uso de producción es la identidad de la carga de trabajo. Este método permite usar identidades de Id. de Microsoft Entra para autenticarse en recursos de Azure sin necesidad de administrar secretos ni credenciales en el repositorio de Git. Esta instalación utiliza la autenticación de identidad de carga de trabajo habilitada en la versión 3.0.0-rc2 o posterior del sistema operativo de ArgoCD.

Para crear la extensión con la identidad de carga de trabajo, reemplace primero las siguientes variables por sus propios valores en esta plantilla de 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'
    }
  }
}

La plantilla de Bicep se puede crear mediante este comando:

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

Parámetros

clusterName es el nombre del clúster de Kubernetes habilitado para AKS o Arc.

workloadIdentityClientId y ssoWorkloadIdentityClientId son los identificadores de cliente de la identidad administrada que se desea usar para la identidad de carga de trabajo. ssoWorkloadIdentityClientId se usa para la autenticación de la interfaz de usuario de ArgoCD y workloadIdentityClientId se usa para la identidad de carga de trabajo para los componentes de ArgoCD. Visite Autenticación de registro de aplicaciones de Microsoft Entra ID mediante OIDC para obtener información adicional sobre la configuración general y la configuración de ssoWorkloadIdentityClientId.

url es la dirección IP pública de la interfaz de usuario de ArgoCD. No hay ningún nombre de dominio o dirección IP pública a menos que el clúster ya tenga un controlador de entrada proporcionado por el cliente. Si es así, la regla de entrada debe agregarse a la interfaz de usuario de ArgoCD después de la implementación.

oidcConfig : reemplace <your-tenant-id> por el identificador de inquilino de Microsoft Entra ID. Reemplace <same-value-as-ssoWorkloadIdentityClientId-above> por el mismo valor que ssoWorkloadIdentityClientId.

La policy variable es la argocd-rbac-cm configmap configuración de ArgoCD. g, replace-me##-argocd-ui-entra-group-admin-id es el identificador de grupo de Microsoft Entra que proporciona acceso de administrador a la interfaz de usuario de ArgoCD. El identificador de grupo de Microsoft Entra se puede encontrar en el portal de Azure bajo Microsoft Entra ID > Grupos >tu-nombre-de-grupo> Propiedades. Puede usar el identificador de usuario de Microsoft Entra en lugar de un identificador de grupo de Microsoft Entra. El identificador de usuario de Microsoft Entra se puede encontrar en el portal de Azure en Microsoft Entra ID > Usuarios >nombre-de-usuario> Propiedades.

Creación de credenciales de identidad de carga de trabajo

Para configurar nuevas credenciales de identidad de carga de trabajo, siga estos pasos:

1. Recupere la dirección URL del emisor de OIDC para el Clúster de AKS o el Clúster de Kubernetes habilitado para Arc.

2. Cree una identidad administrada y anote su identificador de cliente e identificador de inquilino.

3. Establezca una credencial de identidad federada para el clúster de AKS o el clúster de Kubernetes habilitado para Arc. Por ejemplo:

   # 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. Asegúrese de proporcionar los permisos adecuados para la identidad de carga de trabajo para el recurso que desea que extraiga el controlador source-controller o image-reflector. Por ejemplo, si usa Azure Container Registry, asegúrese de que se haya aplicado Container Registry Repository Reader (para registros habilitados para ABAC) o asegúrese de que (para registros que no son de ABAC).

Conexión a registros de ACR privados o repositorios de ACR mediante la identidad de carga de trabajo

Para usar el registro de ACR privado o los repositorios de ACR, siga las instrucciones de la documentación oficial de ArgoCD para conectarse a registros de ACR privados. Etiquetar los pods, Crear credenciales de identidad federada y Agregar anotación a la cuenta de servicio en esa guía se ha completado mediante la extensión con la implementación de Bicep y se puede omitir.

Acceso a la interfaz de usuario de ArgoCD

Si no hay ningún controlador de entrada existente para el clúster de AKS, la interfaz de usuario de ArgoCD se puede exponer directamente mediante un servicio LoadBalancer. El siguiente comando expondrá la interfaz de usuario de ArgoCD en el puerto 80 y 443.

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

Implementación de la aplicación ArgoCD

Ahora que la extensión ArgoCD está instalada, puede implementar una aplicación mediante la INTERFAZ de usuario o la CLI de ArgoCD. En el ejemplo siguiente simplemente se usa kubectl apply para implementar la tienda AKS dentro de una aplicación ArgoCD en el proyecto predeterminado de ArgoCD en el espacio de nombres argocd por defecto.

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

La aplicación de demostración del almacén de AKS se instaló en el espacio de nombres pets. Consulte la página web de la aplicación siguiendo estas instrucciones. Asegúrese de visitar la dirección IP mediante http y no https.

Actualización de la configuración de la extensión

Los mapas de configuración de ArgoCD se pueden actualizar después de la instalación y otras opciones de configuración de extensión mediante el siguiente 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'”

Es importante actualizar el mapa de configuración de ArgoCD a través de la extensión, por lo que la configuración no se sobrescribe. La aplicación de la plantilla de bicep es un método alternativo az cli para actualizar la configuración.

Eliminación de la extensión

Use los comandos siguientes para eliminar la extensión.

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

Pasos siguientes

• Informe problemas y solicitudes de características en el repositorio de Azure/AKS y asegúrese de incluir la palabra "ArgoCD" en la descripción o el título.
• Explore el Ejemplo de código de ingeniería de plataforma de AKS que implementa OSS ArgoCD con Backstage y Cluster API Provider para Azure (CAPZ) o Crossplane.