> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supervisión administrada de Azure

> Recopile métricas de Vantage 3.0 autoalojado en un clúster de AKS mediante Azure Monitor Workspace, Azure Managed Grafana y un Prometheus en la malla que recopila métricas a través de Istio mTLS.

Esta guía le muestra cómo recopilar métricas de la aplicación Vantage en un clúster de AKS que ya tiene habilitada la supervisión administrada de Azure (Azure Monitor Workspace + Managed Grafana + el agente `ama-metrics`). Al finalizar, las métricas de la aplicación Vantage aparecerán junto con sus métricas de infraestructura en el mismo Azure Managed Grafana, recopiladas por un Prometheus en la malla que accede a los endpoints de Vantage a través de Istio mTLS.

<Note>
  Para entender por qué existe este patrón (incluida la restricción de Istio mTLS que lo motiva), consulte [Descripción general de la supervisión](/es/vantage/self-hosted/v3.0/monitoring/overview).
</Note>

<div id="why-this-pattern-exists">
  ## Por qué existe este patrón
</div>

El agente `ama-metrics` implementado por Azure gestiona automáticamente las métricas de infraestructura de Kubernetes (kubelet, cadvisor, kube-state-metrics). También puede recopilar métricas del proxy de Istio, como `istio_requests_total`, mediante anotaciones de pod, ya que el sidecar de Envoy las expone en puertos de texto no cifrado.

