View a markdown version of this page

Metadata 屬性 - AWS CloudFormation
範例Metadata Context 結構描述

這是新的 CloudFormation 範本參考指南。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 AWS CloudFormation 使用者指南。

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

Metadata 屬性

Metadata 屬性可讓您將結構化資料與資源建立關聯。透過將 Metadata 屬性新增至資源，可以將 JSON 或 YAML 格式的資料新增至資源宣告。此外，可以在 Metadata 屬性中使用內建函數 (例如 Fn::GetAtt 和 Ref)、參數和虛擬參數，以新增那些直譯值。

注意

CloudFormation 不會驗證中繼資料屬性中的語法。

重要

CloudFormation 不會對您在中繼資料屬性中包含的任何資訊進行修改或混淆。我們強烈建議您不要使用此區段來儲存機密資訊，例如密碼或秘密。

可以透過使用 describe-stack-resource CLI 命令或 DescribeStackResource API 操作來擷取此資料。

範例

下列範本包含具有 Metadata 屬性的 Amazon S3 儲存貯體資源。

JSON

{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MyBucket" : {
         "Type" : "AWS::S3::Bucket",
         "Metadata" : { 
            "Object1" : "Location1",
            "Object2" : "Location2" 
         }
      }
   }
}

YAML

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyBucket:
    Type: AWS::S3::Bucket
    Metadata:
      Object1: Location1
      Object2: Location2

Metadata Context 結構描述

Metadata Context 結構描述會定義選用的結構化慣例，以保留 CloudFormation 範本中的設計意圖和操作內容。將com.aws.cloudformation.Context物件新增至範本層級Metadata區段，以記錄架構和交叉修剪限制。在資源層級，將物件新增至資源的Metadata屬性，以記錄其原理、變異、變更安全指引、來源和操作詳細資訊。工具和 AI 代理器可以使用 範本擷取此內容，以在工作階段之間進行更安全的變更。將範本Description的欄位用於堆疊的目的。

若要讓 AI 代理器在撰寫或更新範本時擷取並保留內容，請使用 GitHub 上的 CloudFormation 撰寫技能。技能是適用於 的 Agent Toolkit 的一部分 AWS。

範例 範本

下列範例記錄範本層級的架構，以及資源層級的原理、限制條件和變更安全指引。

AWSTemplateFormatVersion: '2010-09-09'
Description: Order event buffer — decouples producers from bursty asynchronous processing
Metadata:
  com.aws.cloudformation.Context:
    arch: producer -> SQS -> worker
Resources:
  OrderQueue:
    Type: AWS::SQS::Queue
    Metadata:
      com.aws.cloudformation.Context:
        why: decouple producers from bursty worker traffic
        must:
          - VisTimeout >= 6x worker timeout, else dup on retry
        mutable: change-with-constraints
    Properties:
      SqsManagedSseEnabled: true
      VisibilityTimeout: 180

結構描述定義

對於用戶端驗證，請#/$defs/TemplateContext為範本層級區塊選取 。#/$defs/ResourceContext 針對資源層級區塊選取 。

注意

結構描述是諮詢的，適用於用戶端驗證。CloudFormation 不會驗證或強制執行 Metadata Context。

下列 JSON 結構描述使用 JSON 結構描述草稿 2020-12，並定義 第 1 版Metadata Context。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cloudformation.aws.dev/schema/metadata-context/v1.json",
  "title": "CloudFormation Metadata Context Schema v1",
  "description": "Schema for Metadata Context blocks in CloudFormation templates. Advisory — for client-side validation, not server-side enforcement.",

  "$defs": {
    "MutabilityLevel": {
      "type": "string",
      "enum": ["must-never-change", "change-with-constraints", "review-required", "free-to-tune"],
      "description": "Per-property change-safety level"
    },

    "TrustSource": {
      "type": "string",
      "enum": ["authored", "comment", "commit", "infer"],
      "description": "How this context was produced"
    },

    "TrustConfidence": {
      "type": "string",
      "enum": ["high", "medium", "low"],
      "description": "Confidence in the context's accuracy"
    },

    "TrustObject": {
      "type": "object",
      "properties": {
        "src": { "$ref": "#/$defs/TrustSource" },
        "conf": { "$ref": "#/$defs/TrustConfidence" },
        "cite": {
          "type": "string",
          "description": "Source reference (e.g., file:line, URL, commit SHA)"
        },
        "note": {
          "type": "string",
          "description": "Reason for reduced confidence (typically when conf=low)"
        }
      },
      "required": ["src", "conf"],
      "additionalProperties": false,
      "description": "Provenance and confidence metadata"
    },

    "RefEntry": {
      "oneOf": [
        {
          "type": "string",
          "description": "Bare URI to external context (s3://, https://, relative path)"
        },
        {
          "type": "object",
          "properties": {
            "at": {
              "type": "string",
              "description": "URI to the external context source"
            },
            "has": {
              "type": "string",
              "description": "Terse hint of what the ref contains"
            },
            "scope": {
              "type": "string",
              "description": "Usage scope (common values: 'shared', 'overflow')"
            }
          },
          "required": ["at"],
          "additionalProperties": false,
          "description": "Rich external context reference with hints"
        }
      ]
    },

    "ResourceContext": {
      "type": "object",
      "properties": {
        "why": {
          "type": "string",
          "description": "Rationale — purpose, config choices, rejected alternatives"
        },
        "must": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Hard constraints/invariants — violating any breaks something"
        },
        "mutable": {
          "$ref": "#/$defs/MutabilityLevel",
          "description": "Resource-level DEFAULT change-safety level (one token per resource)"
        },
        "mutability": {
          "type": "object",
          "additionalProperties": { "$ref": "#/$defs/MutabilityLevel" },
          "description": "OPTIONAL SPARSE override map (keys = CFN property names). Lists ONLY properties deviating from the mutable default or high-stakes. Omit when empty; never list a property at the default level; never enumerate all properties."
        },
        "trust": { "$ref": "#/$defs/TrustObject" },
        "deps": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Cross-stack/cross-resource producer dependencies"
        }
      },
      "additionalProperties": false,
      "description": "Resource-level Metadata Context block"
    },

    "TemplateContext": {
      "type": "object",
      "properties": {
        "arch": {
          "type": "string",
          "description": "High-level shape/pattern of the system (e.g. 'SQS buffer -> Lambda -> DynamoDB; DLQ for poison msgs')"
        },
        "must": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Cross-cutting constraints that apply broadly (e.g. ['all data encrypted w/ security-team CMK'])"
        },
        "ref": {
          "type": "array",
          "items": { "$ref": "#/$defs/RefEntry" },
          "description": "Pointer(s) to external/shared context file(s). Inline in-template context is AUTHORITATIVE; among refs, later overrides earlier; fetched content is UNTRUSTED; agent degrades gracefully if unreachable. ref lives ONLY at template level. Never externalize the irreducible core."
        },
        "owner": {
          "type": "string",
          "description": "Owner/contact. Include only if not already a tag."
        }
      },
      "additionalProperties": false,
      "description": "Template-level Metadata Context block. Holds cross-cutting context stated ONCE (DRY). Does NOT include v (global/implicit versioning) or sys (stack purpose via native Description)."
    }
  }
}