本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Terraform 開始使用 AWS DevOps 代理程式

概觀

本指南說明如何使用 Terraform 來建立和部署 AWS DevOps 代理程式資源。Terraform 組態會自動建立代理程式空間、IAM 角色、運算子應用程式和 AWS 帳戶關聯。

Terraform 方法透過將所有必要資源定義為基礎設施作為程式碼，自動執行 CLI 入門指南中所述的手動步驟。

AWS DevOps 代理程式可在下列 6 AWS 區域使用：美國東部 （維吉尼亞北部）、美國西部 （奧勒岡）、亞太區域 （雪梨）、亞太區域 （東京）、歐洲 （法蘭克福） 和歐洲 （愛爾蘭）。如需支援區域的詳細資訊，請參閱 支援的區域。

先決條件

開始前，請確定您具有下列項目：

本指南涵蓋的內容

本指南分為四個部分：

已建立資源

第 1 部分：監控帳戶

第 2 部分：服務帳戶 （選用）

第 4 部分：資產和觸發條件 （選用）

此組態會建立下列資源：

設定

步驟 1：複製範例儲存庫

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

步驟 2：設定變數

複製範例變數檔案，並針對您的環境進行自訂：

cp terraform.tfvars.example terraform.tfvars

terraform.tfvars 使用您的客服人員空間名稱和描述進行編輯：

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

第 1 部分：部署代理程式空間

在本節中，您會在監控帳戶中建立代理程式空間、IAM 角色、運算子應用程式和 AWS 關聯。

步驟 1：使用自動化部署 （建議）

使用提供的部署指令碼進行簡化設定：

./deploy.sh

此指令碼會自動：

或者，如果您偏好手動控制：

terraform init
terraform plan
terraform apply

出現提示yes時輸入 以確認部署。

步驟 2：記錄輸出

部署完成後，Terraform 會列印輸出。記錄這些值以供日後使用：

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"

如果您打算完成第 2 部分，請儲存該agent_space_arn值。您需要它來設定服務帳戶資源。

步驟 3：驗證部署

執行部署後驗證指令碼：

./post-deploy.sh

或使用 AWS CLI 來驗證已成功建立代理程式空間：

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

此時，您的代理程式空間會在啟用 運算子應用程式且您的監控帳戶相關聯的情況下部署。代理程式可以監控此帳戶中的問題。

第 2 部分 （選用）：新增跨帳戶監控

在本節中，您會擴展設定，讓客服人員空間可以監控第二個 AWS 帳戶 （服務帳戶） 中的資源。這涉及兩個動作：

步驟 1：設定服務帳戶 ID

在 中terraform.tfvars，設定您的服務帳戶 ID：

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

步驟 2：設定客服人員空間 ARN

從第 1 部分輸出複製 agent_space_arn值 （步驟 2)，並在 中設定terraform.tfvars：

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

服務帳戶資源使用此值來限制次要帳戶角色的信任政策範圍。只有在設定此值時，才會建立這些資源。

步驟 3：設定 `aws.service` 供應商

在 中main.tf，使用服務帳戶的登入資料設定aws.service提供者別名。您可以使用具名設定檔或擔任角色：

使用設定檔：

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

或使用擔任角色：

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

步驟 4：部署

套用更新的組態：

terraform apply

這會在服務帳戶中建立下列資源：

它也會在監控帳戶中建立來源 AWS 關聯，以連結服務帳戶。

步驟 5：驗證部署

測試 echo 服務以確認 Lambda 函數已成功部署：

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

第 3 部分 （選用）：註冊第三方整合

在本節中，您會向代理程式空間註冊外部服務 (Dynatrace、ServiceNow、Splunk、New Relic、GitLab、PagerDuty)。這些整合可讓 AWS DevOps 代理程式在調查期間存取遙測、事件資料和來源控制資訊。

與需要單獨的 IntegrationsStack 階段和代理程式空間 ID 手動配線的 AWS CDK 範例不同，這些資源會直接參考代理程式空間，並可部署在第 1 部分terraform apply相同的 中。

支援的整合

步驟 1：設定整合憑證

將 integrations區塊新增至 terraform.tfvars，僅填入您想要的服務。下列範例顯示 Dynatrace 整合：

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>"]
  }
}

如需每個整合的完整形狀，請參閱範例儲存庫terraform.tfvars.example中的 。

ServiceNow 需求：一律instance_id明確設定為簡短執行個體名稱 （例如，"ven04972"— 而非完整 instance_url)。如果省略 instance_id ，則關聯會回復為 instance_url，DevOps Agent API 會使用 拒絕該關聯400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance。

