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

Panoramica di

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

L'approccio Terraform automatizza i passaggi manuali descritti nella guida all'onboarding della CLI definendo tutte le risorse richieste come infrastruttura come codice.

AWS DevOps Agent è 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

Prerequisiti

Prima di iniziare, assicurati di disporre di:

Cosa copre questa guida

Questa guida è divisa in quattro parti:

Risorse create

Parte 1: Account di monitoraggio

Parte 2: Account di servizio (opzionale)

Parte 4: Risorse e trigger (opzionale)

Questa configurazione crea le seguenti risorse:

Configurazione

Fase 1: clonare il repository di esempio

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

Fase 2: Configurazione delle variabili

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 agente:

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

Parte 1: Distribuisci lo spazio per gli agenti

In questa sezione, crei lo spazio dell'agente, i ruoli IAM, l'app per gli operatori e un' AWS associazione nel tuo account di monitoraggio.

Fase 1: Implementazione con automazione (consigliata)

Utilizza lo script di distribuzione fornito per una configurazione semplificata:

./deploy.sh

Questo script automaticamente:

In alternativa, se preferisci il controllo manuale:

terraform init
terraform plan
terraform apply

Digita yes quando richiesto per confermare la distribuzione.

Fase 2: Registrare gli output

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 prevedi di completare la parte 2, salva il agent_space_arn valore. Ti servirà per configurare le risorse dell'account di servizio.

Fase 3: Verifica la distribuzione

Esegui lo script di verifica post-distribuzione:

./post-deploy.sh

Oppure utilizza 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 dell'agente viene distribuito con l'app operatore abilitata e il tuo account di monitoraggio associato. L'agente può monitorare i problemi relativi a questo account.

Parte 2 (opzionale): aggiungere il monitoraggio su più account

In questa sezione, estendi 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:

Fase 1: Configurare l'ID dell'account di servizio

Interraform.tfvars, imposta l'ID del tuo account di servizio:

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

Passaggio 2: imposta l'ARN dello spazio agente

Copia il agent_space_arn valore dall'output della Parte 1 (Fase 2) e impostalo interraform.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 sul ruolo secondario dell'account. Queste risorse vengono create solo quando questo valore è impostato.

Fase 3: Configurare il provider `aws.service`

Inmain.tf, configura l'alias del aws.service provider con le credenziali per l'account di servizio. È possibile utilizzare un profilo denominato o assumere un ruolo:

Usare un profilo:

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

Oppure usando assumi ruolo:

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

Fase 4: distribuzione

Applica la configurazione aggiornata:

terraform apply

Questo crea le seguenti risorse nell'account del servizio:

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

Fase 5: Verifica la distribuzione

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

In questa sezione, registri i servizi esterni (Dynatrace, Splunk ServiceNow, New Relic, GitLab, PagerDuty) con lo spazio agente. Queste integrazioni consentono all' AWS DevOps agente 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 dell'agente, queste risorse fanno riferimento direttamente allo spazio dell'agente e possono essere implementate come nella Parte 1. terraform apply

Integrazioni supportate

Passaggio 1: configurare le credenziali di integrazione

Aggiungi un integrations blocco aterraform.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: impostato sempre in instance_id modo esplicito sul nome breve dell'istanza (ad esempio, "ven04972" non il nome completoinstance_url). Se instance_id viene omesso, l'associazione ritorna ainstance_url, che l'API dell' DevOps agente rifiuta con un. 400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance

Sicurezza: la integrations variabile è contrassegnatasensitive, quindi i suoi valori vengono cancellati dal piano e applicati all'output. Non inviare credenziali reali a. terraform.tfvars Per la produzione, utilizzate le informazioni segrete provenienti da AWS Secrets Manager o AWS Systems Manager Parameter Store (ad esempio, utilizzando data sorgenti) anziché testo in chiaro.

Fase 2: Implementazione

Applica la configurazione:

terraform apply

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

Fase 3: Rivedi i risultati

Al termine della distribuzione, gli output di integrazione associano ciascun 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 ciascun servizio, consulta:

Parte 4 (opzionale): aggiungi una skill, un agente personalizzato e un trigger pianificato

In questa sezione, aggiungi tre risorse allo spazio agente che hai creato nella Parte 1. Si aggiunge una competenza che l'agente carica quando pertinente e un agente personalizzato che assegna l'agente a un flusso di lavoro specifico. Si aggiunge anche un trigger pianificato che esegue automaticamente l'agente personalizzato. Queste risorse utilizzano le awscc_devopsagent_trigger risorse awscc_devopsagent_asset and.

Queste risorse potrebbero comportare costi aggiuntivi per il tuo AWS account. Per rimuoverle quando hai finito, segui la sezione Pulizia alla fine di questa guida.

Questo esempio utilizza i tipi di custom_agent asset skill e. La stessa awscc_devopsagent_asset risorsa crea ogni tipo di risorsa, ad esempio memory_storeagents_md, e. attachment Per utilizzare un tipo diverso, modificate l'asset_typeargomento e fornite i metadati richiesti dal tipo. Per l'elenco completo dei tipi di asset, i metadati richiesti e il riferimento alla proprietà, consultate. Gestione delle risorse

Fase 1: Aggiungere la configurazione

