Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Nozioni di base su AWS DevOps Agente che utilizza AWS CDK

Panoramica di

Questa guida mostra come utilizzare il AWS Cloud Development Kit (AWS CDK) per creare e distribuire risorse per gli AWS DevOps agenti. L'applicazione AWS CDK automatizza la creazione di uno spazio per gli agenti, dei ruoli IAM ( AWS Identity and Access Management), di un'app per operatori e AWS delle associazioni di account tramite. AWS CloudFormation

L'approccio AWS CDK automatizza i passaggi manuali descritti nella guida all'onboarding della CLI definendo tutte le risorse richieste come infrastruttura in codice.

AWS DevOps L'agente è disponibile in più regioni. AWS Per l'elenco completo, consulta Regioni supportate.

Prerequisiti

Prima di iniziare, assicurati di disporre di:

npm install -g aws-cdk

Cosa copre questa guida

Questa guida è suddivisa nelle seguenti parti:

Risorse create

Parte 1: DevOpsAgentStack (account di monitoraggio)

Parte 2: ServiceStack (account di servizio, opzionale)

Parte 3: Risorse e trigger (account di monitoraggio, opzionale)

Questo stack crea le seguenti risorse:

Configurazione

Fase 1: clonare il repository di esempio

Eseguite i seguenti comandi per clonare il repository e passare alla directory del progetto:

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

Fase 2: Installare le dipendenze

Esegui il comando seguente per installare le dipendenze del progetto:

npm install

Parte 1: Distribuisci lo spazio dell'agente

In questa sezione, crei lo spazio dell'agente, i ruoli IAM, l'app per gli operatori e un' AWS associazione nel tuo account di monitoraggio.

Passaggio 1: configura l'ID dell'account di monitoraggio

Apri lib/constants.ts e imposta l'ID del tuo account di monitoraggio:

L'esempio seguente mostra la costante da aggiornare:

export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";

Fase 2: Avvia il AWS Ambiente CDK

Se non hai avviato il AWS CDK nel tuo account di monitoraggio, esegui il seguente comando:

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

Fase 3: compilazione e distribuzione

Esegui i seguenti comandi per creare il TypeScript codice e distribuire lo stack:

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Fase 4: Registrare gli output dello stack

Al termine della distribuzione, il AWS CDK stampa gli output dello stack. Registra questi valori per un uso successivo.

L'esempio seguente mostra l'output previsto:

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 intendete completare la parte 2, salvate il AgentSpaceArn valore. È necessario per configurare lo stack degli account di servizio.

Lo stack emette l'ARN dello spazio dell'agente, non l'ID dello spazio dell'agente. I passaggi successivi richiedono l'ID, che è il segmento successivo agentspace/ nell'ARN. Nell'esempio precedente, l'ARN termina conagentspace/abc123, quindi l'ID dello spazio dell'agente è. abc123 Registra anche quel valore.

Fase 5: Verifica la distribuzione

Per verificare che lo spazio dell'agente sia stato creato correttamente, esegui il seguente comando AWS CLI:

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

A questo punto, lo spazio dell'agente viene distribuito con l'app operatore abilitata e l'account di monitoraggio associato. L'agente può monitorare i problemi relativi a questo account.

Parte 2 (opzionale): aggiungere il monitoraggio su più account

