Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Erste Schritte mit AWS DevOps Agent, der Terraform verwendet

-Übersicht

Dieses Handbuch zeigt Ihnen, wie Sie Terraform zum Erstellen und Bereitstellen von Agentenressourcen verwenden. AWS DevOps Die Terraform-Konfiguration automatisiert die Erstellung eines Agentenbereichs, von IAM-Rollen, einer Operator-App und Kontozuordnungen. AWS

Der Terraform-Ansatz automatisiert die im CLI-Onboarding-Leitfaden beschriebenen manuellen Schritte, indem alle erforderlichen Ressourcen als Infrastruktur in Form von Code definiert werden.

AWS DevOps Der Agent ist in den folgenden 6 AWS Regionen verfügbar: USA Ost (Nord-Virginia), USA West (Oregon), Asien-Pazifik (Sydney), Asien-Pazifik (Tokio), Europa (Frankfurt) und Europa (Irland). Weitere Informationen zu den unterstützten Regionen finden Sie unterUnterstützte Regionen.

Voraussetzungen

Stellen Sie vor dem Beginn sicher, dass Sie über das Folgende verfügen:

Was in diesem Handbuch behandelt wird

Dieses Handbuch ist in vier Teile gegliedert:

Ressourcen wurden erstellt

Teil 1: Überwachungskonto

Teil 2: Dienstkonto (optional)

Teil 4: Ressourcen und Trigger (optional)

Diese Konfiguration erstellt die folgenden Ressourcen:

Einrichtung

Schritt 1: Klonen Sie das Beispiel-Repository

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

Schritt 2: Variablen konfigurieren

Kopieren Sie die Beispielvariablendatei und passen Sie sie an Ihre Umgebung an:

cp terraform.tfvars.example terraform.tfvars

Bearbeiten Sie sie terraform.tfvars mit Ihrem Agentenbereichsnamen und einer Beschreibung:

agent_space_name        = "MyCompanyAgentSpace"
agent_space_description = "DevOps Agent Space for monitoring production workloads"

Teil 1: Stellen Sie den Agentenbereich bereit

In diesem Abschnitt erstellen Sie den Agentenbereich, die IAM-Rollen, die Operator-App und eine AWS Verknüpfung in Ihrem Überwachungskonto.

Schritt 1: Automatisierte Bereitstellung (empfohlen)

Verwenden Sie das mitgelieferte Bereitstellungsskript für eine optimierte Einrichtung:

./deploy.sh

Dieses Skript automatisch:

Alternativ, wenn Sie eine manuelle Steuerung bevorzugen:

terraform init
terraform plan
terraform apply

Geben Sie einyes, wenn Sie aufgefordert werden, die Bereitstellung zu bestätigen.

Schritt 2: Notieren Sie die Ausgaben

Nach Abschluss der Bereitstellung druckt Terraform die Ausgaben. Notieren Sie sich diese Werte für die spätere Verwendung:

Outputs:
agent_space_id              = "abc123"
agent_space_arn             = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/abc123"
agent_space_name            = "MyCompanyAgentSpace"
devops_agentspace_role_arn  = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace-a1b2c3d4"
devops_operator_role_arn    = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin-a1b2c3d4"
primary_account_id          = "<MONITORING_ACCOUNT_ID>"
primary_account_association_id = "assoc-xyz"

Wenn Sie Teil 2 abschließen möchten, speichern Sie den agent_space_arn Wert. Sie benötigen ihn, um die Ressourcen des Dienstkontos zu konfigurieren.

Schritt 3: Überprüfen Sie die Bereitstellung

Führen Sie das Verifizierungsskript nach der Bereitstellung aus:

./post-deploy.sh

Oder überprüfen Sie mithilfe der AWS CLI, ob der Agentenbereich erfolgreich erstellt wurde:

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

Zu diesem Zeitpunkt wird Ihr Agentenbereich bereitgestellt, wobei die Operator-App aktiviert und Ihr Überwachungskonto verknüpft ist. Der Agent kann Probleme in diesem Konto überwachen.

Teil 2 (optional): Fügen Sie eine kontoübergreifende Überwachung hinzu

In diesem Abschnitt erweitern Sie das Setup, sodass der Agentenbereich Ressourcen in einem zweiten AWS Konto (dem Dienstkonto) überwachen kann. Dies beinhaltet zwei Aktionen:

Schritt 1: Konfigurieren Sie die Dienstkonto-ID

Stellen Sie terraform.tfvars unter Ihre Dienstkonto-ID ein:

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

Schritt 2: Stellen Sie den ARN für den Agentenbereich ein