Las métricas de la aplicación Vantage son diferentes: se exponen en el puerto 8080 del container, que es interceptado por el sidecar de Envoy y está sujeto a la aplicación estricta de mTLS. El agente `ama-metrics` se ejecuta en `kube-system` sin un sidecar de Istio y no puede presentar certificados mTLS válidos, por lo que no puede recopilar métricas de endpoints de aplicaciones en namespaces integrados en la malla. Microsoft documenta esto como una limitación conocida: ["Actualmente no se admite la recopilación de métricas desde una configuración de Istio con autenticación mutua TLS."](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/prometheus-istio-integration#limitations)

Para recopilar métricas de la aplicación Vantage, implementa una instancia de Prometheus **dentro de la malla de Istio**. Esta instancia de Prometheus se ejecuta con un sidecar de Istio, exporta los certificados de la malla, los usa para recopilar endpoints de aplicaciones a través de mTLS y envía las métricas mediante remote-write al mismo Azure Monitor Workspace que usa `ama-metrics`.

<div id="how-it-works">
  ## Cómo funciona
</div>

Las aplicaciones de Vantage están instrumentadas con SDK de OpenTelemetry y exponen métricas en formato Prometheus en `/metrics-text` a través del puerto 8080 del contenedor. Los servicios que exponen métricas llevan la etiqueta `abbyy.platform.metrics.text.endpoint: "1"`.

Prometheus en la malla recopila esas métricas de la siguiente manera:

1. Se ejecuta con un sidecar de Istio (`sidecar.istio.io/inject: "true"`).
2. Exporta los certificados mTLS de Istio mediante la anotación de configuración del proxy `OUTPUT_CERTS`.
3. Monta esos certificados en el contenedor de Prometheus en `/etc/prom-certs/`.
4. Configura el `ServiceMonitor` (creado por el chart `vantage-selfhosted` en el Step 6) para recopilar métricas mediante `scheme: https`, usando el certificado de CA de Istio, el certificado de cliente y la clave.

<div id="architecture">
  ## Arquitectura
</div>

| Componente                                        | Función                                                                                                                                                        |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Azure Monitor Workspace**                       | Backend compatible con Prometheus que almacena todas las métricas.                                                                                             |
| **Azure Managed Grafana**                         | Capa de visualización, preconfigurada para usar Azure Monitor Workspace como origen de datos.                                                                  |
| **agente `ama-metrics`** (administrado por Azure) | Recopila las métricas predeterminadas de la infraestructura de Kubernetes. Se implementa automáticamente cuando Prometheus está habilitado en AKS.             |
| **Prometheus en la malla** (personalizado)        | Prometheus con inyección de Istio que recopila métricas de la aplicación Vantage a través de mTLS y las envía mediante remote-write a Azure Monitor Workspace. |
| **`ServiceMonitor`** (personalizado)              | Define los objetivos de scrape de Vantage: `/metrics-text` en servicios etiquetados con `abbyy.platform.metrics.text.endpoint: "1"`.                           |

<div id="prerequisites">
  ## Requisitos previos
</div>

* clúster de AKS con el complemento de malla de servicios de Istio habilitado (mTLS STRICT).
* Azure Monitor Workspace aprovisionado y vinculado al clúster de AKS.
* Azure Managed Grafana aprovisionado y vinculado a Azure Monitor Workspace.
* agente `ama-metrics` en ejecución en el clúster (habilitado mediante AKS Monitor Settings).
* emisor OIDC habilitado en el clúster de AKS (necesario para la identidad de carga de trabajo).
* CRD de Prometheus Operator instalados (se incluyen con `ama-metrics`).

<div id="step-1-provision-azure-resources">
  ## Paso 1: Aprovisione recursos de Azure
</div>

Si aún no ha creado los recursos de monitorización, hágalo ahora en el portal de Azure:

1. **Azure Monitor Workspace**: Portal → "Azure Monitor workspaces" → Create. Use el mismo grupo de recursos y la misma región que su clúster de AKS. Convención de nomenclatura: `amw-<cluster-name>`.
2. **Azure Managed Grafana**: Portal → "Azure Managed Grafana" → Create. Use el mismo grupo de recursos y la misma región. Vincúlelo al Azure Monitor Workspace durante la creación. Convención de nomenclatura: `amg-<cluster-name>`.
3. **Habilitar Prometheus en AKS**: Portal → clúster de AKS → Monitoring → Monitor Settings → habilite "Metrics via managed Prometheus" y seleccione el Azure Monitor Workspace y la instancia de Grafana.

Verifique que los pods de `ama-metrics` estén en ejecución:

```bash theme={null}
kubectl get pods -n kube-system | grep ama-metrics
```

<div id="step-2-create-the-observability-namespace-with-istio-injection">
  ## Paso 2: Cree el espacio de nombres de observabilidad con la inyección de Istio
</div>

> **Nota:** Puede usar cualquier nombre de espacio de nombres, pero algunas funciones opcionales de Vantage (como la compatibilidad con KEDA) dependen de que los servicios de Prometheus estén en el espacio de nombres `observability`, por lo que se recomienda usar `observability`.

```bash theme={null}
kubectl create namespace observability
```

Compruebe la etiqueta de revisión de Istio que usan otros espacios de nombres incluidos en la malla:

```bash theme={null}
# reemplaza con tu namespace si es necesario
kubectl get namespace app -o jsonpath='{.metadata.labels}' | grep istio
```

Aplica la misma etiqueta al espacio de nombres `observability`:

```bash theme={null}
kubectl label namespace observability istio.io/rev=<revision>
```

<div id="step-3-gather-azure-monitor-workspace-ingestion-details">
  ## Paso 3: Recopilar los detalles de ingesta de Azure Monitor Workspace
</div>

Obtenga los ID de recurso de la regla de recopilación de datos y del endpoint:

```bash theme={null}
az monitor account show \
  --name <monitor-workspace-name> \
  --resource-group <resource-group> \
  --query "defaultIngestionSettings"
```

Obtén la URL del endpoint de ingesta de métricas:

```bash theme={null}
az monitor data-collection endpoint show \
  --name <monitor-workspace-name> \
  --resource-group <managed-resource-group> \
  --query "metricsIngestion.endpoint"
```

Obtén el ID inmutable del DCR:

```bash theme={null}
az monitor data-collection rule show \
  --name <monitor-workspace-name> \
  --resource-group <managed-resource-group> \
  --query "immutableId"
```

<Note>
  El grupo de recursos administrado sigue el patrón `MA_<monitor-workspace-name>_<region>_managed`.
</Note>

Construya la URL completa de remote-write (la usará en el Step 5):

```text theme={null}
https://<endpoint>/dataCollectionRules/<dcr-immutable-id>/streams/Microsoft-PrometheusMetrics/api/v1/write?api-version=2023-04-24
```

<div id="step-4-create-a-managed-identity-for-prometheus">
  ## Step 4: Crear una identidad administrada para Prometheus
</div>

Cree una identidad administrada asignada por el usuario:

```bash theme={null}
az identity create \
  --name <cluster-name>-prometheus \
  --resource-group <resource-group> \
  --location <region>
```

Anota `clientId` y `principalId` que aparecen en la salida.

Asigna el rol `Monitoring Metrics Publisher` en la regla de recopilación de datos:

```bash theme={null}
az role assignment create \
  --role "Monitoring Metrics Publisher" \
  --assignee-object-id <principalId> \
  --assignee-principal-type ServicePrincipal \
  --scope "<dataCollectionRuleResourceId>"
```

Obtenga la URL del emisor de OIDC:

```bash theme={null}
az aks show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "oidcIssuerProfile.issuerUrl" -o tsv
```

Cree una credencial federada que asocie la identidad administrada con la cuenta de servicio de Prometheus:

```bash theme={null}
az identity federated-credential create \
  --name prometheus-federated \
  --identity-name <cluster-name>-prometheus \
  --resource-group <resource-group> \
  --issuer "<oidc-issuer-url>" \
  --subject "system:serviceaccount:observability:prometheus" \
  --audiences "api://AzureADTokenExchange"
```

<div id="step-5-install-the-prometheus-operator">
  ## Paso 5: Instalar Prometheus Operator
</div>

El agente `ama-metrics` instala los CRD de Prometheus, pero no ejecuta ningún operador que reconcilie los recursos personalizados de Prometheus. Instale únicamente el operador; deshabilite todo lo demás:

```bash theme={null}
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm install prometheus-operator prometheus-community/kube-prometheus-stack \
  --namespace observability \
  --set prometheus.enabled=false \
  --set alertmanager.enabled=false \
  --set grafana.enabled=false \
  --set defaultRules.create=false \
  --set nodeExporter.enabled=false \
  --set kubeStateMetrics.enabled=false
```

<div id="step-6-apply-the-prometheus-manifests">
  ## Step 6: Aplicar los manifiestos de Prometheus
</div>

Se requieren tres manifiestos (cuenta de servicio, RBAC y la instancia de Prometheus). Aplíquelos en el orden indicado. El `ServiceMonitor` de Vantage se crea por separado mediante el chart `vantage-selfhosted` (consulte más abajo).

**`service-account.yaml`**: Cuenta de servicio de Prometheus con anotación de identidad de carga de trabajo:

```yaml theme={null}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: prometheus
  namespace: observability
  annotations:
    azure.workload.identity/client-id: "<managed-identity-clientId>"
  labels:
    azure.workload.identity/use: "true"
```

**`rbac.yaml`**: `ClusterRole` y vinculación para el descubrimiento de objetivos:

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus
rules:
  - apiGroups: [""]
    resources: [nodes, nodes/metrics, services, endpoints, pods]
    verbs: [get, list, watch]
  - apiGroups: ["networking.k8s.io"]
    resources: [ingresses]
    verbs: [get, list, watch]
  - nonResourceURLs: ["/metrics", "/metrics/cadvisor"]
    verbs: [get]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: prometheus
subjects:
  - kind: ServiceAccount
    name: prometheus
    namespace: observability
```

**`prometheus.yaml`**: instancia de Prometheus con inyección del sidecar de Istio, exportación de certificados y remote-write a Azure Monitor:

```yaml theme={null}
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: metrics
  namespace: observability
spec:
  replicas: 1
  scrapeInterval: 60s
  logLevel: debug
  serviceAccountName: prometheus
  podMetadata:
    annotations:
      proxy.istio.io/config: |
        proxyMetadata:
          OUTPUT_CERTS: /etc/istio-output-certs
      sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-output-certs"}]'
    labels:
      sidecar.istio.io/inject: "true"
      azure.workload.identity/use: "true"
  volumes:
    - name: istio-certs
      emptyDir:
        medium: Memory
  volumeMounts:
    - name: istio-certs
      mountPath: /etc/prom-certs/
      readOnly: true
  resources:
    requests:
      memory: 3Gi
      cpu: 600m
    limits:
      memory: 6Gi
      cpu: 1000m
  serviceMonitorNamespaceSelector: {}
  serviceMonitorSelector: {}
  remoteWrite:
    - url: "<remote-write-url>"
      azureAd:
        cloud: AzurePublic
        sdk:
          tenantId: "<azure-tenant-id>"
  replicaExternalLabelName: "__replica__"
  externalLabels:
    cluster: "<cluster-name>"
```

<Note>
  El método de autenticación `azureAd.sdk` usa `DefaultAzureCredential`, que toma el token de identidad de carga de trabajo inyectado por la etiqueta `azure.workload.identity/use: "true"`. Requiere Prometheus v3.60+.
</Note>

Aplica las tres:

```bash theme={null}
kubectl apply -f service-account.yaml
kubectl apply -f rbac.yaml
kubectl apply -f prometheus.yaml
```

<div id="configure-the-vantage-servicemonitor">
  ### Configurar el `ServiceMonitor` de Vantage
</div>

El `ServiceMonitor` de Vantage se crea mediante el chart de Helm `vantage-selfhosted`, en lugar de aplicarlo manualmente. Instale o actualice el chart con un archivo de valores que configure el `ServiceMonitor` para recopilar métricas de Vantage a través de Istio mTLS mediante los certificados que exporta Prometheus en la malla:

```yaml theme={null}
# values.vantage-selfhosted.yaml
observability:
  prometheus:
    serviceMonitor:
      scheme: https
      tlsConfig:
        caFile: /etc/prom-certs/root-cert.pem
        certFile: /etc/prom-certs/cert-chain.pem
        keyFile: /etc/prom-certs/key.pem
        insecureSkipVerify: true  # Prometheus no admite la nomenclatura de seguridad de Istio, por lo que se omite la verificación del certificado del pod de destino
      relabelings:
        - action: replace
          sourceLabels: [__meta_kubernetes_service_name]
          targetLabel: service_name
      metricRelabelings:
        - action: replace
          sourceLabels: [__meta_kubernetes_service_name]
          targetLabel: app_service
```

Para obtener una explicación completa de la configuración de los certificados mTLS de Istio en la que se basan estas rutas, consulte [Supervisión con Prometheus](/es/vantage/self-hosted/v3.0/monitoring/prometheus#istio-mtls).

<div id="step-7-verify">
  ## Step 7: Verifique
</div>

Compruebe que el pod de Prometheus esté ejecutándose con tres contenedores (`prometheus`, `config-reloader`, `istio-proxy`):

```bash theme={null}
kubectl get pods -n observability
```

Haz un reenvío de puertos para inspeccionar los objetivos de scrape:

```bash theme={null}
kubectl port-forward -n observability prometheus-metrics-0 9090:9090
```

Abra `http://localhost:9090/targets`. Los targets deberían aparecer como **UP**, con scraping a través de `https` en `/metrics-text:8080`.

Revise los logs de remote-write para detectar errores:

```bash theme={null}
kubectl logs -n observability prometheus-metrics-0 -c prometheus | grep -i "remote" | tail -10
```

Si `remote-write` se realiza correctamente, muestra "Done replaying WAL" sin errores de autenticación.

En Managed Grafana, consulta `up{cluster="<cluster-name>"}` en la vista Explore con el origen de datos de Managed Prometheus para confirmar que se están recibiendo métricas.

<div id="operational-notes">
  ## Notas operativas
</div>

* El agente `ama-metrics` sigue ocupándose de las métricas de infraestructura de Kubernetes (kubelet, cadvisor, kube-state-metrics, node-exporter). **No** lo deshabilite.
* Prometheus en la malla solo gestiona las métricas de la aplicación Vantage. Ambos escriben en el mismo Azure Monitor Workspace.
* La autenticación `remote-write` de `azureAd.sdk` usa `DefaultAzureCredential`, que obtiene el token de identidad de carga de trabajo proyectado en el pod por el webhook de identidad de carga de trabajo de AKS. Esto requiere la anotación `azure.workload.identity/client-id` en la cuenta de servicio y la etiqueta `azure.workload.identity/use: "true"` en el pod.
* La configuración `azureAd.managedIdentity` **no** funciona en este caso de uso: llama al endpoint IMDS del nodo, y la identidad asignada por el usuario no está asignada al pool de nodos de VMSS.
* Los destinos `UNKNOWN` en la vista de destinos de Prometheus suelen corresponder a pods en estado Degraded o CrashLooping, no a un problema de scraping.
* `logLevel: debug` en el CRD de Prometheus puede cambiarse a `info` una vez verificada la configuración.