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 CDK

Visão geral do

Este guia mostra como usar o AWS Cloud Development Kit (AWS CDK) para criar e implantar recursos do AWS DevOps agente. O aplicativo AWS CDK automatiza a criação de um espaço para agentes, funções de gerenciamento de AWS identidade e acesso (IAM), um aplicativo de operador e associações de AWS contas por meio dele. AWS CloudFormation

A abordagem AWS CDK automatiza as etapas manuais descritas no guia de integração da CLI, definindo todos os recursos necessários como infraestrutura e código.

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:

npm install -g aws-cdk

O que este guia aborda

Este guia está dividido nas seguintes partes:

Recursos criados

Parte 1: DevOpsAgentStack (conta de monitoramento)

Parte 2: ServiceStack (conta de serviço, opcional)

Parte 3: Ativos e gatilhos (conta de monitoramento, opcional)

Essa pilha cria os seguintes recursos:

Configuração

Etapa 1: clonar o repositório de amostra

Execute os seguintes comandos para clonar o repositório e mudar para o diretório do projeto:

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

Etapa 2: instalar dependências

Execute o comando a seguir para instalar as dependências do projeto:

npm install

Parte 1: Implantar o espaço do agente

Nesta seção, você cria 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: configurar o ID da conta de monitoramento

Abra lib/constants.ts e defina o ID da sua conta de monitoramento:

O exemplo a seguir mostra a constante a ser atualizada:

export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";

Etapa 2: inicialize o AWS Ambiente CDK

Se você não inicializou o AWS CDK em sua conta de monitoramento, execute o seguinte comando:

cdk bootstrap aws://<MONITORING_ACCOUNT_ID>/<REGION> --profile monitoring

Etapa 3: criar e implantar

Execute os seguintes comandos para criar o TypeScript código e implantar a pilha:

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Etapa 4: registre as saídas da pilha

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

O exemplo a seguir mostra a saída esperada:

Outputs:
DevOpsAgentStack.AgentSpaceArn = arn:aws:aidevops:<REGION>:123456789012:agentspace/abc123
DevOpsAgentStack.AgentSpaceRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace
DevOpsAgentStack.OperatorRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-WebappAdmin
DevOpsAgentStack.AssociationId = assoc-xyz

Se você planeja concluir a Parte 2, salve o AgentSpaceArn valor. Você precisa dele para configurar a pilha de contas de serviço.

A pilha gera o ARN do espaço do agente, não o ID do espaço do agente. As etapas posteriores solicitam a ID, que é o segmento posterior agentspace/ no ARN. No exemplo anterior, o ARN termina comagentspace/abc123, então a ID do espaço do agente é. abc123 Registre esse valor também.

Etapa 5: 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:

Etapa 1: configurar o ID da conta de serviço

Abra lib/constants.ts e defina o ID da sua conta de serviço:

O exemplo a seguir mostra a constante a ser atualizada:

export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";

O DevOpsAgentStack cria uma AWS associação de origem usando esse ID de conta. Se você implantou o DevOpsAgentStack antes de definir esse valor, reimplante para criar a associação:

Execute os seguintes comandos para reimplantar:

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Etapa 2: Definir o ARN do espaço do agente

Copie o AgentSpaceArn valor da DevOpsAgentStack saída (Parte 1, Etapa 4) e defina-o emlib/constants.ts:

O exemplo a seguir mostra a constante a ser atualizada:

export const AGENT_SPACE_ARN = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>";

O ServiceStack usa esse valor para definir o escopo da política de confiança na função secundária da conta. O só ServiceStack é sintetizado quando esse valor é definido.

Etapa 3: inicializar a conta de serviço

Se você não inicializou o AWS CDK em sua conta de serviço, execute o seguinte comando:

cdk bootstrap aws://<SERVICE_ACCOUNT_ID>/<REGION> --profile service

Etapa 4: implantar o ServiceStack

Execute os seguintes comandos para criar e implantar o ServiceStack usando credenciais para a conta de serviço:

npm run build
cdk deploy ServiceStack --profile service

Isso cria os seguintes recursos na conta de serviço:

Etapa 5: Verificar a implantação

Para confirmar se a função Lambda foi implantada com sucesso, execute os seguintes comandos para testar o serviço echo:

aws lambda invoke \
  --function-name echo-service \
  --payload '{"test": "hello world"}' \
  --profile service \
  response.json
cat response.json

Parte 3 (opcional): adicionar uma habilidade, um agente personalizado e um gatilho agendado

Nesta seção, você adiciona três recursos ao espaço do agente criado na Parte 1. Você adiciona uma habilidade que o agente carrega quando relevante e um agente personalizado que define o escopo do agente em um fluxo de trabalho específico. Você também adiciona um acionador agendado que executa o agente personalizado automaticamente. Esses recursos usam as CfnTrigger construções CfnAsset e do aws-cdk-lib/aws-devopsagent módulo.

