Metadatenattribut

Das Attribut Metadata ermöglicht es Ihnen, strukturierte Daten mit einer Ressource zu verknüpfen. Indem Sie einer Ressource ein Metadata-Attribut hinzufügen, können Sie der Ressourcendeklaration Daten in JSON oder YAML hinzufügen. Darüber hinaus können Sie intrinsische Funktionen (wie Fn::GetAtt und Ref), Parameter und Pseudoparameter innerhalb des Attributs Metadata verwenden, um diese interpretierten Werte hinzuzufügen.

Sie können diese Daten mit dem CLI-Befehl https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stack-resource.html describe-stack-resource oder der API-Operation abrufen. DescribeStackResource

Beispiel

Die folgende Vorlage enthält eine Amazon-S3-Bucket-Ressource mit dem Attribut Metadata.

{
   "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

Metadaten-Kontextschema

Das Metadata Context Schema definiert eine optionale strukturierte Konvention zur Beibehaltung der Konstruktionsabsicht und des Betriebskontextes in einer CloudFormation Vorlage. Fügen Sie dem Metadata Abschnitt auf Vorlagenebene ein com.aws.cloudformation.Context Objekt hinzu, um Architektur und bereichsübergreifende Einschränkungen aufzuzeichnen. Fügen Sie das Objekt auf Ressourcenebene zum Metadata Attribut einer Ressource hinzu, um seine Begründung, Invarianten, Hinweise zur Änderungssicherheit, Herkunft und Betriebsdetails aufzuzeichnen. Tools und KI-Agenten können diesen Kontext mit der Vorlage abrufen, um sicherere Änderungen zwischen Sitzungen vorzunehmen. Verwenden Sie das Description Feld der Vorlage für den Zweck des Stacks.

Damit ein AI-Agent beim Verfassen oder Aktualisieren einer Vorlage den Kontext abruft und beibehält, verwenden Sie den CloudFormation Authoring-Skill an GitHub. Der Skill ist Teil des Agenten-Toolkits für. AWS

-Beispielvorlage

Im folgenden Beispiel wird die Architektur auf Vorlagenebene und die Gründe, Einschränkungen und Hinweise zur Änderungssicherheit auf Ressourcenebene aufgezeichnet.

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

Schemadefinition

Wählen #/$defs/TemplateContext Sie für die clientseitige Validierung einen Block auf Vorlagenebene aus. Wählen Sie #/$defs/ResourceContext für einen Block auf Ressourcenebene.

Das folgende JSON-Schema verwendet den JSON Schema Draft 2020-12 und definiert Version 1 von. 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)."
    }
  }
}