Crea un file denominato assets.tf con i seguenti contenuti. L'azione di un trigger basata sul tempo fa riferimento all'agente personalizzato in base all'ID dell'asset, nel modulocustom:<assetId>. La configurazione lo collega automaticamente dall'asset_idattributo dell'agente personalizzato. L'skillselenco dell'agente personalizzato accetta anche gli ID delle risorse anziché i nomi, quindi fa riferimento all'asset_idattributo dell'abilità. Ciò conferisce anche a Terraform una dipendenza implicita, quindi l'abilità viene creata prima dell'agente che la collega.

Nota che gli action argomenti metadata e sono documenti JSON passati come stringhe, quindi questo esempio utilizza. jsonencode

variable "agent_space_id" {
  type        = string
  description = "The agent space ID from the Part 1 output"
}

# A skill the agent loads when relevant
resource "awscc_devopsagent_asset" "example_skill" {
  agent_space_id = var.agent_space_id
  asset_type     = "skill"

  metadata = jsonencode({
    name        = "rds-performance-investigation"
    description = "Investigation procedures for RDS performance issues."
    agent_types = ["GENERIC"]
  })

  files = [{
    path         = "SKILL.md"
    content_text = <<-EOT
      # RDS Performance Investigation
      Use this skill when investigating database latency, connection
      errors, or query timeouts.
    EOT
  }]
}

# A custom agent with attached skills that a trigger can invoke
resource "awscc_devopsagent_asset" "example_custom_agent" {
  agent_space_id = var.agent_space_id
  asset_type     = "custom_agent"

  metadata = jsonencode({
    name   = "rds-firefighter"
    skills = [awscc_devopsagent_asset.example_skill.asset_id]
  })

  files = [{
    path         = "AGENT.md"
    content_text = <<-EOT
      # RDS Firefighter
      Custom agent for RDS incidents.
    EOT
  }]
}

# A time-based trigger that runs the custom agent on a schedule
resource "awscc_devopsagent_trigger" "daily" {
  agent_space_id = var.agent_space_id
  type           = "TIME_BASED"

  condition = {
    schedule = {
      expression = "rate(1 day)"
    }
  }

  action = jsonencode({
    actionType = "create:task"
    task = {
      agent = "custom:${awscc_devopsagent_asset.example_custom_agent.asset_id}"
    }
  })

  status = "Active"
}

output "skill_asset_id" {
  description = "The skill asset ID"
  value       = awscc_devopsagent_asset.example_skill.asset_id
}

output "custom_agent_asset_id" {
  description = "The custom agent asset ID"
  value       = awscc_devopsagent_asset.example_custom_agent.asset_id
}

output "trigger_id" {
  description = "The trigger ID"
  value       = awscc_devopsagent_trigger.daily.trigger_id
}

Se lo stai aggiungendo al repository di esempio, puoi fare riferimento direttamente alla risorsa di spazio dell'agente invece di dichiarare la variabile. agent_space_id

Fase 2: distribuzione

Imposta l'ID dello spazio dell'agenteterraform.tfvars, utilizzando il agent_space_id valore dell'output della Parte 1:

agent_space_id = "<AGENT_SPACE_ID>"

Applica la configurazione:

terraform apply

asset_typeGli argomenti agent_space_id e di un asset sono di sola creazione, così come action gli argomentiagent_space_id, typecondition, e di un trigger. La modifica di uno di essi sostituisce la risorsa. Puoi aggiornare il trigger status (ActiveoInactive) in posizione: impostalo in modo da mettere in pausa il trigger Inactive senza eliminarlo.

Passaggio 3: verifica la distribuzione

Per confermare che gli asset e il trigger sono stati creati, esegui i seguenti comandi AWS CLI:

aws devops-agent list-assets \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

aws devops-agent list-triggers \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

Utilizzo dei ruoli IAM esistenti (opzionale)

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

Requisiti

I ruoli esistenti devono soddisfare i seguenti requisiti:

Ruolo nello spazio dell'agente

Ruolo dell'operatore nell'app

Configurazione

Interraform.tfvars, imposta uno o entrambi gli ARN dei ruoli:

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 iam.tf vengono ignorate. Questo approccio è completamente compatibile con le versioni precedenti: le configurazioni esistenti con valori vuoti (impostazione predefinita) mantengono il comportamento corrente di creazione dei ruoli.

Risoluzione dei problemi

Ritardi di propagazione IAM

ServiceNow instanceId does not matcherrore

Associazione Dynatrace status: invalid

Errori di autorizzazione

Cross-account la distribuzione non riesce

Tipo di risorsa Terraform non trovato

Pulizia

Se hai completato la Parte 4, rimuovi prima l'abilità, l'agente personalizzato e il trigger. A differenza della guida AWS CDK, che mette queste risorse in uno stack separato, assets.tf fa parte della stessa configurazione Terraform, quindi una semplice operazione terraform destroy rimuove lo spazio dell'agente insieme ad esse. Elimina assets.tf e applica la modifica per rimuovere solo le risorse della Parte 4:

rm assets.tf
terraform apply

Per conservare il file, scegli invece le tre risorse:

terraform destroy \
  -target=awscc_devopsagent_trigger.daily \
  -target=awscc_devopsagent_asset.example_custom_agent \
  -target=awscc_devopsagent_asset.example_skill

La rimozione solo di queste risorse lascia intatto lo spazio dell'agente. Fate questa operazione se avete applicato la Parte 4 a uno spazio agente che condividete con altri o che non avete creato nella Parte 1.

Per poi rimuovere tutto il resto, distruggi in ordine inverso se hai utilizzato 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

Fasi successive

Dopo aver distribuito il tuo AWS DevOps agente utilizzando Terraform:

Risorse aggiuntive