Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Introducción al AWS DevOps Agente que usa Terraform

Descripción general de

Esta guía muestra cómo usar Terraform para crear e implementar los recursos del AWS DevOps agente. La configuración de Terraform automatiza la creación de un espacio de agentes, funciones de IAM, una aplicación de operador y asociaciones de cuentas. AWS

El enfoque de Terraform automatiza los pasos manuales descritos en la guía de incorporación de la CLI al definir todos los recursos necesarios como infraestructura y código.

AWS DevOps El agente está disponible en las 6 AWS regiones siguientes: EE.UU. Este (Norte de Virginia), EE.UU. Oeste (Oregón), Asia Pacífico (Sídney), Asia Pacífico (Tokio), Europa (Fráncfort) y Europa (Irlanda). Para obtener más información sobre las regiones compatibles, consulteRegiones admitidas.

Requisitos previos

Antes de empezar, asegúrese de que tiene lo siguiente:

Qué cubre esta guía

Esta guía se divide en cuatro partes:

Recursos creados

Parte 1: Supervisar la cuenta

Parte 2: Cuenta de servicio (opcional)

Parte 4: Activos y activadores (opcional)

Esta configuración crea los siguientes recursos:

Configuración

Paso 1: clona el repositorio de muestras

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

Paso 2: Configurar las variables

Copie el archivo de variables de ejemplo y personalícelo para su entorno:

cp terraform.tfvars.example terraform.tfvars

terraform.tfvarsEdítelo con el nombre y la descripción de su espacio de agente:

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

Parte 1: Despliegue el espacio de agentes

En esta sección, crea el espacio de agentes, las funciones de IAM, la aplicación de operador y una AWS asociación en su cuenta de monitoreo.

Paso 1: Implemente con automatización (recomendado)

Utilice el script de implementación proporcionado para una configuración simplificada:

./deploy.sh

Este script automáticamente:

Como alternativa, si prefieres el control manual:

terraform init
terraform plan
terraform apply

Escriba yes cuando se le pida que confirme la implementación.

Paso 2: Registre las salidas

Una vez completada la implementación, Terraform imprime las salidas. Registre estos valores para usarlos más adelante:

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"

Si planea completar la parte 2, guarde el agent_space_arn valor. Lo necesitará para configurar los recursos de la cuenta de servicio.

Paso 3: Verifique la implementación

Ejecute el script de verificación posterior a la implementación:

./post-deploy.sh

O utilice la AWS CLI para comprobar que el espacio de agente se creó correctamente:

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

En este punto, su espacio de agente está desplegado con la aplicación del operador habilitada y su cuenta de monitoreo asociada. El agente puede supervisar los problemas de esta cuenta.

Parte 2 (opcional): añadir la supervisión multicuenta

En esta sección, ampliará la configuración para que el espacio de agentes pueda supervisar los recursos de una segunda AWS cuenta (la cuenta de servicio). Esto implica dos acciones:

Paso 1: Configurar el ID de la cuenta de servicio

Enterraform.tfvars, configura el ID de tu cuenta de servicio:

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

Paso 2: Configura el ARN del espacio de agente

Copie el agent_space_arn valor del resultado de la primera parte (paso 2) y configúrelo enterraform.tfvars:

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

Los recursos de la cuenta de servicio utilizan este valor para definir el alcance de la política de confianza en el rol de la cuenta secundaria. Estos recursos solo se crean cuando se establece este valor.

Paso 3: Configurar el proveedor `aws.service`

Enmain.tf, configure el alias del aws.service proveedor con las credenciales de la cuenta de servicio. Puede usar un perfil con nombre o asumir un rol:

Uso de un perfil:

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

O usando la función de asumir el rol:

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

Paso 4: Despliegue

Aplique la configuración actualizada:

terraform apply

Esto crea los siguientes recursos en la cuenta de servicio:

También crea una AWS asociación de origen en la cuenta de monitoreo que vincula la cuenta de servicio.

Paso 5: Verificar la implementación

Pruebe el servicio echo para confirmar que la función Lambda se implementó correctamente:

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 (opcional): registre las integraciones de terceros

En esta sección, registras los servicios externos (Dynatrace, Splunk ServiceNow, New Relic GitLab, PagerDuty) en el espacio de agentes. Estas integraciones permiten al AWS DevOps Agente acceder a la telemetría, a los datos de incidentes y a la información de control de fuentes durante las investigaciones.

A diferencia del ejemplo del AWS CDK, que requiere una IntegrationsStack fase separada y un cableado manual del identificador del espacio de agentes, estos recursos hacen referencia directa al espacio de agentes y se pueden implementar de la misma terraform apply manera que en la parte 1.

Integraciones compatibles

Paso 1: configurar las credenciales de integración

Agregue un integrations bloque aterraform.tfvars, rellenando solo los servicios que desee. El siguiente ejemplo muestra una integración de 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>"]
  }
}

Para ver la forma completa de cada integración, consulte el terraform.tfvars.example repositorio de ejemplos.

ServiceNow requisito: defina siempre de instance_id forma explícita el nombre corto de la instancia (por ejemplo"ven04972", no el nombre completoinstance_url). Si instance_id se omite, se recurre a la asociacióninstance_url, que la API del DevOps agente rechaza con un400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance.

