Amazon Q：主控台優先開發者工作坊（ACM 憑證自動續期）

時長： 2 小時
受眾： 專業開發人員、DevOps 工程師、平台工程師、雲端平台建置者
主要 AWS AI 服務： AWS 管理主控台中的 Amazon Q Developer
執行方式： 使用者從 AWS 主控台開始，從主控台側邊面板開啟 Amazon Q，並使用 Amazon Q 來引導進行診斷、修復、驗證、程式碼產生和 Runbook 建立。
目標 AWS 任務： 透過驗證 DNS 紀錄並保留更新的先決條件，還原並強化 AWS Certificate Manager (ACM) 公有憑證的自動更新。

1. 工作坊情境

ACM 中面向正式環境的 SSL/TLS 憑證即將到期。ACM 嘗試了託管更新，但由於 DNS 驗證未完成，導致更新受阻。開發人員已經在 AWS 主控台中，檢視 ACM 憑證詳細資訊頁面。

開發人員沒有先切換到外部文件，而是在 AWS 主控台中開啟 Amazon Q Developer，並將其作為主要 AI 助理，以進行以下操作：

• 了解憑證更新狀態。
• 識別該憑證是否符合 ACM 託管更新的資格。
• 找出遺失的 DNS CNAME 驗證紀錄。
• 在 Route 53 中新增或修復紀錄。
• 驗證 ACM 是否可以自動更新。
• 將主控台驅動的修復轉換為可重複執行的開發人員自動化程式和 Runbook。

這是一個技術工作坊。假設開發人員熟悉 AWS 服務、JSON、AWS CLI、DNS、存取控制和基本指令碼編寫。

2. 開發人員將建置什麼

開發人員將在 Amazon Q Developer 的支援下完成主控台優先的工作流程：

AWS 主控台使用者
  |
  | 從 AWS 主控台開啟 Amazon Q Developer 面板
  v
AWS 主控台中的 Amazon Q Developer
  |
  | 解釋 ACM 更新狀態、資源上下文、CLI 指令以及修復計畫
  v
ACM 憑證詳細資訊頁面
  |
  | 顯示憑證狀態、驗證方法、更新資格以及 CNAME 紀錄
  v
Route 53 託管區域
  |
  | 永久儲存 ACM DNS 驗證 CNAME 紀錄
  v
CloudShell / AWS 主控台動作
  |
  | 執行由 Q 產生並經過清理的驗證與修復指令
  v
Amazon Q 後續行動
  |
  | 審查結果、產生測試、強化檢查清單以及 Runbook

3. 涵蓋的 Amazon Q Developer 功能

本工作坊刻意將重點放在單一 AWS AI 服務：Amazon Q Developer。ACM 和 Route 53 是目標服務，但 Amazon Q 是單一的 AI 骨幹。

4. 有時間限制的 2 小時議程

5. 先決條件

5.1 AWS 主控台存取權限

開發人員需要存取：

• AWS Certificate Manager 主控台。
• Route 53 託管區域主控台。
• 來自同一個主控台工作階段的 AWS CloudShell。
• AWS 主控台中的 Amazon Q Developer 聊天面板。

5.2 工作坊執行的存取權限

使用最低權限存取。工作坊角色應能夠檢查 ACM 憑證狀態、列出相關的 DNS 紀錄、為權威託管區域提交已審查的 DNS 驗證紀錄變更，並輪詢 DNS 變更狀態。

商業邏輯： 工作坊需要 ACM 檢查和 DNS 驗證修復。開發人員不需要管理員存取權限、憑證私鑰存取權限、權限管理權限或應用程式部署權限。ACM 用於發掘驗證需求；Route 53 用於使 DNS 狀態符合 ACM 所需的控制權證明。

程式碼邏輯： 存取權限在唯讀 ACM 檢查和受控 Route 53 DNS 紀錄操作之間分開。憑證檢查步驟會擷取更新中繼資料和驗證紀錄。DNS 變更步驟執行已審查的 CNAME UPSERT。變更輪詢步驟讓開發人員可以等待，直到 Route 53 回報 DNS 變更已同步。

預期結果： 開發人員可以在沒有廣泛帳戶權限的情況下，從 AWS 主控台和 CloudShell 完成實驗室。在正式環境的推出中，將 DNS 寫入權限縮小到權威託管區域，並強制對 DNS 寫入進行同儕審查。

系統設計決策 — 從一開始就採用最低權限

• 安全邊界： 憑證更新修復涉及 DNS 擁有權證明，因此存取權應限制為 ACM 讀取操作和特定的 DNS 區域更新路徑。廣泛的管理員權限會隱藏權限設計問題並增加影響範圍。
• 營運清晰度： 狹窄的存取模型有助於開發人員了解確切的系統相依性：ACM 中繼資料、Route 53 紀錄和變更輪詢。這種清晰度使故障更容易排除，因為被拒絕的操作會直接對應到遺失的工作流程權限。
• 正式環境遷移： 工作坊程式碼通常會變成真正的自動化。從最低權限開始可以防止在將工作流程移入 CI、平台工具或事件 Runbook 時，示範捷徑變成持久的安全債。

6. 預留位置實驗室變數

在文件、螢幕截圖和共用筆記中使用預留位置數值。

export AWS_REGION="<certificate-region>"
export CERTIFICATE_ARN="arn:aws:acm:<region>:<redacted-account>:certificate/<certificate-id>"
export HOSTED_ZONE_ID="<hosted-zone-id>"
export PRIMARY_DOMAIN="<workshop-domain>"
export AWS_PROFILE="default"

