Panoramica di Prerequisiti Cosa copre questa guida Parte 1: Distribuzione dello spazio per gli agenti Parte 2 (opzionale): aggiungere il monitoraggio su più account Parte 3: aggiungi un'abilità, un agente personalizzato e un trigger pianificato Verifica Risoluzione dei problemi Pulizia Fasi successive

Nozioni di base su AWS DevOps Agente che utilizza AWS CloudFormation

Panoramica di

Questa guida mostra come utilizzare i AWS CloudFormation modelli per creare e distribuire le risorse AWS DevOps dell'agente. I modelli automatizzano la creazione di uno spazio agente, dei ruoli IAM ( AWS Identity and Access Management), di un'app per operatori e delle associazioni di AWS account sotto forma di infrastruttura come codice.

L' CloudFormation approccio automatizza i passaggi manuali descritti nella guida all'onboarding della CLI definendo tutte le risorse richieste in modelli YAML dichiarativi.

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

Prerequisiti

Prima di iniziare, assicurati di disporre di:

AWS Interfaccia a riga di comando (AWS CLI) installata e configurata con le credenziali appropriate
Autorizzazioni per creare ruoli e stack IAM CloudFormation
Un AWS account per l'account di monitoraggio (primario)
(Facoltativo) Un secondo AWS account se desideri configurare il monitoraggio tra più account

Cosa copre questa guida

Questa guida è suddivisa nelle seguenti parti:

Parte 1: implementa uno spazio per agenti con un'app per operatori e un' AWS associazione nel tuo account di monitoraggio. Dopo aver completato questa parte, l'agente può monitorare i problemi relativi a quell'account.
Parte 2 (opzionale): distribuisci un ruolo IAM su più account in un account secondario e aggiungi un'associazione di origine AWS . Questa configurazione consente allo spazio degli agenti di monitorare le risorse tra gli account.
Parte 3 (opzionale): aggiungi un'abilità, un agente personalizzato e un trigger pianificato allo spazio degli agenti, in modo che l'agente abbia conoscenze personalizzate ed esegua un agente personalizzato in base a una pianificazione.

Parte 1: Distribuzione dello spazio per gli agenti

In questa sezione, crei un CloudFormation modello che fornisce lo spazio dell'agente, i ruoli IAM, l'app dell'operatore e un' AWS associazione nel tuo account di monitoraggio.

Fase 1: Creare il CloudFormation modello

Salva il seguente modello con nomedevops-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

Fase 2: Distribuisci lo stack

Esegui il seguente comando per distribuire lo stack. Sostituisci <REGION> con un Regioni supportate (ad esempio,us-east-1).


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

Fase 3: Registrare gli output dello stack

Al termine della distribuzione, esegui il seguente comando per recuperare gli output dello stack. Registra questi valori per un uso successivo.


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

L'esempio seguente mostra l'output previsto:


