View a markdown version of this page

Metadata 属性 - AWS CloudFormation
示例Metadata Context 架构

这是新的《CloudFormation 模板参考指南》。请更新您的书签和链接。有关开始使用 CloudFormation 的帮助，请参阅《AWS CloudFormation 用户指南》https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html。

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 模板中保留设计意图和操作上下文。向模板级别 Metadata 部分添加一个 com.aws.cloudformation.Context 对象，以记录架构和跨领域约束。在资源级别，将对象添加到资源的 Metadata 属性，以记录其基本原理、不变量、变更安全指南、来源和操作详细信息。工具和人工智能代理可以结合模板检索此上下文，从而跨会话进行更安全的更改。使用模板的 Description 字段来说明堆栈的用途。

要让人工智能代理在创作或更新模板时检索和保留上下文，请使用 GitHub 上的 CloudFormation 创作技能。该技能是 Agent Toolkit for 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 Schema Draft 2020-12 并定义 Metadata Context 的版本 1。

{
  "$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)."
    }
  }
}