商業邏輯： 同一個工作坊必須在多個帳戶和網域中運作，而不暴露客戶資料。預留位置讓開發人員了解數值屬於哪裡，同時保持書面成品的安全以供分享。

程式碼邏輯： 環境變數使 CloudShell 指令可複製且參數化。工作坊後面的指令會使用這些變數，而不是將特定於帳戶的識別碼寫死。

預期結果： 工作坊筆記保持可重複使用。開發人員可以在自己的私人主控台工作階段中取代預留位置數值，但最終的 Markdown、螢幕截圖或拉取請求中不應包含真實的帳戶識別碼。

系統設計決策 — 預留位置優先的工作流程

• 資料最小化： 憑證 ARN、託管區域 ID、網域和 DNS 驗證權杖可能會洩露架構或擁有權資訊。預留位置可減少透過文件、會議聊天、工單和產生的程式碼發生的資料外洩。
• 可重複使用性： 參數化指令可以在不同環境中重複使用。開發人員可以透過變更變數，而不是編輯指令主體，在沙盒、預備環境或正式環境中執行相同的指令模式。
• 可審查性： 審查人員可以檢查邏輯，而不會被客戶特定資料分散注意力。這提高了程式碼審查品質，並防止將敏感識別碼意外複製/貼上到公共儲存庫或支援管道中。

7. AWS Health 電子郵件通知信

需要採取動作：憑證更新信件

通知來源： Amazon Web Services Health 通知
通知類型： 需要採取動作
主旨： 需要採取動作 — 您的憑證更新

AWS Health 事件

需要採取動作 — 您的憑證更新

來自 Amazon Web Services 的問候，

您在 AWS 環境中擁有來自 AWS Certificate Manager 的 SSL/TLS 憑證，該憑證將於 <current-certificate-expiration-utc> 到期。此憑證包含主要 DNS 名稱 <workshop-domain>，總共 <domain-count> 個 DNS 名稱。

AWS 環境：<redacted-account>
AWS 區域名稱：<certificate-region>
憑證識別碼：<certificate-arn>

AWS Certificate Manager (ACM) 無法使用 DNS 驗證自動更新憑證。您必須採取行動以確保更新能在 <current-certificate-expiration-utc> 之前完成。如果憑證未更新且目前憑證到期，您的網站或應用程式可能會變得無法連線。

要更新此憑證，請確保在下方列出的每個 DNS 名稱的權威 DNS 設定中存在所需的 CNAME 紀錄。您可以透過在 ACM 主控台中展開憑證及其 DNS 名稱項目來找到 CNAME 紀錄。您也可以使用 ACM API 中的 DescribeCertificate 操作，或使用 AWS CLI 中的 describe-certificate 操作來尋找憑證的 CNAME 紀錄。

以下 <domain-count> 個 DNS 名稱需要驗證：
<workshop-domain>, <additional-workshop-domain>

如果您對此程序有任何疑問，請透過支援中心聯絡 AWS Support。如果您沒有 AWS 支援計畫，請在 AWS Certificate Manager 討論區發布新討論串。

8. 模組 1 — 開啟 ACM 並向 Amazon Q 詢問上下文

目標

從 AWS 主控台開始，並使用 Amazon Q 在進行變更前了解目前的憑證頁面。

主控台步驟

• 開啟 AWS 管理主控台。
• 前往 AWS Certificate Manager。
• 選擇受影響的公有憑證。
• 從主控台導覽中開啟 Amazon Q 面板。
• 要求 Amazon Q 解釋目前頁面與更新問題。

Amazon Q 提示範例

我正在 AWS Certificate Manager 憑證詳細資訊頁面上。
請解釋我應該檢查什麼，以確認此憑證是否能自動更新。
將重點放在憑證狀態、更新資格、驗證方法、使用中的服務，以及 DNS 驗證 CNAME 紀錄。

預期的 Amazon Q 指引

Amazon Q 應引導開發人員檢查：

• 憑證狀態：ISSUED、EXPIRED 或其他狀態。
• 憑證類型：Amazon 核發與匯入。
• 驗證方法：DNS 驗證與電子郵件驗證。
• 更新資格。
• 更新狀態或更新摘要。
• 網域驗證選項。
• 該憑證是否與 AWS 服務（如 CloudFront、Elastic Load Balancing 或 API Gateway）相關聯。

系統設計決策 — 從主控台上下文開始，而不是指令碼

• 上下文豐富的診斷： AWS 主控台已經顯示憑證狀態、驗證方法和相關中繼資料。從該上下文向 Amazon Q 提問有助於開發人員在執行指令或變更 DNS 之前形成準確的心智模型。
• 降低營運風險： DNS 變更不應是第一個動作。系統可能會因匯入狀態、過期、錯誤區域或遺失服務關聯而受阻。主控台診斷可在修復前縮小原因範圍。
• 開發人員學習： 專業開發人員需要了解控制平面，而不僅僅是複製指令。Amazon Q 的解釋將主控台頁面變成了一個引導式的 ACM、Route 53 和消費服務的系統設計演練。

9. 模組 2 — 要求 Amazon Q 解釋 ACM 託管更新規則

目標

了解 ACM 自動更新所需的契約。

Amazon Q 提示範例

解釋 DNS 驗證公有憑證的 ACM 託管更新。
包含 ACM 何時可以更新、何時無法更新、為何 CNAME 紀錄必須保留在 DNS 中，以及 Route 53 如何融入此程序。

關鍵開發人員筆記

