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à.

# Nozioni di base su AWS DevOps Agente che utilizza Terraform
<a name="getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-terraform"></a>

## Panoramica di
<a name="overview"></a>

Questa guida mostra come utilizzare Terraform per creare e distribuire AWS DevOps risorse Agent. La configurazione Terraform automatizza la creazione di uno spazio per agenti, ruoli IAM, un'app operatore e associazioni di account. AWS 

L'approccio Terraform automatizza i passaggi manuali descritti nella [guida all'onboarding della CLI](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html) definendo tutte le risorse richieste come infrastruttura come codice.

AWS DevOps L'agente è disponibile nelle seguenti 6 AWS regioni: Stati Uniti orientali (Virginia settentrionale), Stati Uniti occidentali (Oregon), Asia Pacifico (Sydney), Asia Pacifico (Tokyo), Europa (Francoforte) ed Europa (Irlanda). Per ulteriori informazioni sulle regioni supportate, consulta. [Regioni supportate](about-aws-devops-agent-supported-regions.md)

## Prerequisiti
<a name="prerequisites"></a>

Prima di iniziare, assicurati di disporre di:
+ Terraform >= 1.0 installato
+ AWS CLI installata e configurata con credenziali appropriate
+ Un AWS account per l'account di monitoraggio (primario)
+ (Facoltativo) Un secondo AWS account se desideri configurare il monitoraggio tra più account

## Cosa tratta questa guida
<a name="what-this-guide-covers"></a>

Questa guida è divisa in tre parti:
+ **Parte 1**: implementa uno spazio per agenti con un'app per operatori e un' AWS associazione nel tuo account di monitoraggio. Dopo aver completato questa parte, l'agente può monitorare i problemi di quell'account.
+ **Parte 2 (facoltativa)**: aggiungi un' AWS associazione di origine per un account di servizio e distribuisci un ruolo IAM tra account più un echo Lambda in quell'account. Ciò consente allo spazio dell'agente di monitorare le risorse tra gli account.
+ **Parte 3 (opzionale)**: registra i servizi di terze parti (Dynatrace, ServiceNow, Splunk, New Relic GitLab, PagerDuty) e li associa allo spazio degli agenti.

## Risorse create
<a name="resources-created"></a>

### Parte 1: Monitoraggio dell'account
<a name="part-1-monitoring-account"></a>
+ **Ruolo IAM** (`DevOpsAgentRole-AgentSpace-*`): assunto dal servizio DevOps Agent per monitorare l'account. Include la policy `AIDevOpsAgentAccessPolicy` gestita e una policy in linea che consente la creazione del ruolo collegato al servizio Resource Explorer. Creato solo quando non `existing_agentspace_role_arn` è impostato.
+ **IAM role** (`DevOpsAgentRole-WebappAdmin-*`) — Ruolo dell'app Operator con policy `AIDevOpsOperatorAppAccessPolicy` gestita per le operazioni degli agenti. Creato solo quando non `existing_operator_role_arn` è impostato.
+ **Spazio agente** (nome configurabile): lo spazio centrale dell'agente, creato utilizzando la `awscc_devopsagent_agent_space` risorsa. Include la configurazione dell'app per l'operatore.
+ **Associazione** (AWS monitor): collega l'account di monitoraggio allo spazio dell'agente utilizzando la `awscc_devopsagent_association` risorsa.
+ **Associazione** (AWS fonte): (Facoltativo) Collega l'account di servizio allo spazio dell'agente per il monitoraggio tra account.

### Parte 2: Account di servizio (opzionale)
<a name="part-2-service-account-optional"></a>
+ **IAM role** (`DevOpsAgentRole-SecondaryAccount-TF`) — Cross-account ruolo con un nome fisso. Scelto dallo spazio degli agenti nell'account di monitoraggio. Include la policy `AIDevOpsAgentAccessPolicy` gestita e una policy in linea che consente la creazione del ruolo collegato al servizio Resource Explorer.
+ **Funzione Lambda** (`echo-service-tf`): un semplice servizio di esempio che riproduce gli eventi di input di ritorno.

## Configurazione
<a name="setup"></a>

### Fase 1: clonare il repository di esempio
<a name="step-1-clone-the-sample-repository"></a>

