As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Introdução ao AWS DevOps Agent usando o Terraform
<a name="getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-terraform"></a>

## Visão geral do
<a name="overview"></a>

Este guia mostra como usar o Terraform para criar e implantar recursos do AWS DevOps Agente. A configuração do Terraform automatiza a criação de um espaço de agente, funções do IAM, um aplicativo de operador e associações de AWS contas.

A abordagem do Terraform automatiza as etapas manuais descritas no [guia de integração da CLI](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html), definindo todos os recursos necessários como infraestrutura como código.

AWS DevOps O agente está disponível nas seguintes 6 AWS regiões: Leste dos EUA (Norte da Virgínia), Oeste dos EUA (Oregon), Ásia-Pacífico (Sydney), Ásia-Pacífico (Tóquio), Europa (Frankfurt) e Europa (Irlanda). Para obter mais informações sobre as regiões suportadas, consulte[Regiões aceitas](about-aws-devops-agent-supported-regions.md).

## Pré-requisitos
<a name="prerequisites"></a>

Antes de começar, você deve ter o seguinte:
+ Terraform >= 1.0 instalado
+ AWS CLI instalada e configurada com as credenciais apropriadas
+ Uma AWS conta para a conta de monitoramento (primária)
+ (Opcional) Uma segunda AWS conta se você quiser configurar o monitoramento entre contas

## O que este guia aborda
<a name="what-this-guide-covers"></a>

Este guia está dividido em duas partes:
+ **Parte 1** — Implante um espaço de agente com um aplicativo de operador e uma AWS associação em sua conta de monitoramento. Depois de concluir essa parte, o agente pode monitorar problemas nessa conta.
+ **Parte 2 (opcional)** — Adicione uma AWS associação de origem para uma conta de serviço e implante uma função do IAM entre contas, além de um echo Lambda nessa conta. Isso permite que o espaço do agente monitore os recursos em todas as contas.

## Recursos criados
<a name="resources-created"></a>

### Parte 1: Conta de monitoramento
<a name="part-1-monitoring-account"></a>
+ **Função do IAM** (`DevOpsAgentRole-AgentSpace-*`) — assumida pelo serviço do DevOps agente para monitorar a conta. Inclui a política `AIDevOpsAgentAccessPolicy` gerenciada e uma política em linha que permite a criação da função vinculada ao serviço Resource Explorer.
+ **Função do IAM** (`DevOpsAgentRole-WebappAdmin-*`) — Função do aplicativo operador com a política `AIDevOpsOperatorAppAccessPolicy` gerenciada para operações do agente.
+ **Espaço do agente** (nome configurável) — O espaço do agente central, criado usando o `awscc_devopsagent_agent_space` recurso. Inclui a configuração do aplicativo do operador.
+ **Associação** (AWS monitor) — vincula a conta de monitoramento ao espaço do agente usando o `awscc_devopsagent_association` recurso.
+ **Associação** (AWS fonte) — (Opcional) Vincula a conta de serviço ao espaço do agente para monitoramento entre contas.

### Parte 2: Conta de serviço (opcional)
<a name="part-2-service-account-optional"></a>
+ **Função do IAM** (`DevOpsAgentRole-SecondaryAccount-TF`) — Função entre contas com um nome fixo. Confiável pelo espaço do agente na conta de monitoramento. Inclui a política `AIDevOpsAgentAccessPolicy` gerenciada e uma política em linha que permite a criação da função vinculada ao serviço Resource Explorer.
+ **Função Lambda** (`echo-service-tf`) — Um exemplo simples de serviço que reflete eventos de entrada.

## Configuração
<a name="setup"></a>

### Etapa 1: clonar o repositório de amostra
<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
```

### Etapa 2: configurar variáveis
<a name="step-2-configure-variables"></a>

Copie o arquivo de variáveis de exemplo e personalize-o para seu ambiente:

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

Edite `terraform.tfvars` com o nome e a descrição do seu espaço de agente:

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

## Parte 1: Implantar o espaço do agente
<a name="part-1-deploy-the-agent-space"></a>

Nesta seção, você cria o espaço do agente, as funções do IAM, o aplicativo do operador e uma AWS associação na sua conta de monitoramento.

### Etapa 1: implantar com automação (recomendado)
<a name="step-1-deploy-with-automation-recommended"></a>

Use o script de implantação fornecido para uma configuração simplificada:

```
./deploy.sh
```

Esse script automaticamente:
+ Verifica os pré-requisitos (Terraform, AWS CLI, credenciais)
+ Cria `terraform.tfvars` a partir do exemplo, se necessário
+ Inicializa, valida, planeja e aplica o Terraform

Como alternativa, se você preferir o controle manual:

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

Digite `yes` quando solicitado para confirmar a implantação.

### Etapa 2: Grave as saídas
<a name="step-2-record-the-outputs"></a>

Após a conclusão da implantação, o Terraform imprime as saídas. Registre esses valores para uso posterior:

```
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 você planeja concluir a Parte 2, salve o `agent_space_arn` valor. Você precisará dele para configurar os recursos da conta de serviço.

### Etapa 3: verificar a implantação
<a name="step-3-verify-the-deployment"></a>

Execute o script de verificação pós-implantação:

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

Ou use a AWS CLI para verificar se o espaço do agente foi criado com êxito:

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

Nesse ponto, seu espaço de agente é implantado com o aplicativo do operador ativado e sua conta de monitoramento associada. O agente pode monitorar problemas nessa conta.