• DNS 驗證使用 ACM 產生的 CNAME 紀錄來證明網域控制權。
• CNAME 紀錄應在核發後保留在 DNS 中，因為 ACM 會重複使用它以進行未來的更新驗證。
• 託管更新適用於符合資格的 Amazon 核發憑證，但不適用於過期或匯入的憑證。
• 與受支援的 AWS 服務相關聯的憑證可以進行更新和部署，無需更改應用程式程式碼。
• 更新後的憑證可保留相同的 ARN，減少應用程式整合工作。

系統設計決策 — 將 DNS 驗證視為期望狀態

• 長期不變量： ACM 驗證 CNAME 不是一次性的設定產物。它是憑證生命週期的持久不變量。平台應像保護任何其他關鍵 DNS 紀錄一樣保護它。
• 職責分離： ACM 擁有憑證生命週期管理，Route 53 擁有 DNS 狀態，而消費服務終止 TLS。開發人員的工作是透過穩定的驗證紀錄讓這些系統保持連接。
• 對自動化友善的模型： 一旦 DNS 驗證正確且憑證符合資格，更新就會成為託管的控制平面操作。這減少了對應用程式部署、自訂憑證輪替程式碼或緊急手動憑證替換的需求。

10. 模組 3 — 使用 Amazon Q 產生安全的 ACM 檢查指令

目標

使用 AWS 主控台中的 CloudShell，僅擷取更新診斷所需的欄位。

Amazon Q 提示範例

產生一個用於 CloudShell 的 AWS CLI 指令，該指令描述一個 ACM 憑證並僅傳回與更新相關的欄位。
使用 CERTIFICATE_ARN 和 AWS_REGION 環境變數。
顯示狀態、類型、更新資格、更新摘要、使用計數，以及網域驗證資源紀錄。

程式碼範例

aws acm describe-certificate \
  --region "$AWS_REGION" \
  --certificate-arn "$CERTIFICATE_ARN" \
  --query '{
    DomainName: Certificate.DomainName,
    Status: Certificate.Status,
    Type: Certificate.Type,
    RenewalEligibility: Certificate.RenewalEligibility,
    RenewalSummary: Certificate.RenewalSummary,
    InUseByCount: length(Certificate.InUseBy),
    DomainValidationOptions: Certificate.DomainValidationOptions[].{
      DomainName: DomainName,
      ValidationStatus: ValidationStatus,
      ResourceRecord: ResourceRecord
    }
  }' \
  --output json

詳細程式碼解釋

商業邏輯： 該指令擷取決定是否必須修復 DNS 紀錄所需的最低憑證狀態。它避免傾印不相關的中繼資料，並降低在終端機輸出中暴露敏感識別碼的機會。

程式碼邏輯： describe-certificate 針對單一憑證呼叫 ACM。--query 運算式將回應投影至以更新為重點的欄位中。InUseByCount 確認憑證是否附加到一個或多個服務，而不會列印出每個完整的服務識別碼。

預期結果： 開發人員會收到一個緊湊的 JSON 文件。如果 ResourceRecord 值存在且驗證狀態不成功，這些 CNAME 紀錄就是 Route 53 驗證的候選項。如果憑證是匯入的、過期的或不符合資格的，團隊應先解決該設計問題，然後再期望進行託管更新。

系統設計決策 — 優先使用查詢投影而非原始 JSON

• 雜訊控制： 原始 ACM 回應可能會很大，並包含對更新決策不必要的識別碼。查詢投影建立了一個針對診斷最佳化的小型營運視圖。
• 減少敏感輸出： 開發人員經常將 CLI 輸出貼上到工單或聊天中。緊湊的查詢減少了將特定於帳戶的資料或不相關的資源識別碼複製到共用系統中的機會。
• 可重複的推理： 相同的投影形狀可以被人類、Amazon Q 後續問題和指令碼使用。這使工作流程具有確定性，且更容易在兩小時的工作坊中進行教學。

11. 模組 4 — 要求 Amazon Q 識別所需的 Route 53 紀錄

目標

將 ACM 驗證紀錄對應到 Route 53 主控台欄位，而不會在共用筆記中暴露真實值。

Amazon Q 提示範例

我有 ACM DomainValidationOptions 輸出，包含 ResourceRecord 名稱、類型和數值。
請解釋如何從 AWS 主控台將這些新增為 Route 53 紀錄。
描述哪部分要放入紀錄名稱、紀錄類型和數值中。

預留位置範例

ACM ResourceRecord 範例：
名稱： _validation-token.<workshop-domain>.
類型： CNAME
數值： _validation-target.acm-validations.aws.

Route 53 紀錄欄位：
紀錄名稱：_validation-token
紀錄類型：CNAME
數值：    _validation-target.acm-validations.aws
路由：    簡單路由
TTL：     300

詳細解釋

商業邏輯： ACM 透過檢查權威 DNS 中是否存在所需的 CNAME 紀錄來更新 DNS 驗證憑證。當 Route 53 是 DNS 供應商時，它會儲存這些紀錄。開發人員必須保留 ACM 提供的確切數值，因為它證明了網域擁有權。

程式碼邏輯： 在此步驟中不執行程式碼。該對應是將 ACM 的完整網域名稱 DNS 紀錄轉換為 Route 53 的主控台格式。Route 53 通常只允許開發人員在所選託管區域內輸入左側紀錄標籤。

預期結果： 開發人員確切知道 ACM 的 ResourceRecord 如何對應到 Route 53 欄位。他們不應在錯誤的託管區域中建立 A 紀錄、TXT 紀錄或 CNAME。他們不應在更新成功後刪除這些紀錄。