Kopieren Sie den agent_space_arn Wert aus der Ausgabe von Teil 1 (Schritt 2) und geben Sie ihn einterraform.tfvars:

agent_space_arn = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>"

Die Ressourcen des Dienstkontos verwenden diesen Wert, um die Vertrauensrichtlinie für die sekundäre Kontorolle festzulegen. Diese Ressourcen werden nur erstellt, wenn dieser Wert festgelegt ist.

Schritt 3: Konfigurieren Sie den Anbieter `aws.service`

Konfigurieren Sie unter main.tf den aws.service Anbieter-Alias mit Anmeldeinformationen für das Dienstkonto. Sie können entweder ein benanntes Profil verwenden oder eine Rolle übernehmen:

Ein Profil verwenden:

provider "aws" {
  alias   = "service"
  region  = var.aws_region
  profile = "your-service-account-profile"
}

Oder indem Sie die Rolle übernehmen verwenden:

provider "aws" {
  alias  = "service"
  region = var.aws_region
  assume_role {
    role_arn = "arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/OrganizationAccountAccessRole"
  }
}

Schritt 4: Bereitstellen

Wenden Sie die aktualisierte Konfiguration an:

terraform apply

Dadurch werden die folgenden Ressourcen im Dienstkonto erstellt:

Es erstellt auch eine AWS Quellzuordnung im Überwachungskonto, die das Dienstkonto verknüpft.

Schritt 5: Überprüfen Sie die Bereitstellung

Testen Sie den Echo-Dienst, um sicherzustellen, dass die Lambda-Funktion erfolgreich bereitgestellt wurde:

aws lambda invoke \
  --function-name echo-service-tf \
  --payload '{"test": "hello world"}' \
  --profile <your-service-account-profile> \
  --region <REGION> \
  response.json
cat response.json

Teil 3 (optional): Integrationen von Drittanbietern registrieren

In diesem Abschnitt registrieren Sie externe Dienste (Dynatrace, Splunk ServiceNow, New Relic,,) im Agentenbereich. GitLab PagerDuty Diese Integrationen ermöglichen es dem AWS DevOps Agenten, während der Ermittlungen auf Telemetrie-, Vorfalldaten- und Quellenkontrollinformationen zuzugreifen.

Im Gegensatz zum AWS CDK-Beispiel, für das eine separate IntegrationsStack Phase und manuelle Verkabelung der Agentenbereichs-ID erforderlich ist, verweisen diese Ressourcen direkt auf den Agentenbereich und können terraform apply wie Teil 1 eingesetzt werden.

Unterstützte Integrationen

Schritt 1: Anmeldedaten für die Integration konfigurieren

Fügen Sie einen integrations Block terraform.tfvars hinzu und füllen Sie nur die gewünschten Dienste aus. Das folgende Beispiel zeigt eine Dynatrace-Integration:

integrations = {
  dynatrace = {
    account_urn   = "<DYNATRACE_ACCOUNT_URN>"
    client_id     = "<DYNATRACE_CLIENT_ID>"
    client_name   = "<DYNATRACE_CLIENT_NAME>"
    client_secret = "<DYNATRACE_CLIENT_SECRET>"
    env_id        = "<DYNATRACE_ENVIRONMENT_ID>"
    resources     = ["<DYNATRACE_RESOURCE_1>"]
  }
}

Die vollständige Form jeder Integration finden Sie terraform.tfvars.example im Beispiel-Repository.

ServiceNow Anforderung: Geben Sie immer instance_id explizit den kurzen Instanznamen an (z. B. "ven04972" — nicht den vollständigeninstance_url). Wenn instance_id es weggelassen wird, wird auf die Verknüpfung zurückgegriffeninstance_url, was die DevOps Agenten-API mit einem 400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance ablehnt.

Sicherheit: Die integrations Variable ist markiertsensitive, sodass ihre Werte aus der Plan- und Applice-Ausgabe entfernt werden. Übergeben Sie keine echten Anmeldeinformationen anterraform.tfvars. Für Produktionszwecke sollten Sie Secrets aus AWS Secrets Manager oder AWS Systems Manager Parameter Store beziehen (z. B. mithilfe von data Quellen) und nicht aus Klartext.

Schritt 2: Bereitstellen

Wenden Sie die Konfiguration an:

terraform apply

Dadurch wird eine Serviceregistrierung und -zuordnung für jede aktivierte Integration erstellt.

Schritt 3: Überprüfen Sie die Ausgaben

Nach Abschluss der Bereitstellung ordnen die Integrationsausgaben jeden aktivierten Dienst seinen registrierten IDs zu:

integration_service_ids = {
  "dynatrace" = "service-abc123"
}
integration_association_ids = {
  "dynatrace" = "assoc-xyz789"
}

Weitere Informationen zur Konfiguration der Anmeldeinformationen für jeden Dienst finden Sie unter:

Teil 4 (optional): Fügen Sie einen Skill, einen benutzerdefinierten Agenten und einen geplanten Trigger hinzu

In diesem Abschnitt fügen Sie dem Agentenbereich, den Sie in Teil 1 erstellt haben, drei Ressourcen hinzu. Sie fügen einen Skill hinzu, den der Agent bei Bedarf lädt, und einen benutzerdefinierten Agenten, der den Agenten einem bestimmten Workflow zuordnet. Sie fügen auch einen geplanten Trigger hinzu, der den benutzerdefinierten Agenten automatisch ausführt. Diese Ressourcen verwenden die awscc_devopsagent_trigger Ressourcen awscc_devopsagent_asset und.

Für diese Ressourcen können zusätzliche Gebühren auf Ihrem AWS Konto anfallen. Um sie zu entfernen, wenn Sie fertig sind, folgen Sie dem Abschnitt Bereinigung am Ende dieser Anleitung.

In diesem Beispiel werden die custom_agent Assettypen skill und verwendet. Dieselbe awscc_devopsagent_asset Ressource erstellt jeden Asset-Typ, z. B. memory_storeagents_md, und. attachment Um einen anderen Typ zu verwenden, ändern Sie das asset_type Argument und geben Sie die Metadaten an, die dieser Typ benötigt. Die vollständige Liste der Asset-Typen, der erforderlichen Metadaten und die Eigenschaftsreferenz finden Sie unterVerwaltung von Komponenten.

Schritt 1: Fügen Sie die Konfiguration hinzu

Erstellen Sie eine Datei mit dem Namen assets.tf und dem folgenden Inhalt. Die Aktion eines zeitbasierten Triggers referenziert den benutzerdefinierten Agenten anhand der Asset-ID im Formularcustom:<assetId>. Die Konfiguration leitet dies automatisch vom asset_id Attribut des benutzerdefinierten Agenten ab. Die skills Liste des benutzerdefinierten Agenten verwendet auch Asset-IDs statt Namen, sodass sie auf das asset_id Attribut des Skills verweist. Dadurch erhält Terraform auch eine implizite Abhängigkeit, sodass der Skill vor dem Agenten erstellt wird, der ihn anhängt.

Beachten Sie, dass es sich bei den action Argumenten metadata und um JSON-Dokumente handelt, die als Zeichenfolgen übergeben werden. Daher wird in diesem Beispiel Folgendes verwendet. jsonencode

variable "agent_space_id" {
  type        = string
  description = "The agent space ID from the Part 1 output"
}

# A skill the agent loads when relevant
resource "awscc_devopsagent_asset" "example_skill" {
  agent_space_id = var.agent_space_id
  asset_type     = "skill"

  metadata = jsonencode({
    name        = "rds-performance-investigation"
    description = "Investigation procedures for RDS performance issues."
    agent_types = ["GENERIC"]
  })

  files = [{
    path         = "SKILL.md"
    content_text = <<-EOT
      # RDS Performance Investigation
      Use this skill when investigating database latency, connection
      errors, or query timeouts.
    EOT
  }]
}

# A custom agent with attached skills that a trigger can invoke
resource "awscc_devopsagent_asset" "example_custom_agent" {
  agent_space_id = var.agent_space_id
  asset_type     = "custom_agent"

  metadata = jsonencode({
    name   = "rds-firefighter"
    skills = [awscc_devopsagent_asset.example_skill.asset_id]
  })

  files = [{
    path         = "AGENT.md"
    content_text = <<-EOT
      # RDS Firefighter
      Custom agent for RDS incidents.
    EOT
  }]
}

# A time-based trigger that runs the custom agent on a schedule
resource "awscc_devopsagent_trigger" "daily" {
  agent_space_id = var.agent_space_id
  type           = "TIME_BASED"

  condition = {
    schedule = {
      expression = "rate(1 day)"
    }
  }

  action = jsonencode({
    actionType = "create:task"
    task = {
      agent = "custom:${awscc_devopsagent_asset.example_custom_agent.asset_id}"
    }
  })

  status = "Active"
}

output "skill_asset_id" {
  description = "The skill asset ID"
  value       = awscc_devopsagent_asset.example_skill.asset_id
}

output "custom_agent_asset_id" {
  description = "The custom agent asset ID"
  value       = awscc_devopsagent_asset.example_custom_agent.asset_id
}

