A tribut metadata

A Metadata tribut memungkinkan Anda untuk mengaitkan data terstruktur dengan sumber daya. Dengan menambahkan Metadata atribut ke sumber daya, Anda dapat menambahkan data dalam JSON atau YAML ke deklarasi sumber daya. Selain itu, Anda dapat menggunakan fungsi intrinsik (seperti Fn::GetAtt danRef), parameter, dan parameter semu dalam Metadata atribut untuk menambahkan nilai-nilai yang ditafsirkan tersebut.

Anda dapat mengambil data ini menggunakan perintah describe-stack-resource CLI atau operasi API. DescribeStackResource

Contoh

Template berikut berisi sumber daya bucket Amazon S3 dengan Metadata atribut.

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

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

Metadata Skema konteks

S Metadata Context kema mendefinisikan konvensi terstruktur opsional untuk melestarikan maksud desain dan konteks operasional dalam CloudFormation template. Tambahkan com.aws.cloudformation.Context objek ke Metadata bagian tingkat template untuk merekam arsitektur dan batasan lintas batas. Pada tingkat sumber daya, tambahkan objek ke Metadata atribut sumber daya untuk merekam alasan, invarian, panduan perubahan keselamatan, asal, dan detail operasionalnya. Alat dan agen AI dapat mengambil konteks ini dengan template untuk membuat perubahan yang lebih aman di seluruh sesi. Gunakan Description bidang template untuk tujuan tumpukan.

Agar agen AI mengambil dan mempertahankan konteks saat membuat atau memperbarui template, gunakan keterampilan pen CloudFormation ulisan pada GitHub. Keterampilan ini adalah bagian dari Agen Toolkit untuk AWS.

Contoh Templat

Contoh berikut mencatat arsitektur pada tingkat template dan alasan, kendala, dan panduan perubahan keselamatan di tingkat sumber daya.

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

Definisi skema

Untuk validasi sisi klien, pilih blok #/$defs/TemplateContext tingkat template. Pilih #/$defs/ResourceContext untuk blok tingkat sumber daya.

Skema JSON berikut menggunakan JSON Schema Draft 2020-12 dan mendefinisikan versi 1 dariMetadata 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)."
    }
  }
}