系統設計決策 — 僅使用權威託管區域

• DNS 權威性很重要： ACM 針對公有 DNS 進行驗證，而不是針對帳戶中碰巧存在的任何託管區域。如果多個託管區域共用一個名稱，則只有權威區域的紀錄對 ACM 可見。
• 避免虛假成功： 在錯誤的託管區域建立紀錄會使主控台看起來正確，而公有 DNS 卻未改變。這會導致持續的 PENDING_VALIDATION，儘管開發人員認為修復已完成。
• 營運擁有權： 識別權威區域闡明了哪個團隊擁有該修復程序。如果權威 DNS 供應商是外部的或位於另一個 AWS 帳戶中，本機開發人員必須進行協調，而不是在非權威的本機區域中強制進行變更。

12. 模組 5 — 使用 Amazon Q 執行 Route 53 主控台修復

目標

使用在 Amazon Q 引導下的 AWS 主控台操作，新增或修復 ACM DNS 驗證紀錄。

主控台步驟

• 在 AWS 主控台中，開啟 Route 53。
• 開啟 託管區域。
• 選擇憑證網域的權威公有託管區域。
• 選擇 建立紀錄。
• 輸入 ACM 提供的 CNAME 紀錄名稱。
• 選擇 CNAME 作為紀錄類型。
• 輸入 ACM 提供的驗證目標作為數值。
• 使用簡單路由和如 300 秒的 TTL。
• 建立該紀錄。
• 為每個所需的驗證紀錄重複此操作。

Amazon Q 提示範例

引導我從主控台在 Route 53 中建立 ACM DNS 驗證 CNAME 紀錄。
在提交之前，給我一份檢查清單以驗證託管區域權威性、紀錄類型、紀錄名稱、數值、TTL，以及該紀錄是否應永久保留。

與 Amazon Q 一起產生的選用 CloudShell 變更批次

只有在了解主控台修復後，才要求 Amazon Q 產生以下內容。

cat > acm-validation-change-batch.json <<'JSON'
{
  "Comment": "UPSERT ACM DNS validation records for managed renewal readiness",
  "Changes": [
    {
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "_validation-token.<workshop-domain>.",
        "Type": "CNAME",
        "TTL": 300,
        "ResourceRecords": [
          {
            "Value": "_validation-target.acm-validations.aws."
          }
        ]
      }
    }
  ]
}
JSON

aws route53 change-resource-record-sets \
  --hosted-zone-id "$HOSTED_ZONE_ID" \
  --change-batch file://acm-validation-change-batch.json

詳細程式碼解釋

商業邏輯： 變更批次表達了 ACM 驗證所需的 DNS 狀態。使用 UPSERT 是因為如果紀錄已存在但需要更正，此操作應該是安全的。CNAME 紀錄是允許 ACM 完成更新的持久證明。

程式碼邏輯： JSON 檔案定義了一項 Route 53 變更。Action 為 UPSERT，所以如果缺失，Route 53 會建立紀錄，如果存在則更新它。ResourceRecordSet 包含 DNS 名稱、紀錄類型、TTL 和驗證目標。AWS CLI 將該變更提交給託管區域。

預期結果： Route 53 接受變更並傳回變更 ID。在變更達到 INSYNC 後，ACM 最終能透過 DNS 偵測到 CNAME 並繼續進行憑證驗證或更新。ACM 狀態可能不會立即更新。

系統設計決策 — 優先學習主控台，然後指令自動化

• 優先人類理解： 開發人員應在自動化操作之前知道他們正在建立什麼紀錄。主控台引導的修復使 DNS 物件清晰可見且更容易推理。
• 其次指令可重複性： 一旦了解對應關係，變更批次就能用於可重複的修復、同儕審查和 CI/CD。Amazon Q 可以幫助將人類主控台動作轉換為安全的自動化。
• 冪等 DNS 修復： UPSERT 減少了在重複執行和事件還原期間的失敗。DNS 修復應使系統趨向於期望狀態，而不是在部分修復已存在時失敗。

13. 模組 6 — 從 CloudShell 驗證 Route 53 變更狀態

目標

確認 Route 53 已接受並同步了 DNS 紀錄變更。

Amazon Q 提示範例

產生一個 CloudShell 指令來輪詢 Route 53 變更 ID，直到它達到 INSYNC。
使用 CHANGE_ID 作為環境變數。
解釋為什麼 INSYNC 不一定表示 ACM 驗證已經完成。

程式碼範例

export CHANGE_ID="<route53-change-id>"

while true; do
  STATUS=$(aws route53 get-change \
    --id "$CHANGE_ID" \
    --query 'ChangeInfo.Status' \
    --output text)

  echo "Route 53 change status: $STATUS"

  if [ "$STATUS" = "INSYNC" ]; then
    break
  fi

  sleep 15
done

詳細程式碼解釋

商業邏輯： Route 53 變更是非同步的。開發人員應等待 Route 53 回報變更已同步後，再期望 ACM 觀察到新的 DNS 紀錄。

程式碼邏輯： 該迴圈使用提交的變更 ID 呼叫 route53 get-change。它只擷取 ChangeInfo.Status。當狀態等於 INSYNC 時迴圈退出；否則，它會等待 15 秒並再次檢查。

預期結果： 指令最終會印出 INSYNC。這確認了 Route 53 已經處理了變更。它不能保證 ACM 已經完成了驗證，因為 ACM 必須獨立查詢 DNS 並更新其自身的憑證狀態。