In questa sezione, estendi la configurazione in modo che il tuo spazio agente possa monitorare le risorse in un secondo AWS account (l'account di servizio). Ciò comporta due azioni:

Fase 1: Configurare l'ID dell'account di servizio

Apri lib/constants.ts e imposta l'ID del tuo account di servizio:

L'esempio seguente mostra la costante da aggiornare:

export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";

DevOpsAgentStack Crea un' AWS associazione di origine utilizzando questo ID account. Se hai distribuito DevOpsAgentStack prima di impostare questo valore, ridistribuiscilo per creare l'associazione:

Esegui i seguenti comandi per ridistribuire:

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Passaggio 2: imposta l'ARN dello spazio dell'agente

Copia il AgentSpaceArn valore dall' DevOpsAgentStack output (parte 1, passaggio 4) e impostalo inlib/constants.ts:

L'esempio seguente mostra la costante da aggiornare:

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

ServiceStack Utilizza questo valore per definire la politica di fiducia sul ruolo secondario dell'account. ServiceStack Viene sintetizzato solo quando questo valore è impostato.

Fase 3: Avvia l'account del servizio

Se non hai avviato il AWS CDK nel tuo account di servizio, esegui il seguente comando:

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

Fase 4: Implementa il ServiceStack

Esegui i seguenti comandi per creare e distribuire ServiceStack utilizzando le credenziali per l'account di servizio:

npm run build
cdk deploy ServiceStack --profile service

Questo crea le seguenti risorse nell'account di servizio:

Passaggio 5: verifica la distribuzione

Per confermare che la funzione Lambda è stata implementata correttamente, esegui i seguenti comandi per testare il servizio echo:

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

Parte 3 (opzionale): aggiungi una skill, un agente personalizzato e un trigger pianificato

In questa sezione, aggiungi tre risorse allo spazio agente che hai creato nella Parte 1. Si aggiunge una competenza che l'agente carica quando pertinente e un agente personalizzato che assegna l'agente a un flusso di lavoro specifico. Si aggiunge anche un trigger pianificato che esegue automaticamente l'agente personalizzato. Queste risorse utilizzano i CfnTrigger costrutti CfnAsset and del aws-cdk-lib/aws-devopsagent modulo.

Queste risorse potrebbero comportare costi aggiuntivi per il tuo AWS account. Per rimuoverle quando hai finito, segui la sezione Pulizia alla fine di questa guida.

Questo esempio utilizza i tipi di custom_agent asset skill e. Lo stesso CfnAsset costrutto crea ogni tipo di risorsa, ad esempiomemory_store, agents_md e. attachment Per utilizzare un tipo diverso, modificate la assetType proprietà e fornite i metadati richiesti dal tipo. Per l'elenco completo dei tipi di asset, i metadati richiesti e il riferimento alla proprietà, consultate. Gestione delle risorse

Fase 1: Creare lo stack di contenuti

Crea un file denominato lib/content-stack.ts con i seguenti contenuti. L'azione di un trigger basata sul tempo fa riferimento all'agente personalizzato in base all'ID della risorsa, nel modulocustom:<assetId>. Lo stack collega automaticamente questo riferimento utilizzando il valore dell'attrAssetIdattributo dell'agente personalizzato. L'skillselenco dell'agente personalizzato accetta anche gli ID delle risorse anziché i nomi, quindi utilizza le abilitàattrAssetId. Ciò conferisce inoltre allo stack una dipendenza implicita, quindi l'abilità viene creata prima dell'agente che la collega.

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,
    });
  }
}

Passaggio 2: aggiungi lo stack al tuo AWS App CDK

Nel punto di ingresso dell'app (ad esempiobin/app.ts), crea un'istanza dello stack e trasmetti l'ID dello spazio dell'agente che hai registrato nella Parte 1, Passaggio 4. Usa l'ID, ad esempioabc123, e non il valore completoAgentSpaceArn:

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

Fase 3: Distribuisci lo stack

Esegui i seguenti comandi per creare e distribuire lo stack utilizzando le credenziali dell'account di monitoraggio:

npm run build
cdk deploy ContentStack --profile monitoring

Le assetType proprietà agentSpaceId e di una risorsa sono di sola creazione, così come le action proprietàagentSpaceId, typecondition, e di un trigger. La modifica di una di esse sostituisce la risorsa. Puoi aggiornare il trigger status (ActiveoInactive) in posizione: impostalo in modo da mettere in pausa il trigger Inactive senza eliminarlo. Per ulteriori informazioni sugli altri tipi di asset e sul riferimento completo alla proprietà, consultate. Gestione delle risorse

Fase 4: verifica della distribuzione

Per confermare che gli asset e il trigger sono stati creati, esegui i seguenti comandi 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>

Risoluzione dei problemi

Questa sezione descrive i problemi più comuni e come risolverli.

CfnAsseto non CfnTrigger viene esportato da aws-cdk-lib/aws-devopsagent

CloudFormation tipo di risorsa non trovato

Creazione del ruolo IAM non riuscita

Cross-account la distribuzione non riesce con «Impossibile assumere il ruolo nell'account di destinazione»

Ritardi nella propagazione dell'IAM

Pulizia

Per rimuovere tutte le risorse, distruggi gli stack in ordine inverso.

Esegui i seguenti comandi per distruggere le pile:

# 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

Avviso: questa azione elimina definitivamente lo spazio dell'agente e tutti i dati associati. Questa azione non può essere annullata. Assicurati di aver eseguito il backup di tutte le informazioni importanti prima di procedere.

Considerazioni relative alla sicurezza

Fasi successive

Dopo aver distribuito il tuo AWS DevOps agente utilizzando il CDK: AWS

Risorse aggiuntive