安全性：integrations變數會標記為 sensitive，因此其值會從計劃中修訂並套用輸出。請勿將實際登入資料遞交至 terraform.tfvars。對於生產，來自 AWS Secrets Manager 或 AWS Systems Manager 參數存放區的來源秘密 （例如，使用data來源），而不是純文字。

步驟 2：部署

套用組態：

terraform apply

這會為每個啟用的整合建立服務註冊和關聯。

步驟 3：檢閱輸出

部署完成後，整合輸出會將每個啟用的服務映射至其已註冊IDs：

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

如需為每個服務設定登入資料的詳細資訊，請參閱：

第 4 部分 （選用）：新增技能、自訂代理程式和排程觸發

在本節中，您將三個資源新增至您在第 1 部分中建立的客服人員空間。您可以新增客服人員在相關時載入的技能，以及將客服人員範圍限定為特定工作流程的自訂客服人員。您也可以新增自動執行自訂代理程式的排程觸發。這些資源使用 awscc_devopsagent_asset和 awscc_devopsagent_trigger 資源。

這些資源可能會對您的帳戶產生額外費用 AWS 。若要在完成時將其移除，請遵循本指南結尾的清除區段。

此範例使用 skill和 custom_agent 資產類型。相同的awscc_devopsagent_asset資源會建立每個資產類型，例如 memory_store、 agents_md和 attachment。若要使用不同的類型，請變更 asset_type 引數，並提供 類型所需的中繼資料。如需資產類型的完整清單、其所需的中繼資料和屬性參考，請參閱 管理資產。

步驟 1：新增組態

使用下列內容建立名為 assets.tf 的檔案。以時間為基礎的觸發動作會依資產 ID 參考自訂代理程式，格式為 custom:<assetId>。組態會自動從自訂代理程式的 asset_id 屬性進行路由。自訂代理程式的skills清單也會採用資產 IDs 而非名稱，因此會參考技能的asset_id屬性。這也會為 Terraform 提供隱含相依性，因此技能會在連接它的代理程式之前建立。

請注意， metadata和 action引數是以字串形式傳遞的 JSON 文件，因此此範例使用 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
}

如果您要將此項目新增至範例儲存庫，您可以直接參考客服人員空間資源，而不是宣告agent_space_id變數。

步驟 2：部署

使用第 1 部分輸出中的agent_space_id值terraform.tfvars，在 中設定代理程式空間 ID：

agent_space_id = "<AGENT_SPACE_ID>"

套用組態：

terraform apply

資產的 agent_space_id和 asset_type引數僅限建立，觸發器的 agent_space_id、condition、 type和 action引數也是如此。變更其中任何一個會取代 資源。您可以更新觸發的 status(Active 或 Inactive)，將其設定為 Inactive以暫停觸發，而不將其刪除。

步驟 3：驗證部署

若要確認資產和觸發條件已建立，請執行下列 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>

使用現有的 IAM 角色 （選用）

根據預設，Terraform 組態會為代理程式空間和運算子應用程式建立新的 IAM 角色。如果您已有具有必要政策的 IAM 角色，您可以略過角色建立，並改為提供現有的角色 ARNs。

要求

現有角色必須符合下列要求：

客服人員空間角色

Operator 應用程式角色

組態

在 中terraform.tfvars，設定一個或兩個角色 ARNs：

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

設定這些值時，iam.tf會略過 中對應的角色資源。此方法完全回溯相容 — 具有空值 （預設值） 的現有組態會保留目前的角色建立行為。

疑難排解

IAM 傳播延遲

ServiceNow instanceId does not match錯誤

Dynatrace 關聯 status: invalid

許可錯誤

跨帳戶部署失敗

找不到 Terraform 資源類型

清除

如果您已完成第 4 部分，請先移除技能、自訂代理程式和觸發程序。與將這些資源放在個別堆疊中的 AWS CDK 指南不同， assets.tf是相同 Terraform 組態的一部分，因此純 會terraform destroy移除代理程式空間。刪除assets.tf並套用變更，以僅移除第 4 部分資源：

rm assets.tf
terraform apply

若要保留檔案，請改為以三個資源為目標：

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

僅移除這些資源會使代理程式空間保持不變。如果您將第 4 部分套用到您與他人共用的代理程式空間，或是您在第 1 部分中未建立的代理程式空間，請執行此操作。

若要移除所有其他項目，如果您部署了第 2 部分，請以相反順序銷毀：

./cleanup.sh

或手動：

terraform destroy

警告：這會永久刪除您的客服人員空間和所有相關聯的資料。在繼續之前，請確定您已備份任何重要資訊。

安全考量

後續步驟

使用 Terraform 部署您的 AWS DevOps 代理程式之後：

其他資源