Visão geral do Pré-requisitos O que este guia aborda Parte 1: Implantar o espaço do agente Parte 2 (opcional): Adicionar monitoramento entre contas Parte 3: Adicione uma habilidade, um agente personalizado e um gatilho agendado Verificação Solução de problemas Limpeza Próximas etapas

Conceitos básicos de AWS DevOps Agente usando AWS CloudFormation

Visão geral do

Este guia mostra como usar AWS CloudFormation modelos para criar e implantar recursos AWS DevOps do agente. Os modelos automatizam a criação de um espaço de agente, funções de gerenciamento de AWS identidade e acesso (IAM), um aplicativo de operador e associações de AWS contas como infraestrutura e código.

A CloudFormation abordagem automatiza as etapas manuais descritas no guia de integração da CLI definindo todos os recursos necessários em modelos YAML declarativos.

AWS DevOps O agente está disponível em várias AWS regiões. Para ver a lista completa, consulte Regiões aceitas.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

AWS Interface de linha de comando (AWS CLI) instalada e configurada com as credenciais apropriadas
Permissões para criar funções e CloudFormation pilhas do IAM
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

Este guia está dividido nas seguintes 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 os problemas nessa conta.
Parte 2 (opcional) — Implante uma função de IAM entre contas em uma conta secundária e adicione uma AWS associação de origem. Essa configuração permite que o espaço do agente monitore recursos em todas as contas.
Parte 3 (opcional) — Adicione uma habilidade, um agente personalizado e um gatilho agendado ao espaço do agente, para que o agente tenha conhecimento personalizado e execute um agente personalizado de acordo com uma programação.

Parte 1: Implantar o espaço do agente

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

Etapa 1: criar o CloudFormation modelo

Salve o modelo a seguir comodevops-agent-stack.yaml:


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Agent Space with IAM roles, operator app, and AWS association

Parameters:
  AgentSpaceName:
    Type: String
    Default: MyCloudFormationAgentSpace
    Description: Name for the agent space
  AgentSpaceDescription:
    Type: String
    Default: Agent space deployed with CloudFormation
    Description: Description for the agent space