系統設計決策 — 將 Route 53 同步與 ACM 驗證分開

• 不同的控制平面： Route 53 和 ACM 是獨立的服務，具有獨立的狀態轉換。Route 53 INSYNC 表示 DNS 供應商接受了變更，而 ACM 驗證則需要較晚的憑證控制平面檢查。
• 更好的故障排除： 分開這些狀態可以防止開發人員假設失敗的 ACM 狀態意味著 Route 53 變更失敗。這可能只是傳播或 ACM 輪詢延遲。
• 可靠的可觀察性： 每個服務應使用其自己的 API 和狀態欄位進行驗證。這建立了一個乾淨的診斷鏈：提交 DNS 寫入、同步 DNS 寫入、觀察到 ACM 驗證、完成憑證更新。

14. 模組 7 — 要求 Amazon Q 驗證 ACM 更新整備度

目標

返回 ACM 並確認憑證現在已準備好進行託管更新。

Amazon Q 提示範例

我已將 ACM DNS 驗證 CNAME 紀錄新增至 Route 53。
請告訴我如何從 ACM 憑證頁面和從 CloudShell 驗證自動更新現在已解除阻擋。
解釋 ISSUED、PENDING_VALIDATION、SUCCESS、FAILED 和 RenewalEligibility 的含義。

程式碼範例

aws acm describe-certificate \
  --region "$AWS_REGION" \
  --certificate-arn "$CERTIFICATE_ARN" \
  --query '{
    Status: Certificate.Status,
    RenewalEligibility: Certificate.RenewalEligibility,
    RenewalStatus: Certificate.RenewalSummary.RenewalStatus,
    DomainStatuses: Certificate.DomainValidationOptions[].{
      DomainName: DomainName,
      ValidationStatus: ValidationStatus
    },
    NotAfter: Certificate.NotAfter
  }' \
  --output json

詳細程式碼解釋

商業邏輯： 開發人員在 DNS 修復後需要最終以 ACM 為重點的檢查。此指令確認 ACM 是否仍將驗證視為擱置中、憑證是否保持核發狀態，以及憑證是否符合託管更新的資格。

程式碼邏輯： CLI 呼叫 describe-certificate 並僅投影與更新相關的欄位。Status 顯示憑證生命週期狀態，RenewalEligibility 顯示 ACM 是否可以管理更新，RenewalStatus 在存在時顯示更新進度，而 DomainStatuses 顯示每個網域名稱的驗證狀態。

預期結果： 健康的路徑會顯示已核發的憑證、啟用了更新資格，且網域驗證狀態正朝著成功推進。如果在 DNS 傳播後驗證仍保持擱置狀態，開發人員應驗證權威 DNS、紀錄拼字、CNAME 數值以及是否檢查了正確的憑證區域。

系統設計決策 — 按網域驗證，而不僅僅是憑證等級的狀態

• 多名稱憑證作為一個單元失敗： 一個憑證可以包含多個名稱。如果任何一個網域驗證紀錄遺失或錯誤，即使其他名稱有效，更新仍可能受阻。
• 精確的修復： 每個網域的驗證狀態將開發人員指向需要修復的確切紀錄。這比重新檢查每筆紀錄或替換憑證更快。
• 更安全的事件通訊： 回報每個網域的狀態可為平台和 DNS 團隊提供可操作的資訊，而不會暴露帳戶識別碼。當 DNS 擁有權屬於另一個團隊時，它也支援乾淨的升級路徑。

15. 模組 8 — 要求 Amazon Q 產生可重複使用的驗證指令碼

目標

將主控台修復轉換為可重複使用的開發人員自動化程式。

Amazon Q 提示範例

撰寫一個用於 CloudShell 的 Bash 驗證指令碼，該指令碼驗證 Route 53 中是否存在 ACM DNS 驗證紀錄。
需求：
- 從環境變數中讀取 CERTIFICATE_ARN、AWS_REGION 和 HOSTED_ZONE_ID。
- 比較 ACM ResourceRecord 項目與 Route 53 CNAME 紀錄。
- 如果所有紀錄都存在則結束代碼為 0，如果遺失紀錄則結束代碼為 2，在指令失敗時結束代碼為 1。
- 產生指令碼後對其進行解釋。

程式碼範例

#!/usr/bin/env bash
set -euo pipefail

: "${CERTIFICATE_ARN:?CERTIFICATE_ARN is required}"
: "${AWS_REGION:?AWS_REGION is required}"
: "${HOSTED_ZONE_ID:?HOSTED_ZONE_ID is required}"

ACM_FILE="/tmp/acm-certificate-renewal-check.json"
R53_FILE="/tmp/route53-cname-records.json"
REQUIRED_FILE="/tmp/acm-required-validation-records.json"
MISSING_FILE="/tmp/acm-missing-validation-records.json"

aws acm describe-certificate \
  --region "$AWS_REGION" \
  --certificate-arn "$CERTIFICATE_ARN" \
  --output json > "$ACM_FILE"

aws route53 list-resource-record-sets \
  --hosted-zone-id "$HOSTED_ZONE_ID" \
  --query "ResourceRecordSets[?Type == 'CNAME']" \
  --output json > "$R53_FILE"

jq '[
  .Certificate.DomainValidationOptions[]
  | select(.ResourceRecord != null)
  | .ResourceRecord
  | {
      Name: .Name,
      Type: .Type,
      Value: .Value
    }
] | unique_by(.Name)' "$ACM_FILE" > "$REQUIRED_FILE"

