Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Démarrage avec AWS DevOps Agent utilisant AWS CDK

Vue d’ensemble

Ce guide explique comment utiliser le AWS Cloud Development Kit (AWS CDK) pour créer et déployer des ressources d' AWS DevOps agent. L'application AWS CDK automatise la création d'un espace d'agent, de rôles de gestion des AWS identités et des accès (IAM), d'une application opérateur et d'associations de AWS comptes via. AWS CloudFormation

L'approche AWS CDK automatise les étapes manuelles décrites dans le guide d'intégration de la CLI en définissant toutes les ressources requises sous forme d'infrastructure en tant que code.

AWS DevOps L'agent est disponible dans plusieurs AWS régions. Pour obtenir la liste complète, consultez Régions prises en charge.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

npm install -g aws-cdk

Ce que couvre ce guide

Ce guide comprend les parties suivantes :

Ressources créées

Partie 1 : DevOpsAgentStack (compte de suivi)

Partie 2 : ServiceStack (compte de service, facultatif)

Partie 3 : Actifs et déclencheurs (compte de surveillance, facultatif)

Cette pile crée les ressources suivantes :

Configuration

Étape 1 : cloner le référentiel d'échantillons

Exécutez les commandes suivantes pour cloner le référentiel et accéder au répertoire du projet :

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

Étape 2 : installer les dépendances

Exécutez la commande suivante pour installer les dépendances du projet :

npm install

Partie 1 : Déploiement de l'espace agent

Dans cette section, vous créez l'espace agent, les rôles IAM, l'application opérateur et une AWS association dans votre compte de surveillance.

Étape 1 : Configuration de l'identifiant du compte de surveillance

Ouvrez lib/constants.ts et définissez l'identifiant de votre compte de surveillance :

L'exemple suivant montre la constante à mettre à jour :

export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";

Étape 2 : Bootstrap AWS environnement CDK

Si vous n'avez pas démarré le AWS CDK dans votre compte de surveillance, exécutez la commande suivante :

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

Étape 3 : Création et déploiement

Exécutez les commandes suivantes pour créer le TypeScript code et déployer la pile :

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Étape 4 : Enregistrez les sorties de la pile

Une fois le déploiement terminé, le AWS CDK imprime les sorties de la pile. Enregistrez ces valeurs pour une utilisation ultérieure.

L'exemple suivant montre le résultat attendu :

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

Si vous prévoyez de terminer la partie 2, enregistrez la AgentSpaceArn valeur. Vous en avez besoin pour configurer la pile de comptes de service.

La pile produit l'ARN de l'espace agent, et non l'ID de l'espace agent. Les étapes suivantes demandent l'ID, qui est le segment suivant agentspace/ dans l'ARN. Dans l'exemple précédent, l'ARN se termine paragentspace/abc123, donc l'ID de l'espace agent estabc123. Enregistrez également cette valeur.

Étape 5 : vérifier le déploiement

Pour vérifier que l'espace agent a été créé correctement, exécutez la commande AWS CLI suivante :

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

À ce stade, votre espace agent est déployé avec l'application opérateur activée et votre compte de surveillance associé. L'agent peut surveiller les problèmes liés à ce compte.

Partie 2 (Facultatif) : Ajouter une surveillance multi-comptes

Dans cette section, vous allez étendre la configuration afin que votre espace agent puisse surveiller les ressources d'un second AWS compte (le compte de service). Cela implique deux actions :

Étape 1 : configurer l'ID du compte de service

Ouvrez lib/constants.ts et définissez l'identifiant de votre compte de service :

L'exemple suivant montre la constante à mettre à jour :

export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";

DevOpsAgentStack Crée une AWS association source à l'aide de cet ID de compte. Si vous l'avez déployé DevOpsAgentStack avant de définir cette valeur, redéployez-le pour créer l'association :

Exécutez les commandes suivantes pour redéployer :

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Étape 2 : définir l'ARN de l'espace agent

Copiez la AgentSpaceArn valeur de la DevOpsAgentStack sortie (partie 1, étape 4) et définissez-la dans lib/constants.ts :

L'exemple suivant montre la constante à mettre à jour :

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

ServiceStack Utilise cette valeur pour définir la politique de confiance sur le rôle du compte secondaire. Le n' ServiceStack est synthétisé que lorsque cette valeur est définie.

Étape 3 : Bootstrap le compte de service

Si vous n'avez pas démarré le AWS CDK dans votre compte de service, exécutez la commande suivante :

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