```
git clone https://github.com/aws-samples/sample-aws-devops-agent-terraform.git
cd sample-aws-devops-agent-terraform
```

### Fase 2: Configurare le variabili
<a name="step-2-configure-variables"></a>

Copia il file delle variabili di esempio e personalizzalo per il tuo ambiente:

```
cp terraform.tfvars.example terraform.tfvars
```

Modifica `terraform.tfvars` con il nome e la descrizione dello spazio dell'agente:

```
agent_space_name        = "MyCompanyAgentSpace"
agent_space_description = "DevOps Agent Space for monitoring production workloads"
```

## Parte 1: Implementa lo spazio degli agenti
<a name="part-1-deploy-the-agent-space"></a>

In questa sezione, crei lo spazio degli agenti, i ruoli IAM, l'app operatore e un' AWS associazione nel tuo account di monitoraggio.

### Fase 1: Implementazione con automazione (consigliata)
<a name="step-1-deploy-with-automation-recommended"></a>

Utilizza lo script di distribuzione fornito per una configurazione semplificata:

```
./deploy.sh
```

Questo script automaticamente:
+ Verifica i prerequisiti (Terraform, AWS CLI, credenziali)
+ Crea `terraform.tfvars` dall'esempio se necessario
+ Inizializza, convalida, pianifica e applica Terraform

In alternativa, se preferisci il controllo manuale:

```
terraform init
terraform plan
terraform apply
```

Digita `yes` quando richiesto per confermare la distribuzione.

### Fase 2: Registrare le uscite
<a name="step-2-record-the-outputs"></a>

Al termine della distribuzione, Terraform stampa gli output. Registra questi valori per un uso successivo:

```
Outputs:
agent_space_id              = "abc123"
agent_space_arn             = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/abc123"
agent_space_name            = "MyCompanyAgentSpace"
devops_agentspace_role_arn  = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace-a1b2c3d4"
devops_operator_role_arn    = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin-a1b2c3d4"
primary_account_id          = "<MONITORING_ACCOUNT_ID>"
primary_account_association_id = "assoc-xyz"
```

Se intendi completare la Parte 2, salva il `agent_space_arn` valore. Ti servirà per configurare le risorse dell'account di servizio.

### Fase 3: Verificare la distribuzione
<a name="step-3-verify-the-deployment"></a>

Esegui lo script di verifica post-implementazione:

```
./post-deploy.sh
```

Oppure usa la AWS CLI per verificare che lo spazio dell'agente sia stato creato correttamente:

```
aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>
```

A questo punto, lo spazio per gli agenti viene distribuito con l'app dell'operatore abilitata e l'account di monitoraggio associato. L'agente può monitorare i problemi relativi a questo account.

## Parte 2 (facoltativa): aggiungi il monitoraggio tra account
<a name="part-2-optional-add-cross-account-monitoring"></a>

In questa sezione, estendete la configurazione in modo che lo spazio dell'agente possa monitorare le risorse in un secondo AWS account (l'account di servizio). Ciò comporta due azioni:

1. Aggiungere un' AWS associazione di origine che punti all'account del servizio.

1. Implementazione di un ruolo IAM su più account e di una funzione echo Lambda nell'account del servizio.

**Importante**  
**È necessario completare la parte 1 prima di procedere. Le risorse dell'account di servizio richiedono l'output `agent_space_arn` di distribuzione della Parte 1.

### Fase 1: Configurare l'ID dell'account di servizio
<a name="step-1-configure-the-service-account-id"></a>

In`terraform.tfvars`, imposta l'ID del tuo account di servizio:

```
service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"
```

### Fase 2: Impostare lo spazio dell'agente (ARN)
<a name="step-2-set-the-agent-space-arn"></a>

Copiate il `agent_space_arn` valore dall'output della Parte 1 (Fase 2) e impostatelo in`terraform.tfvars`:

```
agent_space_arn = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>"
```

Le risorse dell'account di servizio utilizzano questo valore per definire la politica di fiducia relativa al ruolo secondario dell'account. Queste risorse vengono create solo quando questo valore è impostato.

### Fase 3: Configurare il provider `aws.service`
<a name="step-3-configure-the-awsservice-provider"></a>