output "trigger_id" {
  description = "The trigger ID"
  value       = awscc_devopsagent_trigger.daily.trigger_id
}

Wenn Sie dies zum Beispiel-Repository hinzufügen, können Sie direkt auf die Ressource für den Agentenbereich verweisen, anstatt die agent_space_id Variable zu deklarieren.

Schritt 2: Bereitstellen

Geben Sie die Agenten-Space-ID ein terraform.tfvars und verwenden Sie agent_space_id dabei den Wert aus der Ausgabe von Teil 1:

agent_space_id = "<AGENT_SPACE_ID>"

Wenden Sie die Konfiguration an:

terraform apply

Die asset_type Argumente agent_space_id und eines Assets können nur erstellt werden, ebenso wie die action Argumenteagent_space_id, typecondition, und eines Triggers. Wenn Sie einen von ihnen ändern, wird die Ressource ersetzt. Sie können den Trigger status (ActiveoderInactive) an Ort und Stelle aktualisieren. Stellen Sie ihn auf ein, um den Trigger Inactive anzuhalten, ohne ihn zu löschen.

Schritt 3: Überprüfen Sie die Bereitstellung

Führen Sie die folgenden AWS CLI-Befehle aus, um zu bestätigen, dass die Assets und der Trigger erstellt wurden:

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>

Verwenden vorhandener IAM-Rollen (optional)

Standardmäßig erstellt die Terraform-Konfiguration neue IAM-Rollen für den Agentenbereich und die Operator-App. Wenn Sie bereits über IAM-Rollen mit den erforderlichen Richtlinien verfügen, können Sie die Rollenerstellung überspringen und stattdessen die vorhandenen Rollen-ARNs angeben.

Voraussetzungen

Die vorhandenen Rollen müssen die folgenden Anforderungen erfüllen:

Rolle „Agent Space“

Rolle „Operator-App“

Konfiguration

Legen Sie terraform.tfvars unter eine oder beide Rollen-ARNs fest:

existing_agentspace_role_arn = "arn:aws:iam::ACCOUNT_ID:role/YourAgentSpaceRole"
existing_operator_role_arn   = "arn:aws:iam::ACCOUNT_ID:role/YourOperatorRole"

Wenn diese Werte festgelegt sind, werden die entsprechenden Rollenressourcen iam.tf übersprungen. Dieser Ansatz ist vollständig abwärtskompatibel — bestehende Konfigurationen mit leeren Werten (Standardeinstellung) behalten das aktuelle Verhalten bei der Rollenerstellung bei.

Fehlerbehebung

Verzögerungen bei der IAM-Übertragung

ServiceNow instanceId does not matchFehler

Verband Dynatrace status: invalid

Fehler bei der Genehmigung

Cross-account Die Bereitstellung schlägt fehl

Der Terraform-Ressourcentyp wurde nicht gefunden

Bereinigen

Wenn Sie Teil 4 abgeschlossen haben, entfernen Sie zuerst den Skill, den benutzerdefinierten Agenten und den Trigger. Im Gegensatz zum AWS CDK-Handbuch, in dem diese Ressourcen in einem separaten Stapel zusammengefasst werden, assets.tf ist es Teil derselben Terraform-Konfiguration, sodass einfach der Agentenbereich zusammen mit ihnen terraform destroy entfernt wird. Löschen Sie die Änderung assets.tf und wenden Sie sie an, um nur die Ressourcen von Teil 4 zu entfernen:

rm assets.tf
terraform apply

Um die Datei zu behalten, zielen Sie stattdessen auf die drei Ressourcen ab:

terraform destroy \
  -target=awscc_devopsagent_trigger.daily \
  -target=awscc_devopsagent_asset.example_custom_agent \
  -target=awscc_devopsagent_asset.example_skill

Wenn Sie nur diese Ressourcen entfernen, bleibt der Agentenbereich intakt. Tun Sie dies, wenn Sie Teil 4 auf einen Agentenbereich angewendet haben, den Sie mit anderen teilen oder den Sie nicht in Teil 1 erstellt haben.

Um dann alles andere zu entfernen, zerstöre es in umgekehrter Reihenfolge, wenn du Teil 2 eingesetzt hast:

./cleanup.sh

Oder manuell:

terraform destroy

Warnung: Dadurch werden Ihr Agentenbereich und alle zugehörigen Daten dauerhaft gelöscht. Stellen Sie sicher, dass Sie alle wichtigen Informationen gesichert haben, bevor Sie fortfahren.

Sicherheitsüberlegungen

Nächste Schritte

Nachdem Sie Ihren AWS DevOps Agenten mit Terraform bereitgestellt haben:

Weitere Ressourcen