Esses recursos podem gerar cobranças adicionais em sua AWS conta. Para removê-los quando terminar, siga a seção Limpeza no final deste guia.

Este exemplo usa skill os tipos custom_agent de ativos e. A mesma CfnAsset construção cria todos os tipos de ativosmemory_store, comoagents_md, e. attachment Para usar um tipo diferente, altere a assetType propriedade e forneça os metadados que esse tipo exige. Para ver a lista completa dos tipos de ativos, seus metadados necessários e a referência da propriedade, consulteGerenciar ativos.

Etapa 1: criar a pilha de conteúdo

Crie um arquivo denominado lib/content-stack.ts com os conteúdos a seguir. A ação de um gatilho baseado em tempo faz referência ao agente personalizado por ID do ativo, no formuláriocustom:<assetId>. A pilha conecta automaticamente essa referência usando o valor do attrAssetId atributo do agente personalizado. A skills lista de agentes personalizados também usa IDs de ativos em vez de nomes, portanto, usa as habilidadesattrAssetId. Isso também confere à pilha uma dependência implícita, então a habilidade é criada antes do agente que a anexa.

import * as cdk from 'aws-cdk-lib';
import { CfnAsset, CfnTrigger } from 'aws-cdk-lib/aws-devopsagent';
import { Construct } from 'constructs';

export interface ContentStackProps extends cdk.StackProps {
  readonly agentSpaceId: string;
}

export class ContentStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: ContentStackProps) {
    super(scope, id, props);

    // A skill the agent loads when relevant
    const skill = new CfnAsset(this, 'ExampleSkill', {
      agentSpaceId: props.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.',
          ].join('\n'),
        },
      ],
    });

    // A custom agent with attached skills that a trigger can invoke
    const customAgent = new CfnAsset(this, 'ExampleCustomAgent', {
      agentSpaceId: props.agentSpaceId,
      assetType: 'custom_agent',
      metadata: {
        name: 'rds-firefighter',
        skills: [skill.attrAssetId],
      },
      files: [
        {
          path: 'AGENT.md',
          contentText: ['# RDS Firefighter', 'Custom agent for RDS incidents.'].join('\n'),
        },
      ],
    });

    // A time-based trigger that runs the custom agent on a schedule
    const dailyTrigger = new CfnTrigger(this, 'DailyTrigger', {
      agentSpaceId: props.agentSpaceId,
      type: 'TIME_BASED',
      condition: {
        schedule: {
          expression: 'rate(1 day)',
        },
      },
      action: {
        actionType: 'create:task',
        task: {
          agent: `custom:${customAgent.attrAssetId}`,
        },
      },
      status: 'Active',
    });

    new cdk.CfnOutput(this, 'SkillAssetId', {
      description: 'The skill asset ID',
      value: skill.attrAssetId,
    });
    new cdk.CfnOutput(this, 'CustomAgentAssetId', {
      description: 'The custom agent asset ID',
      value: customAgent.attrAssetId,
    });
    new cdk.CfnOutput(this, 'TriggerId', {
      description: 'The trigger ID',
      value: dailyTrigger.attrTriggerId,
    });
  }
}

Etapa 2: adicione a pilha ao seu AWS Aplicação do CDK

No ponto de entrada do seu aplicativo (por exemplo,bin/app.ts), instancie a pilha e passe o ID do espaço do agente que você registrou na Parte 1, Etapa 4. Use o ID, comoabc123, e não o AgentSpaceArn valor total:

new ContentStack(app, 'ContentStack', {
  env: { account: MONITORING_ACCOUNT_ID, region: process.env.CDK_DEFAULT_REGION },
  agentSpaceId: '<AGENT_SPACE_ID>',
});

Etapa 3: implantar a pilha

Execute os seguintes comandos para criar e implantar a pilha usando as credenciais da conta de monitoramento:

npm run build
cdk deploy ContentStack --profile monitoring

As assetType propriedades agentSpaceId e de um ativo são somente para criação, assim como as action propriedadesagentSpaceId, typecondition, e de um acionador. 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.

Etapa 4: Verificar a implantação

Para confirmar se os ativos e o acionador foram criados, execute os seguintes comandos da 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>

Solução de problemas

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

CfnAssetou não CfnTrigger é exportado de aws-cdk-lib/aws-devopsagent

CloudFormation tipo de recurso não encontrado

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

Cross-account a implantação falha com “Não foi possível assumir a função na conta de destino”

Atrasos na propagação do IAM

Limpeza

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

Execute os seguintes comandos para destruir as pilhas:

# If you deployed the Part 3 ContentStack, destroy it first
cdk destroy ContentStack --profile monitoring
# If you deployed the ServiceStack, destroy it next
cdk destroy ServiceStack --profile service
# Then destroy the DevOpsAgentStack
cdk destroy DevOpsAgentStack --profile monitoring

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.

Considerações sobre segurança

Próximas etapas

Depois de implantar seu AWS DevOps agente usando o AWS CDK:

Recursos adicionais do