In`main.tf`, configura l'alias del `aws.service` provider con le credenziali per l'account di servizio. Puoi utilizzare un profilo denominato o assumere un ruolo:

Utilizzando un profilo:

```
provider "aws" {
  alias   = "service"
  region  = var.aws_region
  profile = "your-service-account-profile"
}
```

O usando assume il ruolo:

```
provider "aws" {
  alias  = "service"
  region = var.aws_region
  assume_role {
    role_arn = "arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/OrganizationAccountAccessRole"
  }
}
```

### Fase 4: Implementazione
<a name="step-4-deploy"></a>

Applica la configurazione aggiornata:

```
terraform apply
```

In questo modo vengono create le seguenti risorse nell'account del servizio:
+ Un ruolo IAM (`DevOpsAgentRole-SecondaryAccount-TF`) che affida lo spazio dell'agente nell'account di monitoraggio
+ Una funzione echo Lambda `echo-service-tf` () come servizio di esempio

Crea inoltre un' AWS associazione di origine nell'account di monitoraggio che collega l'account di servizio.

### Fase 5: Verificare la distribuzione
<a name="step-5-verify-the-deployment"></a>

Prova il servizio echo per confermare che la funzione Lambda è stata implementata correttamente:

```
aws lambda invoke \
  --function-name echo-service-tf \
  --payload '{"test": "hello world"}' \
  --profile <your-service-account-profile> \
  --region <REGION> \
  response.json
cat response.json
```

## Parte 3 (opzionale): registrazione delle integrazioni di terze parti
<a name="part-3-optional-register-third-party-integrations"></a>

In questa sezione, registri i servizi esterni (Dynatrace,, Splunk ServiceNow, New Relic, GitLab, PagerDuty) con lo spazio degli agenti. Queste integrazioni consentono all' AWS DevOps Agent di accedere alla telemetria, ai dati sugli incidenti e alle informazioni sul controllo del codice sorgente durante le indagini.

A differenza dell'esempio AWS CDK, che richiede una IntegrationsStack fase separata e il cablaggio manuale dell'ID dello spazio agente, queste risorse fanno riferimento direttamente allo spazio degli agenti e possono essere implementate come nella Parte 1. `terraform apply`

### Integrazioni supportate
<a name="supported-integrations"></a>


| Servizio | Tipo di servizio | Autenticazione | 
| --- | --- | --- | 
| Dynatrace | dynatrace | Credenziali del client OAuth | 
| ServiceNow | servicenow | Credenziali del client OAuth | 
| Splunk | mcpserversplunk | Token Bearer | 
| New Relic | mcpservernewrelic | Chiave API | 
| GitLab | gitlab | Token di accesso | 
| PagerDuty | pagerduty | Credenziali del client OAuth | 

**Nota**  
**Datadog non è incluso nella configurazione Terraform. La connessione a Datadog richiede l'autorizzazione OAuth interattiva dell'utente (accesso e consenso del browser) come descritto in, che Terraform non può automatizzare. [Connessione DataDog](connecting-telemetry-sources-connecting-datadog.md) Registra Datadog manualmente tramite la pagina Capability Provider nella console.

### Fase 1: Configurare le credenziali di integrazione
<a name="step-1-configure-integration-credentials"></a>

Aggiungi un `integrations` blocco a`terraform.tfvars`, compilando solo i servizi che desideri. L'esempio seguente mostra un'integrazione con Dynatrace:

```
integrations = {
  dynatrace = {
    account_urn   = "<DYNATRACE_ACCOUNT_URN>"
    client_id     = "<DYNATRACE_CLIENT_ID>"
    client_name   = "<DYNATRACE_CLIENT_NAME>"
    client_secret = "<DYNATRACE_CLIENT_SECRET>"
    env_id        = "<DYNATRACE_ENVIRONMENT_ID>"
    resources     = ["<DYNATRACE_RESOURCE_1>"]
  }
}
```

Per la forma completa di ogni integrazione, vedi `terraform.tfvars.example` nel repository di esempio.