jq -n \
  --slurpfile required "$REQUIRED_FILE" \
  --slurpfile actual "$R53_FILE" '
  $required[0]
  | map(select(
      . as $req
      | ($actual[0]
        | any(
            .Name == $req.Name
            and .Type == $req.Type
            and (.ResourceRecords[]?.Value == $req.Value)
          )
        | not
      )
    ))' > "$MISSING_FILE"

MISSING_COUNT=$(jq 'length' "$MISSING_FILE")
REQUIRED_COUNT=$(jq 'length' "$REQUIRED_FILE")

if [ "$REQUIRED_COUNT" -eq 0 ]; then
  echo "No ACM DNS validation records were found for this certificate."
  exit 2
fi

if [ "$MISSING_COUNT" -gt 0 ]; then
  echo "Missing or mismatched ACM DNS validation record count: $MISSING_COUNT"
  jq '[.[] | {Type, Name}]' "$MISSING_FILE"
  exit 2
fi

echo "All required ACM DNS validation records exist in Route 53. Record count: $REQUIRED_COUNT"
exit 0

詳細程式碼解釋

商業邏輯： 此指令碼為開發人員在主控台修復後提供了一種可重複的驗證機制。其目的不是直接更新憑證；相反地，它驗證 Route 53 中存在 ACM 託管更新所需的 DNS 狀態。

程式碼邏輯： 指令碼將 ACM 憑證中繼資料和 Route 53 CNAME 紀錄匯出至暫存的 JSON 檔案中。它擷取 ACM 所需的驗證紀錄，將它們與實際的 Route 53 紀錄進行比較，計算遺失的項目，並傳回自動化可使用的結束代碼。

預期結果： 結束代碼 0 表示存在所有必要的 ACM 驗證 CNAME 紀錄。結束代碼 2 表示紀錄遺失或無法使用。結束代碼 1 保留給嚴格模式下造成的 shell 或 AWS CLI 失敗。指令碼僅為遺失的條目印出紀錄類型和名稱。

系統設計決策 — 不進行變異的驗證自動化

• 安全的可重複性： 唯讀的驗證器可以在有需求時、事件發生後或按排程執行，而不會有更動 DNS 的風險。這使其適合需要信心但不應重複變異正式環境紀錄的開發人員。
• 自動化訊號： 結束代碼將主控台故障排除工作流程轉換為機器可讀的結果。CI 作業、排程檢查或部署閘門可以根據成功或失敗採取行動。
• 最小揭露： 指令碼避免印出完整的憑證 ARN 或特定於帳戶的識別碼。它僅印出足以進行修復的 DNS 資訊，降低敏感資料出現在共用日誌中的風險。

16. 模組 9 — 要求 Amazon Q 像資深開發人員一樣審查指令碼

目標

使用 Amazon Q 在重複使用前強化營運程式碼。

Amazon Q 提示範例

以資深雲端平台開發人員的身分審查此 Bash 驗證指令碼。
將重點放在正確性、冪等性、錯誤處理、DNS 邊緣案例、敏感日誌記錄和正式環境整備度。
傳回排好優先順序的建議並解釋權衡取捨。

預期的審查主題

• 使用嚴格模式：set -euo pipefail。
• 驗證所有必需的環境變數。
• 避免記錄帳戶識別碼和完整的憑證 ARN。
• 避免在驗證程式碼中更改 DNS。
• 如果比較來自混合 DNS 供應商的輸出，則對尾隨點 (trailing dots) 進行標準化。
• 處理多個網域驗證選項。
• 刪除重複紀錄。
• 將修復和驗證保持為獨立的指令。

系統設計決策 — AI 輔助審查，人類負責正確性

• Amazon Q 加速審查： Amazon Q 可快速識別常見的指令碼編寫風險、不安全的日誌記錄、遺失的輸入驗證和 AWS CLI 失敗處理。這有助於開發人員在短暫的工作坊期間提高品質。
• 人類保持問責制： AI 產生的審查是建議性質的。專業開發人員仍然要決定哪些變更屬於正式環境，並根據其環境、權限和營運限制來驗證行為。
• 重複使用前審查： 主控台事件修復通常會變成共用指令碼。現在進行審查可防止脆弱的一次性指令在沒有適當安全檢查的情況下嵌入到建置系統、Runbook 或排程作業中。

17. 模組 10 — 向 Amazon Q 詢問安全性和營運護欄

目標

使用 Amazon Q 將修復轉換為安全的正式環境實務。

Amazon Q 提示範例

針對正式環境安全性，審查此 ACM DNS 驗證更新工作流程。
將重點放在敏感資料暴露、存取控制最低權限、DNS 擁有權、還原、可稽核性與監控上。
提供簡潔的工程建議。

建議的護欄

• 不要在共用的工作坊輸出中記錄真實網域、特定於帳戶的識別碼、憑證 ARN、託管區域 ID 或驗證權杖。
• 在變更正式環境 DNS 前要求進行同儕審查。
• 永久保留驗證 CNAME 紀錄，除非該憑證被刻意停用。
• 監控憑證到期和驗證紀錄的漂移 (drift)。
• 對排程檢查使用唯讀驗證器。
• 將修復權限與監控權限分開。
• 將指令碼儲存在版本控制中。
• 保留 CloudTrail 和 Route 53 變更歷程以供稽核。
• 當權威 DNS 位於目前帳戶之外時進行升級 (escalate)。

系統設計決策 — 將修復與監控分開

