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 템플릿에서 설계 의도와 운영 컨텍스트를 보존하기 위한 선택적이고 구조화된 규칙을 정의합니다. 아키텍처 및 크로스 컷팅 제약 조건을 기록하려면 템플릿 수준 Metadata 섹션에 com.aws.cloudformation.Context 객체를 추가합니다. 리소스 수준에서 근거, 불변성, 변경 안전 지침, 출처 및 운영 세부 정보를 기록하려면 리소스의 Metadata 속성에 객체를 추가합니다. 도구와 AI 에이전트는 템플릿으로 이 컨텍스트를 검색해서 세션 전반에 걸쳐 보다 안전하게 변경 작업을 수행할 수 있습니다. 스택의 용도에는 템플릿의 Description 필드를 사용합니다.

템플릿을 작성하거나 업데이트할 때 AI 에이전트가 컨텍스트를 검색하고 보존하도록 하려면 GitHub의 CloudFormation 작성 스킬을 사용합니다. 이 스킬은 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를 사용하며 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)."
    }
  }
}