**ServiceNow requisito:** imposta sempre in `instance_id` modo esplicito il nome breve dell'istanza (ad esempio, `"ven04972"` non quello completo`instance_url`). Se `instance_id` viene omessa, l'associazione ritorna a`instance_url`, cosa che l'API dell' DevOps agente rifiuta con un. `400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance`

**Sicurezza:** la `integrations` variabile è contrassegnata`sensitive`, quindi i suoi valori vengono eliminati dal piano e applicati all'output. Non inserire credenziali reali in. `terraform.tfvars` Per la produzione, i segreti dei sorgenti provengono da AWS Secrets Manager o AWS Systems Manager Parameter Store (ad esempio, utilizzando i `data` sorgenti) anziché il testo semplice.

### Fase 2: Implementazione
<a name="step-2-deploy"></a>

Applica la configurazione:

```
terraform apply
```

Questo crea una registrazione e un'associazione del servizio per ogni integrazione abilitata.

### Fase 3: Esamina gli output
<a name="step-3-review-the-outputs"></a>

Una volta completata la distribuzione, gli output di integrazione mappano ogni servizio abilitato ai relativi ID registrati:

```
integration_service_ids = {
  "dynatrace" = "service-abc123"
}
integration_association_ids = {
  "dynatrace" = "assoc-xyz789"
}
```

Per ulteriori informazioni sulla configurazione delle credenziali per ogni servizio, consulta:
+ [Connessione di Dynatrace](connecting-telemetry-sources-connecting-dynatrace.md)
+ [Connessione ServiceNow](connecting-to-ticketing-and-chat-connecting-servicenow.md)
+ [Connessione a Splunk](connecting-telemetry-sources-connecting-splunk.md)
+ [Collegamento di New Relic](connecting-telemetry-sources-connecting-new-relic.md)
+ [Connessione GitLab](connecting-to-cicd-pipelines-connecting-gitlab.md)
+ [Connessione PagerDuty](connecting-to-ticketing-and-chat-connecting-pagerduty.md)

## Utilizzo dei ruoli IAM esistenti (facoltativo)
<a name="using-existing-iam-roles-optional"></a>

Per impostazione predefinita, la configurazione Terraform crea nuovi ruoli IAM per lo spazio degli agenti e l'app dell'operatore. Se disponi già di ruoli IAM con le policy richieste, puoi saltare la creazione di ruoli e fornire invece gli ARN dei ruoli esistenti.

### Requisiti
<a name="requirements"></a>

I ruoli esistenti devono soddisfare i seguenti requisiti:

#### Ruolo spaziale dell'agente
<a name="agent-space-role"></a>
+ La politica di fiducia `aidevops.amazonaws.com` consente di assumere il ruolo con `sts:AssumeRole`
+ Ha la politica `AIDevOpsAgentAccessPolicy` gestita allegata
+ (Facoltativo) Dispone di una politica in linea che consente la creazione del ruolo collegato al servizio Resource Explorer

#### Ruolo dell'app Operator
<a name="operator-app-role"></a>
+ La politica di fiducia `aidevops.amazonaws.com` consente di assumere il ruolo con `sts:AssumeRole` e `sts:TagSession`
+ Ha la politica `AIDevOpsOperatorAppAccessPolicy` gestita allegata

### Configurazione
<a name="configuration"></a>

In`terraform.tfvars`, imposta uno o entrambi gli ARN di ruolo:

```
existing_agentspace_role_arn = "arn:aws:iam::ACCOUNT_ID:role/YourAgentSpaceRole"
existing_operator_role_arn   = "arn:aws:iam::ACCOUNT_ID:role/YourOperatorRole"
```

Quando questi valori sono impostati, le risorse di ruolo corrispondenti in cui sono `iam.tf` inserite vengono ignorate. Questo approccio è completamente compatibile con le versioni precedenti: le configurazioni esistenti con valori vuoti (impostazione predefinita) mantengono l'attuale comportamento di creazione dei ruoli.

## Risoluzione dei problemi
<a name="troubleshooting"></a>

**Ritardi di propagazione IAM**
+ La configurazione include 30 secondi `time_sleep` tra la creazione del ruolo IAM e la creazione di Agent Space. Il servizio DevOps Agent convalida la politica di fiducia del ruolo dell'operatore durante la creazione di Agent Space, e questa operazione può fallire se IAM non viene propagato completamente. Se continui a riscontrare errori nelle policy di fiducia, attendi un minuto ed esegui di `terraform apply` nuovo: i ruoli IAM esisteranno già e l'applicazione riprenderà dal punto in cui era stata interrotta.