Resources:
  # IAM role assumed by the DevOps Agent service to monitor the account
  DevOpsAgentSpaceRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevOpsAgentRole-AgentSpace
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: aidevops.amazonaws.com
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref AWS::AccountId
              ArnLike:
                aws:SourceArn: !Sub arn:aws:aidevops:${AWS::Region}:${AWS::AccountId}:agentspace/*
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy
      Policies:
        - PolicyName: AllowCreateServiceLinkedRoles
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Sid: AllowCreateServiceLinkedRoles
                Effect: Allow
                Action:
                  - iam:CreateServiceLinkedRole
                Resource:
                  - !Sub arn:aws:iam::${AWS::AccountId}:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer

  # IAM role for the operator app interface
  DevOpsOperatorRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevOpsAgentRole-WebappAdmin
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: aidevops.amazonaws.com
            Action:
              - sts:AssumeRole
              - sts:TagSession
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref AWS::AccountId
              ArnLike:
                aws:SourceArn: !Sub arn:aws:aidevops:${AWS::Region}:${AWS::AccountId}:agentspace/*
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy

  # The agent space resource
  AgentSpace:
    Type: AWS::DevOpsAgent::AgentSpace
    DependsOn:
      - DevOpsAgentSpaceRole
      - DevOpsOperatorRole
    Properties:
      Name: !Ref AgentSpaceName
      Description: !Ref AgentSpaceDescription
      OperatorApp:
        Iam:
          OperatorAppRoleArn: !GetAtt DevOpsOperatorRole.Arn

  # Association linking the monitoring account to the agent space
  MonitorAssociation:
    Type: AWS::DevOpsAgent::Association
    Properties:
      AgentSpaceId: !GetAtt AgentSpace.AgentSpaceId
      ServiceId: aws
      Configuration:
        Aws:
          AssumableRoleArn: !GetAtt DevOpsAgentSpaceRole.Arn
          AccountId: !Ref AWS::AccountId
          AccountType: monitor

Outputs:
  AgentSpaceId:
    Description: The agent space ID
    Value: !GetAtt AgentSpace.AgentSpaceId
  AgentSpaceArn:
    Description: The agent space ARN
    Value: !GetAtt AgentSpace.Arn
  AgentSpaceRoleArn:
    Description: The agent space IAM role ARN
    Value: !GetAtt DevOpsAgentSpaceRole.Arn
  OperatorRoleArn:
    Description: The operator app IAM role ARN
    Value: !GetAtt DevOpsOperatorRole.Arn

Etapa 2: implantar a pilha

Execute o comando a seguir para implantar a pilha. <REGION>Substitua por um Regiões aceitas (por exemplo,us-east-1).


aws cloudformation deploy \
  --template-file devops-agent-stack.yaml \
  --stack-name DevOpsAgentStack \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <REGION>

Etapa 3: registre as saídas da pilha

Após a conclusão da implantação, execute o comando a seguir para recuperar as saídas da pilha. Registre esses valores para uso posterior.


aws cloudformation describe-stacks \
  --stack-name DevOpsAgentStack \
  --query 'Stacks[0].Outputs' \
  --region <REGION>

O exemplo a seguir mostra a saída esperada:


[
  {
    "OutputKey": "AgentSpaceId",
    "OutputValue": "abc123def456"
  },
  {
    "OutputKey": "AgentSpaceArn",
    "OutputValue": "arn:aws:aidevops:<REGION>:<ACCOUNT_ID>:agentspace/abc123def456"
  },
  {
    "OutputKey": "AgentSpaceRoleArn",
    "OutputValue": "arn:aws:iam::<ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace"
  },
  {
    "OutputKey": "OperatorRoleArn",
    "OutputValue": "arn:aws:iam::<ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin"
  }
]

Se você planeja concluir a Parte 2, salve o AgentSpaceArn valor. Você precisa dele para configurar a função entre contas.

Etapa 4: Verificar a implantação

Para verificar se o espaço do agente foi criado com êxito, execute o seguinte comando AWS CLI:


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

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

Implantação de uma função do IAM na conta de serviço que confia no espaço do agente.
Adicionar uma AWS associação de origem na conta de monitoramento que aponta para a conta de serviço.

Você deve concluir a Parte 1 antes de continuar. O modelo de conta de serviço exige as saídas AgentSpaceArn da pilha da Parte 1.

Etapa 1: criar o modelo de conta de serviço

Salve o modelo a seguir comodevops-agent-service-account.yaml. Esse modelo cria uma função de IAM entre contas na conta secundária.


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Cross-account IAM role for secondary account monitoring

Parameters:
  MonitoringAccountId:
    Type: String
    Description: The 12-digit AWS account ID of the monitoring account
  AgentSpaceArn:
    Type: String
    Description: The ARN of the agent space from the monitoring account

Resources:
  # Cross-account IAM role trusted by the agent space
  DevOpsSecondaryAccountRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevOpsAgentRole-SecondaryAccount
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: aidevops.amazonaws.com
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref MonitoringAccountId
              ArnLike:
                aws:SourceArn: !Ref AgentSpaceArn
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy
      Policies:
        - PolicyName: AllowCreateServiceLinkedRoles
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Sid: AllowCreateServiceLinkedRoles
                Effect: Allow
                Action:
                  - iam:CreateServiceLinkedRole
                Resource:
                  - !Sub arn:aws:iam::${AWS::AccountId}:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer

Outputs:
  SecondaryAccountRoleArn:
    Description: The cross-account IAM role ARN
    Value: !GetAtt DevOpsSecondaryAccountRole.Arn

Etapa 2: implantar a pilha de contas de serviço

Usando credenciais para a conta de serviço, execute o seguinte comando:


aws cloudformation deploy \
  --template-file devops-agent-service-account.yaml \
  --stack-name DevOpsAgentServiceAccountStack \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    MonitoringAccountId=<MONITORING_ACCOUNT_ID> \
    AgentSpaceArn=<AGENT_SPACE_ARN> \
  --region <REGION>

Etapa 3: adicionar a fonte AWS associação

Volte para a conta de monitoramento e crie uma AWS associação de origem. Você pode fazer isso criando uma pilha separada ou atualizando o modelo original. O exemplo a seguir usa um modelo independente.

Salve o modelo a seguir comodevops-agent-source-association.yaml:


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Source AWS association for cross-account monitoring

Parameters:
  AgentSpaceId:
    Type: String
    Description: The agent space ID from the monitoring account stack
  ServiceAccountId:
    Type: String
    Description: The 12-digit AWS account ID of the service account
  ServiceAccountRoleArn:
    Type: String
    Description: The ARN of the DevOpsAgentRole-SecondaryAccount role in the service account

Resources:
  SourceAssociation:
    Type: AWS::DevOpsAgent::Association
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      ServiceId: aws
      Configuration:
        SourceAws:
          AccountId: !Ref ServiceAccountId
          AccountType: source
          AssumableRoleArn: !Ref ServiceAccountRoleArn

Outputs:
  SourceAssociationId:
    Description: The source association ID
    Value: !Ref SourceAssociation

Implante a pilha de associações usando as credenciais da conta de monitoramento:


aws cloudformation deploy \
  --template-file devops-agent-source-association.yaml \
  --stack-name DevOpsAgentSourceAssociationStack \
  --parameter-overrides \
    AgentSpaceId=<AGENT_SPACE_ID> \
    ServiceAccountId=<SERVICE_ACCOUNT_ID> \
    ServiceAccountRoleArn=arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/DevOpsAgentRole-SecondaryAccount \
  --region <REGION>

Parte 3: Adicione uma habilidade, um agente personalizado e um gatilho agendado

Essa parte é opcional. Nesta seção, você adiciona três recursos ao espaço do agente criado na Parte 1. A primeira é uma habilidade que o agente carrega quando relevante. O segundo é um agente personalizado que define o escopo do agente em um fluxo de trabalho específico. O terceiro é um gatilho programado que executa o agente personalizado automaticamente. Esses recursos usam AWS::DevOpsAgent::Asset os tipos AWS::DevOpsAgent::Trigger de recursos e. Para obter mais informações sobre como gerenciar ativos como infraestrutura e código, consulteGerenciar ativos.

Você deve concluir a Parte 1 antes de continuar. Este modelo requer as saídas AgentSpaceId da pilha da Parte 1.

Etapa 1: criar o modelo

Salve o modelo a seguir comodevops-agent-content.yaml. A ação de um gatilho baseado em tempo faz referência ao agente personalizado por ID do ativo, no formuláriocustom:<assetId>. O modelo conecta isso automaticamente comFn::GetAtt.


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Example skill, custom agent, and scheduled trigger

Parameters:
  AgentSpaceId:
    Type: String
    Description: The agent space ID from the Part 1 stack outputs

Resources:
  # A skill the agent loads when relevant
  ExampleSkill:
    Type: AWS::DevOpsAgent::Asset
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      AssetType: skill
      Metadata:
        name: rds-performance-investigation
        description: Investigation procedures for RDS performance issues.
        agent_types:
          - GENERIC
      Files:
        - Path: SKILL.md
          ContentText: |
            # RDS Performance Investigation
            Use this skill when investigating database latency, connection
            errors, or query timeouts.

  # A custom agent that a trigger can invoke
  ExampleCustomAgent:
    Type: AWS::DevOpsAgent::Asset
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      AssetType: custom_agent
      Metadata:
        name: rds-firefighter
        skills:
          - rds-performance-investigation
      Files:
        - Path: AGENT.md
          ContentText: |
            # RDS Firefighter
            Custom agent for RDS incidents.

  # A time-based trigger that runs the custom agent on a schedule
  DailyTrigger:
    Type: AWS::DevOpsAgent::Trigger
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      Type: TIME_BASED
      Condition:
        Schedule:
          Expression: rate(1 day)
      Action:
        actionType: create:task
        task:
          agent: !Sub
            - custom:${AssetId}
            - AssetId: !GetAtt ExampleCustomAgent.AssetId
      Status: Active

Outputs:
  SkillAssetId:
    Description: The skill asset ID
    Value: !GetAtt ExampleSkill.AssetId
  CustomAgentAssetId:
    Description: The custom agent asset ID
    Value: !GetAtt ExampleCustomAgent.AssetId
  TriggerId:
    Description: The trigger ID
    Value: !GetAtt DailyTrigger.TriggerId

Etapa 2: implantar a pilha

Usando as credenciais da conta de monitoramento, execute o comando a seguir. <AGENT_SPACE_ID>Substitua pelo valor das saídas da Parte 1.


aws cloudformation deploy \
  --template-file devops-agent-content.yaml \
  --stack-name DevOpsAgentContentStack \
  --parameter-overrides AgentSpaceId=<AGENT_SPACE_ID> \
  --region <REGION>

As Action propriedades AgentSpaceIdType,Condition, e são somente para criação. Alterar qualquer um deles substitui o recurso. Você pode atualizar o gatilho Status (ActiveouInactive) existente — configurá-lo Inactive para pausar o gatilho sem excluí-lo. Para obter mais informações sobre os outros tipos de ativos e a referência completa da propriedade, consulteGerenciar ativos.

Verificação

Verifique sua configuração executando os seguintes comandos da AWS CLI:


# List your agent spaces
aws devops-agent list-agent-spaces \
  --region <REGION>

# Get details of a specific agent space
aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

# List associations for an agent space
aws devops-agent list-associations \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

Solução de problemas

Esta seção descreve problemas comuns e como resolvê-los.

CloudFormation tipo de recurso não encontrado

Verifique se você está implantando em umRegiões aceitas.
Confirme se sua AWS CLI está configurada com as permissões apropriadas.

Falha na criação da função do IAM

Verifique se suas credenciais de implantação têm permissões para criar funções do IAM com nomes personalizados (CAPABILITY_NAMED_IAM).
Verifique se as condições da política de confiança correspondem ao ID da sua conta.

Cross-account falha na implantação

Cada pilha deve ser implantada com credenciais para a conta de destino. Use o --profile sinalizador para especificar o perfil AWS CLI correto.
Verifique se o AgentSpaceArn parâmetro corresponde ao ARN exato das saídas da pilha da Parte 1.

Atrasos na propagação do IAM

As mudanças de função do IAM podem levar alguns minutos para serem propagadas. Se a criação do espaço do agente falhar imediatamente após a criação da função, aguarde alguns minutos e reimplante.

Limpeza

Para remover todos os recursos, exclua as pilhas na ordem inversa.

Aviso: Essa ação exclui permanentemente o espaço do agente e todos os dados associados. Esta ação não pode ser desfeita. Certifique-se de ter feito backup de todas as informações importantes antes de continuar.

Execute os seguintes comandos para excluir as pilhas:


# If you deployed the Part 3 content stack, delete it first
aws cloudformation delete-stack \
  --stack-name DevOpsAgentContentStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentContentStack \
  --region <REGION>

# If you deployed the source association stack, delete it next
aws cloudformation delete-stack \
  --stack-name DevOpsAgentSourceAssociationStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentSourceAssociationStack \
  --region <REGION>

# If you deployed the service account stack, delete it next (using service account credentials)
aws cloudformation delete-stack \
  --stack-name DevOpsAgentServiceAccountStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentServiceAccountStack \
  --region <REGION>

# Delete the main stack last
aws cloudformation delete-stack \
  --stack-name DevOpsAgentStack \
  --region <REGION>

Próximas etapas

Depois de implantar seu AWS DevOps agente usando AWS CloudFormation:

Para conectar integrações adicionais, consulteConfigurando integrações e conhecimento.
Se você registrar uma integração de terceiros, obtenha o URL e o segredo do webhook girando o webhook no console. AWS CloudFormation não retorna o segredo do webhook como uma saída de pilha, porque é sensível. Para obter instruções sobre como gerenciar credenciais de webhook, consulte Gerenciando credenciais de webhook.
Para saber mais sobre as habilidades e capacidades dos agentes, consulteDevOps Habilidades do agente.
Para obter mais informações sobre como gerenciar habilidades, agentes personalizados e outros ativos, como infraestrutura e código, consulteGerenciar ativos.
Para entender o aplicativo web do operador, consulteO que é um DevOps Agent Web App?.
Para obter referências detalhadas de propriedades dos tipos de CloudFormation recursos usados neste guia, consulte Referência do tipo de recurso do AWS DevOps agente na Referência do AWS CloudFormation modelo.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Conceitos básicos de AWS DevOps Agente usando AWS CDK

Conceitos básicos de AWS DevOps Agente usando o Terraform