Seguridad: la integrations variable está marcadasensitive, por lo que sus valores se eliminan del resultado del plan y la aplicación. No asigne credenciales reales aterraform.tfvars. Para la producción, obtenga AWS secretos de Secrets Manager o AWS Systems Manager Parameter Store (por ejemplo, utilizando data fuentes) en lugar de texto sin formato.

Paso 2: Despliegue

Aplique la configuración:

terraform apply

Esto crea un registro y una asociación de servicios para cada integración habilitada.

Paso 3: Revise los resultados

Una vez finalizada la implementación, los resultados de la integración asignan cada servicio habilitado a sus ID registrados:

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

Para obtener más información sobre la configuración de las credenciales para cada servicio, consulta:

Parte 4 (opcional): añada una habilidad, un agente personalizado y un activador programado

En esta sección, agrega tres recursos al espacio de agente que creó en la parte 1. Añada una habilidad que el agente cargue cuando sea relevante y un agente personalizado que asigne al agente un flujo de trabajo específico. También añades un activador programado que ejecuta el agente personalizado de forma automática. Estos recursos utilizan los awscc_devopsagent_trigger recursos awscc_devopsagent_asset y.

Estos recursos pueden generar cargos adicionales en tu AWS cuenta. Para eliminarlos cuando hayas terminado, sigue la sección Limpieza que aparece al final de esta guía.

En este ejemplo se utilizan los tipos de custom_agent activos skill y. El mismo awscc_devopsagent_asset recurso crea todos los tipos de activosmemory_store, comoagents_md, y. attachment Para usar un tipo diferente, cambie el asset_type argumento y proporcione los metadatos que requiere ese tipo. Para obtener la lista completa de los tipos de activos, sus metadatos necesarios y la referencia a la propiedad, consulteAdministración de activos.

Paso 1: Agregar la configuración

Cree un archivo denominado assets.tf con el siguiente contenido. La acción de un activador basada en el tiempo hace referencia al agente personalizado por el ID de activo, en el formulariocustom:<assetId>. La configuración lo transfiere automáticamente desde el asset_id atributo del agente personalizado. La skills lista de agentes personalizados también toma los ID de los activos en lugar de los nombres, por lo que hace referencia al asset_id atributo de la habilidad. Esto también le da a Terraform una dependencia implícita, por lo que la habilidad se crea antes que el agente que la adjunta.

Tenga en cuenta que los action argumentos metadata y son documentos JSON que se pasan como cadenas, por lo que este ejemplo usa. 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
}

Si lo añades al repositorio de muestras, puedes hacer referencia directamente al recurso del espacio de agentes en lugar de declarar la agent_space_id variable.

Paso 2: Despliegue

Defina el ID del espacio de terraform.tfvars agente utilizando el agent_space_id valor del resultado de la primera parte:

agent_space_id = "<AGENT_SPACE_ID>"

Aplique la configuración:

terraform apply

Los asset_type argumentos agent_space_id y de un activo son de solo creación, al igual que los action argumentos agent_space_id typecondition, y de un activador. Al cambiar cualquiera de ellos, se reemplaza el recurso. Puedes actualizar el desencadenador status (ActiveoInactive) en su lugar; configurarlo Inactive para pausar el desencadenador sin eliminarlo.

Paso 3: Verificar la implementación

Para confirmar que se crearon los activos y el activador, ejecute los siguientes comandos de la 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>

Uso de las funciones de IAM existentes (opcional)

De forma predeterminada, la configuración de Terraform crea nuevas funciones de IAM para el espacio de agentes y la aplicación de operador. Si ya tiene funciones de IAM con las políticas necesarias, puede omitir la creación de funciones y, en su lugar, proporcionar los ARN de las funciones existentes.

Requisitos

Los roles existentes deben cumplir los siguientes requisitos:

Función de espacio de agente

Función de aplicación de operador

Configuración

Enterraform.tfvars, defina uno o ambos ARN de rol:

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

Cuando se establecen estos valores, se iam.tf omiten los recursos de rol correspondientes. Este enfoque es totalmente compatible con versiones anteriores: las configuraciones existentes con valores vacíos (los valores predeterminados) conservan el comportamiento actual de creación de roles.

Resolución de problemas

Retrasos en la propagación de IAM

ServiceNow instanceId does not matcherror

Asociación Dynatrace status: invalid

Errores de permisos

Cross-account la implementación falla

No se encontró el tipo de recurso de Terraform

Limpieza

Si has completado la parte 4, elimina la habilidad, el agente personalizado y actívala primero. A diferencia de la guía del AWS CDK, que coloca estos recursos en una pila separada, assets.tf forma parte de la misma configuración de Terraform, por lo que una simple guía terraform destroy elimina el espacio de agente junto con ellos. Elimine assets.tf y aplique el cambio para eliminar solo los recursos de la Parte 4:

rm assets.tf
terraform apply

Para conservar el archivo, diríjase a los tres recursos en su lugar:

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

Al eliminar solo estos recursos, el espacio del agente permanece intacto. Hágalo si ha utilizado la parte 4 en un espacio de agente que comparte con otras personas o que no creó en la parte 1.

Para eliminar todo lo demás, destrúyalo en orden inverso si desplegó la parte 2:

./cleanup.sh

O manualmente:

terraform destroy

Advertencia: Esto elimina permanentemente tu espacio de agente y todos los datos asociados. Asegúrese de haber realizado una copia de seguridad de toda la información importante antes de continuar.

Consideraciones de seguridad

Siguientes pasos

Una vez que haya desplegado su AWS DevOps agente con Terraform:

Recursos adicionales