## Parte 2 (opcional): adicionar monitoramento entre contas
<a name="part-2-optional-add-cross-account-monitoring"></a>

Nesta seção, você estende a configuração para que o espaço do agente possa monitorar recursos em uma segunda AWS conta (a conta de serviço). Isso envolve duas ações:

1. Adicionar uma AWS associação de origem que aponta para a conta de serviço.

1. Implantação de uma função IAM entre contas e uma função echo Lambda na conta de serviço.

**Importante**  
**Você deve concluir a Parte 1 antes de continuar. Os recursos da conta de serviço exigem o resultado `agent_space_arn` da implantação da Parte 1.

### Etapa 1: configurar o ID da conta de serviço
<a name="step-1-configure-the-service-account-id"></a>

Em`terraform.tfvars`, defina o ID da sua conta de serviço:

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

### Etapa 2: definir o ARN do espaço do agente
<a name="step-2-set-the-agent-space-arn"></a>

Copie o `agent_space_arn` valor da saída da Parte 1 (Etapa 2) e defina-o em`terraform.tfvars`:

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

Os recursos da conta de serviço usam esse valor para definir o escopo da política de confiança na função secundária da conta. Esses recursos são criados somente quando esse valor é definido.

### Etapa 3: configurar o provedor `aws.service`
<a name="step-3-configure-the-awsservice-provider"></a>

Em`main.tf`, configure o alias do `aws.service` provedor com as credenciais da conta de serviço. Você pode usar um perfil nomeado ou assumir uma função:

Usando um perfil:

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

Ou usando assume a função:

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

### Etapa 4: implantar
<a name="step-4-deploy"></a>

Aplique a configuração atualizada:

```
terraform apply
```

Isso cria os seguintes recursos na conta de serviço:
+ Uma função do IAM (`DevOpsAgentRole-SecondaryAccount-TF`) que confia no espaço do agente na conta de monitoramento
+ Uma função echo Lambda `echo-service-tf` () como um serviço de exemplo

Ele também cria uma AWS associação de origem na conta de monitoramento que vincula a conta de serviço.

### Etapa 5: verificar a implantação
<a name="step-5-verify-the-deployment"></a>

Teste o serviço echo para confirmar se a função Lambda foi implantada com sucesso:

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

## Solução de problemas
<a name="troubleshooting"></a>

**Atrasos na propagação do IAM**
+ A configuração inclui 30 segundos `time_sleep` entre a criação da função do IAM e a criação do Agent Space. O serviço de DevOps agente valida a política de confiança da função de operador durante a criação do Agent Space, e isso pode falhar se o IAM não for totalmente propagado. Se você ainda encontrar erros na política de confiança, espere um minuto e execute `terraform apply` novamente. As funções do IAM já existirão e a aplicação continuará de onde parou.

**Erros de permissão**
+ Verifique se suas AWS credenciais têm as permissões necessárias do IAM para criar funções e políticas.
+ Verifique se as condições da política de confiança correspondem ao ID da sua conta.

**Falha na implantação entre contas**
+ O `aws.service` provedor deve ser configurado com as credenciais da conta de serviço. Use um perfil nomeado ou um bloco de assumir funções.
+ Verifique se o `agent_space_arn` valor corresponde ao ARN da saída da Parte 1.

**Tipo de recurso do Terraform não encontrado**
+ Verifique se você tem a versão do `awscc` provedor `~> 1.0` ou posterior. Os `awscc_devopsagent_association` recursos `awscc_devopsagent_agent_space` e exigem o provedor do AWS Cloud Control.

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

Para remover todos os recursos, destrua na ordem inversa se você implantou a Parte 2:

```
./cleanup.sh
```

Ou manualmente:

```
terraform destroy
```

**Aviso:** Isso exclui permanentemente seu espaço de agente e todos os dados associados. Certifique-se de ter feito backup de todas as informações importantes antes de continuar.

## Considerações sobre segurança
<a name="security-considerations"></a>
+ A configuração do Terraform cria funções do IAM com políticas de confiança que só permitem que o responsável pelo `aidevops.amazonaws.com` serviço as assuma.
+ As políticas de confiança incluem condições que restringem o acesso à sua AWS conta específica e ao ARN do espaço do agente.
+ Todas as políticas seguem o princípio do menor privilégio. Analise e personalize as políticas do IAM com base nos requisitos de segurança da sua organização.
+ A função entre contas (`DevOpsAgentRole-SecondaryAccount-TF`) usa um nome fixo e tem como escopo um ARN de espaço de agente específico.

## Próximas etapas
<a name="next-steps"></a>

Depois de implantar seu AWS DevOps agente usando o Terraform:

1. Saiba mais sobre a gama completa de recursos do DevOps Agente no [Guia do Usuário do AWS DevOps Agente](https://docs.aws.amazon.com/devopsagent/latest/userguide/).

1. Considere integrar a implantação do Terraform em seus CI/CD pipelines para gerenciamento automatizado da infraestrutura.

## Recursos adicionais do
<a name="additional-resources"></a>
+ [AWS DevOps Guia do usuário do agente](https://docs.aws.amazon.com/devopsagent/latest/userguide/)
+ [Exemplo de repositório Terraform](https://github.com/aws-samples/sample-aws-devops-agent-terraform)
+ [Guia de integração da CLI](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)