[
  {
    "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 intendete completare la parte 2, salvate il AgentSpaceArn valore. Ti serve per configurare il ruolo tra più account.

Passaggio 4: 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:

Implementazione di un ruolo IAM nell'account di servizio che considera attendibile lo spazio dell'agente.
Aggiungere un' AWS associazione di origine nell'account di monitoraggio che punti all'account del servizio.

È necessario completare la Parte 1 prima di procedere. Il modello di account di servizio richiede AgentSpaceArn gli output dello stack della Parte 1.

Fase 1: Creare il modello di account di servizio

Salva il seguente modello comedevops-agent-service-account.yaml. Questo modello crea un ruolo IAM per più account nell'account secondario.


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

Fase 2: Implementa lo stack di account di servizio

Utilizzando le credenziali per l'account di servizio, esegui il comando seguente:


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>

Passaggio 3: aggiungere la fonte AWS associazione

Torna all'account di monitoraggio e crea un' AWS associazione di origine. Puoi farlo creando uno stack separato o aggiornando il modello originale. L'esempio seguente utilizza un modello autonomo.

Salva il seguente modello con nome: 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

Distribuisci lo stack di associazione utilizzando le credenziali dell'account di monitoraggio:


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: aggiungi un'abilità, un agente personalizzato e un trigger pianificato

Questa parte è facoltativa. In questa sezione, aggiungi tre risorse allo spazio agente creato nella Parte 1. La prima è un'abilità che l'agente carica quando pertinente. Il secondo è un agente personalizzato che assegna l'agente a un flusso di lavoro specifico. Il terzo è un trigger pianificato che esegue automaticamente l'agente personalizzato. Queste risorse utilizzano i tipi di AWS::DevOpsAgent::Trigger risorse AWS::DevOpsAgent::Asset e. Per ulteriori informazioni sulla gestione delle risorse come infrastruttura come codice, vedereGestione delle risorse.

È necessario completare la Parte 1 prima di procedere. Questo modello richiede gli AgentSpaceId output dello stack della Parte 1.

Fase 1: Creare il modello

Salva il seguente modello con nomedevops-agent-content.yaml. L'azione di un trigger basata sul tempo fa riferimento all'agente personalizzato in base all'ID della risorsa, nel modulocustom:<assetId>. Il modello lo collega automaticamente aFn::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

Fase 2: Distribuisci lo stack

Utilizzando le credenziali dell'account di monitoraggio, esegui il seguente comando. Sostituisci <AGENT_SPACE_ID> con il valore degli output della Parte 1.


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

Le Action proprietàAgentSpaceId, TypeCondition, e sono di sola creazione. 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

Verifica

Verificate la configurazione eseguendo i seguenti comandi 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>

Risoluzione dei problemi

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

CloudFormation tipo di risorsa non trovato

Verifica di eseguire la distribuzione in unRegioni supportate.
Verifica che la tua AWS CLI sia configurata con le autorizzazioni appropriate.

Creazione del ruolo IAM non riuscita

Verifica che le tue credenziali di distribuzione dispongano delle autorizzazioni per creare ruoli IAM con nomi personalizzati (). CAPABILITY_NAMED_IAM
Verifica che le condizioni della politica di fiducia corrispondano all'ID del tuo account.

Cross-account la distribuzione non riesce

Ogni stack deve essere distribuito con le credenziali per l'account di destinazione. Usa il --profile flag per specificare il profilo AWS CLI corretto.
Verifica che il AgentSpaceArn parametro corrisponda all'ARN esatto degli output dello stack della Parte 1.

Ritardi di propagazione IAM

La propagazione delle modifiche ai ruoli IAM può richiedere alcuni minuti. Se la creazione dello spazio dell'agente fallisce subito dopo la creazione del ruolo, attendi qualche minuto e ridistribuisci.

Pulizia

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

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.

Eseguite i seguenti comandi per eliminare gli stack:


# 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>

Fasi successive

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

Per connettere integrazioni aggiuntive, consulta. Configurazione di integrazioni e conoscenze
Se registri un'integrazione di terze parti, ottieni l'URL e il segreto del webhook ruotando il webhook nella console. AWS CloudFormation non restituisce il segreto del webhook come output dello stack, perché è sensibile. Per istruzioni sulla gestione delle credenziali webhook, vedi Gestione delle credenziali webhook.
Per saperne di più sulle competenze e le capacità degli agenti, consulta. DevOps Competenze degli agenti
Per ulteriori informazioni sulla gestione delle competenze, degli agenti personalizzati e di altre risorse come infrastruttura come codice, consultaGestione delle risorse.
Per informazioni sull'app web per gli operatori, consultaChe cos'è un' DevOps Agent Web App?.
Per riferimenti dettagliati alle proprietà per i tipi di CloudFormation risorse utilizzati in questa guida, vedere Riferimento al tipo di risorsa AWS DevOps dell'agente nel Riferimento del AWS CloudFormation modello.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Nozioni di base su AWS DevOps Agente che utilizza AWS CDK

Nozioni di base su AWS DevOps Agente che utilizza Terraform