**ServiceNow `instanceId does not match`errore**
+ Impostato `instance_id` esplicitamente nel blocco di `service_now` integrazione sul nome breve dell'istanza (ad esempio,`"ven04972"`), non su quello completo`instance_url`. Vedi la nota nella parte 3 precedente.

**Associazione Dynatrace `status: invalid`**
+ Se `terraform apply` ha successo ma l'associazione risultante riporta i risultati `status = "invalid"` (visibili utilizzando `aws devops-agent get-association` o la console), ciò indica che Dynatrace ha rifiutato le credenziali del client OAuth. Double-check `client_id``client_secret`, e `account_urn` rispetto all'account Dynatrace, anziché a un problema di configurazione Terraform.

**Errori di autorizzazione**
+ Verifica che AWS le tue credenziali dispongano delle autorizzazioni IAM necessarie per creare ruoli e policy.
+ Verifica che le condizioni della politica di fiducia corrispondano all'ID del tuo account.

**Cross-account la distribuzione fallisce**
+ Il `aws.service` provider deve essere configurato con le credenziali per l'account del servizio. Utilizza un profilo denominato o un blocco Assume Role.
+ Verificate che il `agent_space_arn` valore corrisponda all'ARN dell'output della Parte 1.

**Tipo di risorsa Terraform non trovato**
+ Verifica di avere la versione del `awscc` provider `~> 1.0` o successiva. Le `awscc_devopsagent_association` risorse `awscc_devopsagent_agent_space` e richiedono il provider AWS Cloud Control.

## Pulizia
<a name="cleanup"></a>

Per rimuovere tutte le risorse, distruggile in ordine inverso se hai distribuito la Parte 2:

```
./cleanup.sh
```

O manualmente:

```
terraform destroy
```

**Avviso:** questa operazione elimina definitivamente lo spazio dell'agente e tutti i dati associati. Assicurati di aver eseguito il backup di tutte le informazioni importanti prima di procedere.

## Considerazioni relative alla sicurezza
<a name="security-considerations"></a>
+ La configurazione Terraform crea ruoli IAM con politiche di fiducia che consentono solo al responsabile del `aidevops.amazonaws.com` servizio di assumerli.
+ Le politiche di fiducia includono condizioni che limitano l'accesso al tuo AWS account specifico e allo spazio ARN dello spazio agente.
+ Tutte le politiche seguono il principio del privilegio minimo. Rivedi e personalizza le policy IAM in base ai requisiti di sicurezza della tua organizzazione.
+ Il ruolo tra account (`DevOpsAgentRole-SecondaryAccount-TF`) utilizza un nome fisso ed è limitato a uno spazio di agenti ARN specifico.

## Fasi successive
<a name="next-steps"></a>

Dopo aver distribuito il tuo AWS DevOps agente utilizzando Terraform:

1. Scopri l'intera gamma di funzionalità dell' DevOps agente nella Guida per l'[utente dell'AWS DevOps agente](https://docs.aws.amazon.com/devopsagent/latest/userguide/).

1. Prendi in considerazione l'integrazione dell'implementazione di Terraform nelle tue CI/CD pipeline per la gestione automatizzata dell'infrastruttura.

## Risorse aggiuntive
<a name="additional-resources"></a>
+ [AWS DevOps Guida per l'utente dell'agente](https://docs.aws.amazon.com/devopsagent/latest/userguide/)
+ [Esempio di repository Terraform](https://github.com/aws-samples/sample-aws-devops-agent-terraform)
+ [Guida all'onboarding CLI](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)
+ [risorsa awscc\_devopsagent\_agent\_space](https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/devopsagent_agent_space) *nel registro Terraform*
+ [https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/devopsagent_association](https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/devopsagent_association)
+ *risorsa [awscc\_devopsagent\_private\_connection](https://registry.terraform.io/providers/hashicorp/awscc/latest/docs/resources/devopsagent_private_connection) nel registro Terraform*