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á. # 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 ](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html) 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](about-aws-devops-agent-supported-regions.md). ## 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 como`devops-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. ``Substitua por um [Regiões aceitas](about-aws-devops-agent-supported-regions.md) (por exemplo,`us-east-1`). ``` aws cloudformation deploy \ --template-file devops-agent-stack.yaml \ --stack-name DevOpsAgentStack \ --capabilities CAPABILITY_NAMED_IAM \ --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 ``` O exemplo a seguir mostra a saída esperada: ``` [ { "OutputKey": "AgentSpaceId", "OutputValue": "abc123def456" }, { "OutputKey": "AgentSpaceArn", "OutputValue": "arn:aws:aidevops:::agentspace/abc123def456" }, { "OutputKey": "AgentSpaceRoleArn", "OutputValue": "arn:aws:iam:::role/DevOpsAgentRole-AgentSpace" }, { "OutputKey": "OperatorRoleArn", "OutputValue": "arn:aws:iam:::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 \ --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: 1. Implantação de uma função do IAM na conta de serviço que confia no espaço do agente. 1. 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 como`devops-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= \ AgentSpaceArn= \ --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 como`devops-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= \ ServiceAccountId= \ ServiceAccountRoleArn=arn:aws:iam:::role/DevOpsAgentRole-SecondaryAccount \ --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, consulte[Gerenciar ativos](about-aws-devops-agent-managing-assets.md). 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 como`devops-agent-content.yaml`. A ação de um gatilho baseado em tempo faz referência ao agente personalizado por ID do ativo, no formulário`custom:`. O modelo conecta isso automaticamente com`Fn::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. ``Substitua pelo valor das saídas da Parte 1. ``` aws cloudformation deploy \ --template-file devops-agent-content.yaml \ --stack-name DevOpsAgentContentStack \ --parameter-overrides AgentSpaceId= \ --region ``` As `Action` propriedades `AgentSpaceId``Type`,`Condition`, e são somente para criação. Alterar qualquer um deles substitui o recurso. Você pode atualizar o gatilho `Status` (`Active`ou`Inactive`) 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, consulte[Gerenciar ativos](about-aws-devops-agent-managing-assets.md). ## Verificação Verifique sua configuração executando os seguintes comandos da AWS CLI: ``` # List your agent spaces aws devops-agent list-agent-spaces \ --region # Get details of a specific agent space aws devops-agent get-agent-space \ --agent-space-id \ --region # List associations for an agent space aws devops-agent list-associations \ --agent-space-id \ --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 um[Regiões aceitas](about-aws-devops-agent-supported-regions.md). + 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 aws cloudformation wait stack-delete-complete \ --stack-name DevOpsAgentContentStack \ --region # If you deployed the source association stack, delete it next aws cloudformation delete-stack \ --stack-name DevOpsAgentSourceAssociationStack \ --region aws cloudformation wait stack-delete-complete \ --stack-name DevOpsAgentSourceAssociationStack \ --region # If you deployed the service account stack, delete it next (using service account credentials) aws cloudformation delete-stack \ --stack-name DevOpsAgentServiceAccountStack \ --region aws cloudformation wait stack-delete-complete \ --stack-name DevOpsAgentServiceAccountStack \ --region # Delete the main stack last aws cloudformation delete-stack \ --stack-name DevOpsAgentStack \ --region ``` ## Próximas etapas Depois de implantar seu AWS DevOps agente usando AWS CloudFormation: + Para conectar integrações adicionais, consulte[Configurando integrações e conhecimento](configuring-integrations-and-knowledge.md). + 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. ](configuring-integrations-and-knowledge-invoking-devops-agent-through-webhook.md) + Para saber mais sobre as habilidades e capacidades dos agentes, consulte[DevOps Habilidades do agente](about-aws-devops-agent-devops-agent-skills.md). + Para obter mais informações sobre como gerenciar habilidades, agentes personalizados e outros ativos, como infraestrutura e código, consulte[Gerenciar ativos](about-aws-devops-agent-managing-assets.md). + Para entender o aplicativo web do operador, consulte[O que é um DevOps Agent Web App?](about-aws-devops-agent-what-is-a-devops-agent-web-app.md). + 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 ](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/AWS_DevOpsAgent.html) na Referência do *AWS CloudFormation modelo*.