Étape 4 : Déployez le ServiceStack

Exécutez les commandes suivantes pour créer et déployer le ServiceStack en utilisant les informations d'identification du compte de service :

npm run build
cdk deploy ServiceStack --profile service

Cela crée les ressources suivantes dans le compte de service :

Étape 5 : vérifier le déploiement

Pour vérifier que la fonction Lambda a été correctement déployée, exécutez les commandes suivantes pour tester le service echo :

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

Partie 3 (Facultatif) : Ajouter une compétence, un agent personnalisé et un déclencheur programmé

Dans cette section, vous ajoutez trois ressources à l'espace agent que vous avez créé dans la partie 1. Vous ajoutez une compétence que l'agent charge le cas échéant et un agent personnalisé qui définit l'agent pour un flux de travail spécifique. Vous ajoutez également un déclencheur programmé qui exécute automatiquement l'agent personnalisé. Ces ressources utilisent les CfnTrigger constructions CfnAsset et du aws-cdk-lib/aws-devopsagent module.

Ces ressources peuvent entraîner des frais supplémentaires sur votre AWS compte. Pour les supprimer lorsque vous avez terminé, suivez la section Nettoyage à la fin de ce guide.

Cet exemple utilise les types custom_agent d'actifs skill et. La même CfnAsset structure crée tous les types d'actifs, tels que memory_storeagents_md, et. attachment Pour utiliser un autre type, modifiez la assetType propriété et fournissez les métadonnées requises par ce type. Pour obtenir la liste complète des types de ressources, leurs métadonnées requises et la référence de propriété, consultezGestion des ressources.

Étape 1 : Création de la pile de contenu

Créez un fichier nommé lib/content-stack.ts avec les contenus suivants. L'action d'un déclencheur basé sur le temps fait référence à l'agent personnalisé par ID d'actif, dans le formulairecustom:<assetId>. La pile connecte automatiquement cette référence en utilisant la valeur de l'attrAssetIdattribut de l'agent personnalisé. La skills liste des agents personnalisés prend également des identifiants d'actifs plutôt que des noms, elle utilise donc ceux des compétencesattrAssetId. Cela confère également à la pile une dépendance implicite, de sorte que la compétence est créée avant l'agent qui l'attache.

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

Étape 2 : Ajoutez la pile à votre AWS Appli CDK

Dans le point d'entrée de votre application (par exemplebin/app.ts), instanciez la pile et transmettez l'identifiant de l'espace agent que vous avez enregistré dans la partie 1, étape 4. Utilisez l'identifiant, tel queabc123, et non la AgentSpaceArn valeur complète :

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

Étape 3 : Déploiement de la pile

Exécutez les commandes suivantes pour créer et déployer la pile à l'aide des informations d'identification du compte de surveillance :

npm run build
cdk deploy ContentStack --profile monitoring

Les assetType propriétés agentSpaceId et d'un actif sont réservées à la création, tout comme les action propriétésagentSpaceId, typecondition, et d'un déclencheur. La modification de l'un d'entre eux remplace la ressource. Vous pouvez mettre à jour le déclencheur status (ActiveouInactive) en place, en le configurant Inactive pour le suspendre sans le supprimer. Pour plus d'informations sur les autres types d'actifs et la référence complète des propriétés, consultezGestion des ressources.

Étape 4 : vérifier le déploiement

Pour confirmer que les actifs et le déclencheur ont été créés, exécutez les commandes AWS CLI suivantes :

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>

Résolution des problèmes

Cette section décrit les problèmes courants et explique comment les résoudre.

CfnAssetou n'CfnTriggerest pas exporté depuis aws-cdk-lib/aws-devopsagent

CloudFormation type de ressource introuvable

La création du rôle IAM a échoué

Cross-account le déploiement échoue avec le message « Impossible d'assumer le rôle dans le compte cible »

Délais de propagation IAM

Nettoyage

Pour retirer toutes les ressources, détruisez les piles dans l'ordre inverse.

Exécutez les commandes suivantes pour détruire les piles :

# 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

Avertissement : Cette action supprime définitivement votre espace agent et toutes les données associées. Cette action ne peut être annulée. Assurez-vous d'avoir sauvegardé toutes les informations importantes avant de continuer.

Considérations sur la sécurité

Étapes suivantes

Après avoir déployé votre AWS DevOps agent à l'aide du AWS CDK :

Ressources supplémentaires