`Metadata` 属性

リソースには、Metadata 属性を使用して構造化データを関連付けることができます。リソースに Metadata 属性を追加することで、JSON または YAML 形式のデータをリソースの宣言に追加することができます。また、Metadata 属性内で組み込み関数 (Fn::GetAtt、Ref など) パラメータや擬似パラメータを使用し、これらの解釈された値を追加することもできます。

注記

CloudFormation は、Metadata 属性内の構文を検証しません。

重要

CloudFormation は、Metadata 属性に含められた情報の編集や難読化を行いません。このセクションを使用してパスワードやシークレットなどの機密情報を保存しないことを強くお勧めします。

このデータは、describe-stack-resource CLI コマンドまたは DescribeStackResource API オペレーションを使用して取得できます。

例

次のテンプレートでは、Amazon S3 バケットリソースに Metadata 属性が使用されています。

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 オーサリングスキルを使用します。このスキルは 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)."
    }
  }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

DependsOn

AWS::CloudFormation::Authentication

Metadata 属性

注記

重要

例