• 影響範圍控制： 監控應偵測遺失的紀錄，預設情況下不自動修改 DNS。這可以防止低信心水準的偵測器做出高影響的 DNS 變更。
• 明確的擁有權： DNS 寫入權限應保留給擁有正式環境 DNS 的角色、團隊或工作流程。驗證的範圍可以更廣泛，因為它是唯讀且低風險的。
• 可稽核性： 將讀取檢查與寫入動作分開，可讓團隊更容易審查誰變更了 DNS、為何進行該變更，以及觸發該變更的證據是什麼。

18. 使用 Amazon Q 產生的最後 10 分鐘主控台 Runbook

Amazon Q 提示範例

從 AWS 主控台建立一份簡潔的 ACM 自動更新整備度開發人員 Runbook。
包含症狀、主控台診斷、要詢問 Amazon Q 的問題、Route 53 修復、CloudShell 驗證、還原注意事項和升級條件。

Runbook 輸出範本

# ACM 自動更新整備度 Runbook

## 症狀
- ACM 憑證更新狀態為擱置中或受阻。
- ACM 回報 DNS 驗證未完成。
- 憑證即將到期。

## 主控台診斷
1. 在 AWS 主控台開啟 ACM。
2. 選取憑證。
3. 從主控台面板開啟 Amazon Q Developer。
4. 要求 Amazon Q 解釋更新資格、驗證方法和所需的 DNS 紀錄。
5. 確認憑證為 Amazon 核發、尚未過期，且已與預期的 AWS 服務關聯。

## DNS 修復
1. 開啟 Route 53 託管區域。
2. 選取權威公有託管區域。
3. 新增或修復 ACM 提供的 CNAME 驗證紀錄。
4. 永久保留這些紀錄。

## 驗證
1. 等待 Route 53 變更狀態變為 INSYNC。
2. 返回 ACM 憑證詳細資訊。
3. 詢問 Amazon Q 哪些狀態欄位應該變更。
4. 執行 CloudShell ACM 狀態指令。
5. 如果可用，執行 DNS 驗證器。

## 還原
- 不要刪除正確的 ACM 驗證紀錄。
- 如果建立了不正確的 CNAME，請用 ACM 提供的數值取代它。
- 如果變更了錯誤的託管區域，請將正確的紀錄套用至權威區域。

## 升級
- 如果權威 DNS 由另一個帳戶或供應商管理，請升級處理。
- 如果 DNS 傳播後驗證仍然擱置，請升級處理。
- 如果憑證是匯入、已過期或不符合託管更新資格，請升級處理。

系統設計決策 — 將 Runbook 作為最終成品

• 知識捕捉： 工作坊不應只以修復憑證結束。它應該產出一份可重複使用的營運程序，讓其他開發人員之後可以遵循。
• 一致性： Runbook 標準化術語、驗證指令、還原行為和升級條件。這可減少未來更新事件中的混淆。
• AI 輔助文件化： Amazon Q 可以在上下文仍然新鮮時，將對話式疑難排解路徑轉換為結構化文件。接著由開發人員審查並儲存為工程團隊擁有的知識。

19. 端到端開發人員檢查清單

• 在 AWS 主控台開啟 ACM 憑證詳細資訊。
• 從主控台開啟 Amazon Q Developer。
• 要求 Amazon Q 解釋憑證更新狀態。
• 確認憑證為 Amazon 核發且未過期。
• 確認驗證方法為 DNS 驗證。
• 確認憑證符合託管更新資格。
• 確認預期的 AWS 服務正在使用該憑證。
• 要求 Amazon Q 識別所需的 DNS 驗證紀錄。
• 開啟權威 Route 53 託管區域。
• 新增或修復 CNAME 驗證紀錄。
• 等待 Route 53 變更狀態變為 INSYNC。
• 重新檢查 ACM 網域驗證狀態。
• 要求 Amazon Q 解釋任何仍然擱置的狀態。
• 使用 Amazon Q 產生驗證器指令碼。
• 要求 Amazon Q 審查驗證器的安全日誌記錄和正確性。
• 為驗證器邏輯產生測試。
• 產生最終 Runbook。

20. 完成標準

當開發人員能夠展示以下成果時，工作坊即完成：

• 已從 AWS 主控台使用 Amazon Q Developer 作為主要指引。
• 在不暴露特定帳戶識別碼的情況下診斷 ACM 更新問題。
• 已識別所需的 DNS 驗證 CNAME 紀錄，並將其對應到 Route 53 欄位。
• 已透過主控台步驟或已審查的 CloudShell 指令完成 Route 53 修復。
• 已獨立驗證 ACM 和 Route 53 狀態。
• 已產生並審查可重複使用的驗證自動化。
• 已為核心比較邏輯產生單元測試。
• 已記錄安全性和營運護欄。
• 已產出經過清理的開發人員 Runbook。

21. 參考資料

• Amazon Q Developer in the AWS Management Console: https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/ask-q.html
• Amazon Q resource troubleshooting: https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/chat-actions-troubleshooting.html
• Amazon Q Developer documentation overview: https://aws.amazon.com/documentation-overview/q-developer/
• ACM DNS validation: https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html
• ACM managed certificate renewal: https://docs.aws.amazon.com/acm/latest/userguide/managed-renewal.html
• Route 53 validation guidance for ACM certificates: https://www.repost.aws/knowledge-center/route-53-validate-acm-certificates

22. 新增至工作坊的已清理主控台對話

目標

展示當開發人員要求 Amazon Q Developer 從 AWS 主控台協助還原 ACM 自動更新時，工作坊對話可能如何進行。此逐字稿已清理：不包含真實 DNS 名稱、特定帳戶識別碼、託管區域識別碼、驗證權杖或正式環境憑證識別碼。

