Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Implementa OTel Container Insights con Helm
<a name="container-insights-eks-otel-helm"></a>

Il grafico Amazon CloudWatch Observability Helm offre un'opzione di implementazione flessibile per Otel Container Insights. Installa l' CloudWatch agent (OTel-based) con il ricevitore OpenTelemetry filelog per la raccolta dei log. Il diagramma di Helm viene mantenuto in. [https://github.com/aws-observability/helm-charts](https://github.com/aws-observability/helm-charts)

Usa il diagramma di Helm quando hai bisogno di una o più delle seguenti funzionalità:
+ Fine-grained controllo sulla configurazione dell'agente
+ OTel-native raccolta di log utilizzando il ricevitore filelog (nessuna dipendenza da Fluent Bit)
+ Gestione personalizzata dei certificati TLS tramite cert-manager
+ Non-EKS Cluster Kubernetes (ROSA, Kubernetes autogestito)
+ GitOps flussi di lavoro con ArgoCD o Flux

## Prerequisiti
<a name="container-insights-eks-otel-helm-prereqs"></a>

Prima di distribuire Otel Container Insights con Helm, verificate di soddisfare i seguenti requisiti.
+ Un cluster Amazon EKS esistente che esegue Kubernetes versione 1.28 o successiva
+ Helm versione 3.9 o successiva
+ `kubectl`configurato per comunicare con il cluster di destinazione
+ Autorizzazioni IAM: policy `CloudWatchAgentServerPolicy` gestita allegata al ruolo di agente
+ Un provider OpenID Connect (OIDC) configurato per IAM Roles for Service Accounts (IRSA)
+ Accesso a Internet in uscita dal cluster agli endpoint CloudWatch 

## Installa il diagramma Helm
<a name="container-insights-eks-otel-helm-setup"></a>

Completa i seguenti passaggi per distribuire Otel Container Insights utilizzando il grafico Helm.

### Fase 1: Aggiungere il repository Helm
<a name="container-insights-eks-otel-helm-step1"></a>

Aggiungi il repository AWS cartografico Observability Helm alla configurazione Helm locale.

**Per aggiungere il repository Helm**

1. Esegui il comando seguente per aggiungere il repository.

   ```
   helm repo add aws-observability \
     https://aws-observability.github.io/helm-charts
   ```

1. Aggiorna il repository per ottenere le versioni più recenti dei grafici.

   ```
   helm repo update
   ```

### Passaggio 2: creare il ruolo IAM
<a name="container-insights-eks-otel-helm-step2"></a>

Crea un ruolo IAM che consenta all' CloudWatch agente di inviare dati a CloudWatch. Questo ruolo utilizza IRSA per associare le autorizzazioni IAM a un account di servizio Kubernetes.

**Per creare il ruolo IAM per l'agente CloudWatch**

1. Recupera l'URL dell'emittente OIDC per il tuo cluster. Sostituisci {{cluster-name}} con il nome del tuo cluster Amazon EKS.

   ```
   aws eks describe-cluster \
     --name {{cluster-name}} \
     --query "cluster.identity.oidc.issuer" \
     --output text
   ```

1. Crea il ruolo IAM con una policy di fiducia per IRSA. Sostituiscilo {{account-id}} con l'ID del tuo AWS account e {{oidc-id}} con l'ID del provider OIDC del passaggio precedente (la parte successiva). `https://oidc.eks.region.amazonaws.com/id/`

   ```
   aws iam create-role \
     --role-name EKS-CW-Observability-Role \
     --assume-role-policy-document '{
       "Version": "2012-10-17",
       "Statement": [{
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::{{account-id}}:oidc-provider/oidc.eks.{{region}}.amazonaws.com/id/{{oidc-id}}"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "oidc.eks.{{region}}.amazonaws.com/id/{{oidc-id}}:sub": "system:serviceaccount:amazon-cloudwatch:cloudwatch-agent"
           }
         }
       }]
     }'
   ```

1. Collegare la policy gestita `CloudWatchAgentServerPolicy` al ruolo.

   ```
   aws iam attach-role-policy \
     --role-name EKS-CW-Observability-Role \
     --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
   ```

### Fase 3: Installare il grafico
<a name="container-insights-eks-otel-helm-step3"></a>

Installa il grafico Amazon CloudWatch Observability Helm con OTel Container Insights abilitato.

**Per installare il grafico Helm**
+ Eseguire il seguente comando seguente. Sostituiscilo {{cluster-name}} con il nome del tuo cluster Amazon EKS, {{region}} con la tua AWS regione e {{account-id}} con l'ID AWS del tuo account.

  ```
  helm install amazon-cloudwatch-observability \
    aws-observability/amazon-cloudwatch-observability \
    --namespace amazon-cloudwatch \
    --create-namespace \
    --set clusterName={{cluster-name}} \
    --set region={{region}} \
    --set agent.serviceAccount.name=cloudwatch-agent \
    --set "agent.serviceAccount.annotations.eks\\.amazonaws\\.com/role-arn=arn:aws:iam::{{account-id}}:role/EKS-CW-Observability-Role" \
    --set otelContainerInsights.enabled=true
  ```
**Importante**  
Il parametro `otelContainerInsights.enabled` è obbligatorio. OTel Container Insights non è abilitato per impostazione predefinita.

### Fase 4: Verificare l'installazione
<a name="container-insights-eks-otel-helm-step4"></a>

Conferma che la release di Helm e gli agent pod siano stati distribuiti correttamente.

**Per verificare l'installazione di Helm**

1. Verifica che sia visualizzato lo stato di rilascio di Helm. `deployed`

   ```
   helm list -n amazon-cloudwatch
   ```

1. Conferma che il pod dell'operatore sia in funzione.

   ```
   kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=amazon-cloudwatch-observability
   ```

1. Verificate che i pod CloudWatch dell'agente siano in esecuzione su tutti i nodi.

   ```
   kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
   ```

   Tutti i pod degli agenti devono mostrare lo `Running` stato.

## Opzioni di configurazione principali
<a name="container-insights-eks-otel-helm-config"></a>

Le tabelle seguenti descrivono i valori chiave del grafico Helm che è possibile configurare. Passa questi valori utilizzando il `--set` flag o un `values.yaml` file personalizzato.

### Impostazioni del cluster
<a name="container-insights-eks-otel-helm-config-cluster"></a>


| Parametro | Predefinita | Description | 
| --- | --- | --- | 
| clusterName | — | Il nome del cluster Amazon EKS. Obbligatorio. | 
| region | — | La AWS regione in cui viene eseguito il cluster. Obbligatorio. | 
| otelContainerInsights.enabled | false | Abilita OTel Container Insights con il ricevitore filelog. | 

### Registri dei contenitori (ricevitore otEL filelog)
<a name="container-insights-eks-otel-helm-config-logs"></a>


| Parametro | Predefinita | Description | 
| --- | --- | --- | 
| containerLogs.enabled | true | Abilita la raccolta dei log del contenitore utilizzando il ricevitore Filelog Otel. | 
| containerLogs.logGroupName | /aws/containerinsights/{{cluster-name}}/application | Il nome del gruppo CloudWatch di log Logs per i log del contenitore. | 
| containerLogs.logRetentionDays | 7 | Il numero di giorni in cui conservare i log dei contenitori nei registri. CloudWatch  | 

### Agente (metriche)
<a name="container-insights-eks-otel-helm-config-agent"></a>


| Parametro | Predefinita | Description | 
| --- | --- | --- | 
| agent.enabled | true | Abilita l' CloudWatch agente DaemonSet per la raccolta delle metriche. | 
| agent.serviceAccount.name | cloudwatch-agent | Il nome dell'account del servizio Kubernetes per l'agente. | 
| agent.resources.requests.cpu | 100m | La richiesta CPU per il contenitore dell'agente. | 
| agent.resources.requests.memory | 128Mi | La richiesta di memoria per il contenitore dell'agente. | 
| agent.resources.limits.cpu | 200m | Il limite di CPU per il contenitore dell'agente. | 
| agent.resources.limits.memory | 256Mi | Il limite di memoria per il contenitore dell'agente. | 

### Monitoraggio della GPU
<a name="container-insights-eks-otel-helm-config-gpu"></a>


| Parametro | Predefinita | Description | 
| --- | --- | --- | 
| agent.config.logs.metrics\_collected.kubernetes.enhanced\_container\_insights | true | Abilita le metriche di Enhanced Container Insights, incluse le metriche GPU. | 
| dcgmExporter.enabled | false | Abilita l'esportatore DCGM per le metriche della GPU NVIDIA. Richiede nodi GPU NVIDIA. | 
| neuronMonitor.enabled | false | Abilita il monitor Neuron per le metriche AWS Inferentia e Trainium. | 

## Gestione dei certificati TLS
<a name="container-insights-eks-otel-helm-tls"></a>

L'operatore CloudWatch Observability richiede certificati TLS per la comunicazione tramite webhook. Per impostazione predefinita, il grafico genera certificati autofirmati. È possibile utilizzare cert-manager per gestire automaticamente i certificati.

### Self-signed certificati (impostazione predefinita)
<a name="container-insights-eks-otel-helm-tls-default"></a>

Per impostazione predefinita, il grafico Helm genera una CA autofirmata e ne emette i certificati. e non sono necessarie ulteriori configurazioni. Il grafico ruota automaticamente questi certificati durante gli aggiornamenti.

### integrazione cert-manager
<a name="container-insights-eks-otel-helm-tls-certmanager"></a>

È possibile utilizzare cert-manager per automatizzare l'emissione e il rinnovo dei certificati. Questo approccio è utile quando l'organizzazione richiede certificati firmati esternamente o una gestione centralizzata dei certificati.

**Per configurare l'integrazione con cert-manager**

1. Verifica che cert-manager sia installato nel tuo cluster.

   ```
   kubectl get pods -n cert-manager
   ```

1. Installa il grafico Helm con cert-manager abilitato. Sostituiscilo {{cluster-name}} con il nome del tuo cluster Amazon EKS, {{region}} con la tua AWS regione e {{account-id}} con l'ID AWS del tuo account.

   ```
   helm install amazon-cloudwatch-observability \
     aws-observability/amazon-cloudwatch-observability \
     --namespace amazon-cloudwatch \
     --create-namespace \
     --set clusterName={{cluster-name}} \
     --set region={{region}} \
     --set agent.serviceAccount.name=cloudwatch-agent \
     --set "agent.serviceAccount.annotations.eks\\.amazonaws\\.com/role-arn=arn:aws:iam::{{account-id}}:role/EKS-CW-Observability-Role" \
     --set otelContainerInsights.enabled=true \
     --set admissionWebhooks.certManager.enabled=true
   ```

Quando cert-manager è abilitato, il grafico crea una `Certificate` risorsa che cert-manager utilizza per emettere e gestire automaticamente il certificato TLS webhook.

**Nota**  
Puoi anche usare cert-manager con emittenti esterni come Vault. HashiCorp Per configurare un emittente esterno, imposta `admissionWebhooks.certManager.issuerRef.name` e abbina l'emittente del tuo `admissionWebhooks.certManager.issuerRef.kind` cert-manager.

## Aggiorna il grafico
<a name="container-insights-eks-otel-helm-upgrade"></a>

Aggiorna il grafico Helm per applicare nuovi valori di configurazione o per eseguire l'aggiornamento a una versione più recente del grafico.

**Per aggiornare il diagramma di Helm**

1. Aggiorna il repository Helm per ottenere le versioni più recenti dei grafici.

   ```
   helm repo update
   ```

1. Esegui il comando di aggiornamento con i valori desiderati. Sostituiscilo {{cluster-name}} con il nome del tuo cluster Amazon EKS, {{region}} con la tua AWS regione e {{account-id}} con l'ID AWS del tuo account.

   ```
   helm upgrade amazon-cloudwatch-observability \
     aws-observability/amazon-cloudwatch-observability \
     --namespace amazon-cloudwatch \
     --set clusterName={{cluster-name}} \
     --set region={{region}} \
     --set agent.serviceAccount.name=cloudwatch-agent \
     --set "agent.serviceAccount.annotations.eks\\.amazonaws\\.com/role-arn=arn:aws:iam::{{account-id}}:role/EKS-CW-Observability-Role" \
     --set otelContainerInsights.enabled=true
   ```

1. Verifica che l'aggiornamento sia stato completato correttamente.

   ```
   helm list -n amazon-cloudwatch
   ```

   Il numero di revisione deve aumentare e lo stato deve essere visualizzato. `deployed`

**Suggerimento**  
Per evitare di perdere i valori di configurazione durante gli aggiornamenti, memorizzate i valori personalizzati in un `values.yaml` file e passatelo con il flag. `-f values.yaml`

## Disinstalla il grafico
<a name="container-insights-eks-otel-helm-uninstall"></a>

Per rimuovere Otel Container Insights dal cluster, disinstalla la versione Helm.

**Per disinstallare il grafico Helm**

1. Esegui il comando seguente per disinstallare la versione.

   ```
   helm uninstall amazon-cloudwatch-observability \
     --namespace amazon-cloudwatch
   ```

1. Facoltativamente, elimina lo spazio dei nomi se non è più necessario.

   ```
   kubectl delete namespace amazon-cloudwatch
   ```

Dopo aver disinstallato il grafico Helm, il ruolo IAM e la configurazione del provider OIDC rimangono nell'account. AWS Elimina queste risorse separatamente se non sono più necessarie.

```
aws iam detach-role-policy \
  --role-name EKS-CW-Observability-Role \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

aws iam delete-role \
  --role-name EKS-CW-Observability-Role
```

## Verifica i dati in CloudWatch
<a name="container-insights-eks-otel-helm-verify"></a>

Dopo aver installato il grafico Helm, i dati di Container Insights vengono visualizzati CloudWatch entro 3-5 minuti.

### Controlla le metriche
<a name="container-insights-eks-otel-helm-verify-metrics"></a>

**Per controllare le metriche in CloudWatch**

1. Apri la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. Nel riquadro di navigazione, scegli **Container Insights**.

1. Verifica che il cluster compaia nell'elenco dei cluster e che i parametri dell'infrastruttura siano compilati.

### Controlla i log di
<a name="container-insights-eks-otel-helm-verify-logs"></a>

Per verificare l'esistenza di gruppi di log per il cluster, esegui il comando seguente. Sostituisci {{cluster-name}} con il nome del tuo cluster Amazon EKS.

```
aws logs describe-log-groups \
  --log-group-name-prefix "/aws/containerinsights/{{cluster-name}}" \
  --query "logGroups[].logGroupName" \
  --output table
```

## Risoluzione dei problemi
<a name="container-insights-eks-otel-helm-troubleshoot"></a>

Utilizza le seguenti linee guida per risolvere i problemi più comuni durante la distribuzione di Otel Container Insights con Helm.

### Pod in operatore CrashLoopBackOff
<a name="container-insights-eks-otel-helm-ts-operator-crash"></a>

**Sintomo:** quando corri`kubectl get pods -n amazon-cloudwatch`, il pod operatore mostra `CrashLoopBackOff` lo stato.

**Causa:** il pod dell'operatore non può essere avviato a causa di problemi con il certificato TLS o di autorizzazioni insufficienti.

**Soluzione:** completa i seguenti passaggi per risolvere il problema.

1. Controlla i log del pod dell'operatore per verificare la presenza di errori relativi ai certificati.

   ```
   kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=amazon-cloudwatch-observability --tail=50
   ```

1. Verifica che il segreto TLS del webhook esista nello spazio dei nomi.

   ```
   kubectl get secrets -n amazon-cloudwatch | grep webhook
   ```

1. Se usi cert-manager, verifica che lo stato della risorsa sia visualizzato. `Certificate` `Ready`

   ```
   kubectl get certificate -n amazon-cloudwatch
   ```

1. Se il certificato è mancante o non valido, disinstalla e reinstalla il grafico per rigenerare i certificati.

   ```
   helm uninstall amazon-cloudwatch-observability -n amazon-cloudwatch
   ```

### I pod degli agenti non sono pianificati su tutti i nodi
<a name="container-insights-eks-otel-helm-ts-agent-scheduling"></a>

**Sintomo:** l'agente DaemonSet mostra un numero di pod inferiore al numero di nodi del cluster.

**Causa: problemi** di nodo, vincoli di risorse o selettori di nodi impediscono la pianificazione dei pod degli agenti su determinati nodi.

**Soluzione:** completare i seguenti passaggi per risolvere il problema.

1. Verifica lo DaemonSet stato dei problemi di pianificazione.

   ```
   kubectl get daemonset -n amazon-cloudwatch cloudwatch-agent
   ```

1. Verifica la presenza di pod non programmabili e visualizza i relativi eventi.

   ```
   kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --field-selector=status.phase!=Running
   ```

1. Se i nodi presentano macchie, aggiungi delle tolleranze ai valori del grafico Helm. Ad esempio, per tollerare tutte le macchie, aggiorna il grafico con il seguente flag.

   ```
   helm upgrade amazon-cloudwatch-observability \
     aws-observability/amazon-cloudwatch-observability \
     --namespace amazon-cloudwatch \
     --reuse-values \
     --set "agent.tolerations[0].operator=Exists"
   ```

1. Verificate che i pod dell'agente ora funzionino su tutti i nodi.

   ```
   kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent -o wide
   ```