對話 walkthrough

開發人員： 更新 <certificate-id> 的 <workshop-domain> 憑證。

Amazon Q Developer： 我會協助您更新 <workshop-domain> 的憑證 ID <certificate-id>。我可以看到您正在憑證區域中檢視 AWS Certificate Manager 憑證詳細資訊頁面。我會檢查目前的主控台上下文，並提供憑證更新指引。

Amazon Q Developer 頁面上下文指引： 您目前正在檢視憑證 <certificate-id> 的 ACM 憑證詳細資訊頁面。憑證更新可以透過兩種方式處理：

選項 1：強制手動更新

aws acm renew-certificate \
  --certificate-arn arn:aws:acm:<region>:<redacted-account>:certificate/<certificate-id>

選項 2：自動更新

為了日後更新，請確保憑證與受支援的 AWS 服務關聯，並保留 DNS 驗證 CNAME 紀錄，讓憑證持續符合託管更新資格。對於 DNS 驗證，ACM 會檢查權威 DNS 中是否存在所需的 CNAME 紀錄。如果這些紀錄存在，ACM 可以自動完成更新。如果使用電子郵件驗證，更新則取決於續約電子郵件工作流程中的核准。

開發人員： 設定自動更新。

Amazon Q Developer： 我會檢查憑證設定和更新狀態。

Amazon Q Developer 觀察到的狀態： 此憑證已設定為自動更新，且更新程序已啟動。

目前發現：

• 憑證符合託管更新資格。
• 憑證已與受支援的 AWS 服務關聯。
• 憑證使用 DNS 驗證。
• 更新目前正在等待驗證。

問題：

所需的 DNS 驗證 CNAME 紀錄遺失於權威 DNS 區域中。

Amazon Q Developer 修復指引： 將 ACM 提供的 CNAME 驗證紀錄新增至權威 Route 53 託管區域。

紀錄 1：

名稱：  <validation-record-name-1>.<workshop-domain>
類型：  CNAME
數值：  <validation-target-1>.acm-validations.aws

紀錄 2：

名稱：  <validation-record-name-2>.<workshop-domain>
類型：  CNAME
數值：  <validation-target-2>.acm-validations.aws

主控台步驟：

1. 開啟 Route 53 託管區域。
2. 選取 <workshop-domain> 的權威公有託管區域。
3. 選擇 建立紀錄。
4. 完全依照 ACM 提供的內容輸入 CNAME 紀錄名稱。
5. 選擇 CNAME 作為紀錄類型。
6. 輸入 ACM 驗證目標作為數值。
7. 使用簡單路由和適當的 TTL，例如 300 秒。
8. 對每個 ACM 驗證紀錄重複以上步驟。
9. 永久保留這些 DNS 驗證紀錄，以免未來的託管更新受阻。

開發人員： 紀錄已新增。檢查一下。

Amazon Q Developer： 我會驗證 Route 53 紀錄是否存在，然後重新檢查 ACM 憑證更新狀態。

Amazon Q Developer 驗證結果： 所需的 DNS 驗證 CNAME 紀錄已存在於權威託管區域中。

DNS 紀錄狀態：

• 紀錄 1 存在。
• 紀錄 2 存在。

憑證狀態：

• 憑證狀態為 ISSUED。
• 已啟用託管更新。
• 在 DNS 傳播且 ACM 輪詢 DNS 期間，更新驗證仍可能顯示擱置。
• 憑證仍與受支援的服務關聯，因此更新完成後可以自動部署。

預期的後續步驟：

1. 等待 DNS 傳播和 ACM 驗證輪詢。
2. 從憑證詳細資訊頁面重新檢查 ACM 更新狀態。
3. 確認每個網域的驗證狀態移至成功。
4. 永久保留 DNS 中的 CNAME 紀錄。

此對話如何對應到工作坊模組

• 模組 1： 開發人員從 ACM 憑證詳細資訊頁面開始，並要求 Amazon Q 提供頁面上下文指引。
• 模組 2： Amazon Q 解釋 ACM 託管更新先決條件，以及為何 DNS 驗證紀錄必須保留。
• 模組 4： Amazon Q 將 ACM 驗證紀錄對應到 Route 53 CNAME 欄位。
• 模組 5： Amazon Q 透過 Route 53 主控台引導 DNS 修復。
• 模組 7： Amazon Q 同時驗證 Route 53 紀錄存在與 ACM 更新整備度。
• 模組 10： Amazon Q 強化營運護欄：驗證紀錄應永久保留。

23. 憑證更新完成信

通知來源： Amazon Web Services Health 通知
通知類型： 資訊
主旨： 您的憑證已更新

AWS Health 事件

您的憑證已更新

來自 Amazon Web Services 的問候，

此通知是為了告知您，AWS Certificate Manager (ACM) 已完成 SSL/TLS 憑證的更新，該憑證包含主要 DNS 名稱 <workshop-domain>，總共 <domain-count> 個 DNS 名稱。

AWS 環境：<redacted-account>
AWS 區域名稱：<certificate-region>
憑證識別碼：<certificate-arn>

您的新憑證將於 <renewed-certificate-expiration-utc> 到期。

如果您對此程序有任何疑問，請透過支援中心聯絡 AWS Support。如果您沒有 AWS 支援計畫，請在 AWS Certificate Manager 討論區發布新討論串。

此通知僅供負責 <workshop-domain> 的授權人員使用。如果您誤收到此通知，請依照貴組織的通知處理流程辦理。