atmos-yaml-functions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Atmos YAML Functions

Atmos YAML 函数

Overview

概述

YAML functions are the recommended way to add dynamic behavior to Atmos stack configurations. They use YAML explicit tags (the

prefix) and operate on structured data after YAML parsing. They cannot break YAML syntax, are type-safe, and produce clear error messages.

All YAML functions support Go template expressions in their arguments. Atmos processes templates first, then executes the YAML functions.

YAML函数是为Atmos栈配置添加动态行为的推荐方式。它们使用YAML显式标签（

前缀），并在YAML解析后对结构化数据进行操作。它们不会破坏YAML语法，是类型安全的，并且能生成清晰的错误信息。

所有YAML函数在参数中支持Go template表达式。Atmos会先处理模板，再执行YAML函数。

Available YAML Functions

可用的YAML函数

Function	Purpose
`!terraform.state`	Read Terraform outputs directly from state backend (fastest, recommended)
`!terraform.output`	Read Terraform outputs via `terraform output` (requires init, slower)
`!store`	Read values from stores using component/stack/key pattern
`!store.get`	Read arbitrary keys from stores (no naming convention required)
`!env`	Read environment variables (from stack `env:` sections or OS)
`!exec`	Execute shell scripts and use the output
`!include`	Include local or remote files (YAML, JSON, HCL, text)
`!include.raw`	Include files as raw text regardless of extension
`!template`	Evaluate Go template expressions and convert JSON to YAML types
`!literal`	Preserve values verbatim, bypassing all template processing
`!random`	Generate cryptographically secure random integers
`!cwd`	Get the current working directory
`!repo-root`	Get the repository root directory
`!aws.account_id`	Get the current AWS account ID via STS
`!aws.caller_identity_arn`	Get the current AWS caller identity ARN
`!aws.caller_identity_user_id`	Get the AWS caller identity user ID
`!aws.organization_id`	Get the current AWS Organization ID
`!aws.region`	Get the current AWS region from SDK config

函数	用途
`!terraform.state`	直接从状态后端读取Terraform输出（速度最快，推荐使用）
`!terraform.output`	通过 `terraform output` 命令读取Terraform输出（需要初始化，速度较慢）
`!store`	使用组件/栈/键的模式从存储中读取值
`!store.get`	从存储中读取任意键（无需遵循命名约定）
`!env`	读取环境变量（来自栈的 `env:` 部分或操作系统）
`!exec`	执行shell脚本并使用其输出
`!include`	包含本地或远程文件（YAML、JSON、HCL、文本）
`!include.raw`	以原始文本形式包含文件，不受扩展名影响
`!template`	计算Go template表达式并将JSON转换为YAML类型
`!literal`	按原样保留值，绕过所有模板处理
`!random`	生成加密安全的随机整数
`!cwd`	获取当前工作目录
`!repo-root`	获取仓库根目录
`!aws.account_id`	通过STS获取当前AWS账户ID
`!aws.caller_identity_arn`	获取当前AWS调用者身份ARN
`!aws.caller_identity_user_id`	获取AWS调用者身份用户ID
`!aws.organization_id`	获取当前AWS组织ID
`!aws.region`	从SDK配置中获取当前AWS区域

Supported Sections

支持的部分

YAML functions work in all Atmos stack manifest sections:

```
vars
```
,
```
settings
```
,
```
env
```
,
```
metadata
```
,
```
command
```
,
```
component
```
```
providers
```
,
```
overrides
```
,
```
backend
```
,
```
backend_type
```

remote_state_backend

remote_state_backend_type

YAML函数可在所有Atmos栈清单部分中使用：

```
vars
```
、
```
settings
```
、
```
env
```
、
```
metadata
```
、
```
command
```
、
```
component
```
```
providers
```
、
```
overrides
```
、
```
backend
```
、
```
backend_type
```

remote_state_backend

、

remote_state_backend_type

!terraform.state

-- Fast State Backend Access (Recommended)

!terraform.state

-- 快速状态后端访问（推荐）

Reads outputs directly from the Terraform state backend without initialization. Supports S3, local, GCS, and azurerm backends. 10-100x faster than

!terraform.output

yaml

vars:
  # Two-parameter form: component + output (current stack)
  vpc_id: !terraform.state vpc vpc_id

  # Three-parameter form: component + stack + output
  vpc_id: !terraform.state vpc plat-ue2-prod vpc_id

  # Using Go templates for dynamic stack references
  vpc_id: !terraform.state vpc {{ .stack }} vpc_id

  # YQ expressions for complex outputs
  first_subnet: !terraform.state vpc .private_subnet_ids[0]
  db_host: !terraform.state config .config_map.username

  # Default values for unprovisioned components
  vpc_id: !terraform.state vpc ".vpc_id // ""default-vpc"""

  # YQ string concatenation
  url: !terraform.state aurora-postgres ".master_hostname | ""jdbc:postgresql://"" + . + "":5432"""

  # Bracket notation for keys with special characters
  key: !terraform.state security '.users["github-dependabot"].access_key_id'

无需初始化即可直接从Terraform状态后端读取输出。支持S3、本地、GCS和azurerm后端。速度比
!terraform.output
快10-100倍。

yaml

vars:
  # 双参数形式：组件 + 输出（当前栈）
  vpc_id: !terraform.state vpc vpc_id

  # 三参数形式：组件 + 栈 + 输出
  vpc_id: !terraform.state vpc plat-ue2-prod vpc_id

  # 使用Go模板实现动态栈引用
  vpc_id: !terraform.state vpc {{ .stack }} vpc_id

  # 针对复杂输出使用YQ表达式
  first_subnet: !terraform.state vpc .private_subnet_ids[0]
  db_host: !terraform.state config .config_map.username

  # 为未部署的组件设置默认值
  vpc_id: !terraform.state vpc ".vpc_id // ""default-vpc"""

  # YQ字符串拼接
  url: !terraform.state aurora-postgres ".master_hostname | ""jdbc:postgresql://"" + . + "":5432"""

  # 对包含特殊字符的键使用括号表示法
  key: !terraform.state security '.users["github-dependabot"].access_key_id'

!terraform.output

-- Remote State Access

!terraform.output

-- 远程状态访问

Reads Terraform outputs by running

terraform output

. Requires Terraform initialization (downloading providers), which is significantly slower than

!terraform.state

. Use

!terraform.state

instead when your backend is supported.

yaml

vars:
  vpc_id: !terraform.output vpc vpc_id
  vpc_id: !terraform.output vpc plat-ue2-prod vpc_id
  vpc_id: !terraform.output vpc {{ .stack }} vpc_id
  first_subnet: !terraform.output vpc .private_subnet_ids[0]

通过运行

terraform output

命令读取Terraform输出。需要Terraform初始化（下载提供商），速度明显慢于
!terraform.state
。当你的后端受支持时，请改用

!terraform.state

。

yaml

vars:
  vpc_id: !terraform.output vpc vpc_id
  vpc_id: !terraform.output vpc plat-ue2-prod vpc_id
  vpc_id: !terraform.output vpc {{ .stack }} vpc_id
  first_subnet: !terraform.output vpc .private_subnet_ids[0]

!store

-- Component-Aware Store Access

!store

-- 感知组件的存储访问

Reads values from configured stores (SSM Parameter Store, Redis, Artifactory, etc.) following the Atmos stack/component/key naming convention:

yaml

vars:
  vpc_id: !store prod/ssm vpc vpc_id
  vpc_id: !store prod/ssm plat-ue2-prod vpc vpc_id
  vpc_id: !store prod/ssm {{ .stack }} vpc vpc_id
  api_key: !store prod/ssm config api_key | default "not-set"
  db_host: !store prod/ssm config connection | query .host

从已配置的存储（SSM Parameter Store、Redis、Artifactory等）中读取值，遵循Atmos的栈/组件/键命名约定：

yaml

vars:
  vpc_id: !store prod/ssm vpc vpc_id
  vpc_id: !store prod/ssm plat-ue2-prod vpc vpc_id
  vpc_id: !store prod/ssm {{ .stack }} vpc vpc_id
  api_key: !store prod/ssm config api_key | default "not-set"
  db_host: !store prod/ssm config connection | query .host

!store.get

-- Arbitrary Key Store Access

!store.get

-- 任意键的存储访问

Reads arbitrary keys from stores without following the component/stack naming convention:

yaml

vars:
  db_password: !store.get ssm /myapp/prod/db/password
  feature_flag: !store.get ssm /features/new-feature | default "disabled"
  api_key: !store.get redis app-config | query .api.key
  config: !store.get redis "config-{{ .vars.region }}"

从存储中读取任意键，无需遵循组件/栈的命名约定：

yaml

vars:
  db_password: !store.get ssm /myapp/prod/db/password
  feature_flag: !store.get ssm /features/new-feature | default "disabled"
  api_key: !store.get redis app-config | query .api.key
  config: !store.get redis "config-{{ .vars.region }}"

!env

-- Environment Variables

!env

-- 环境变量

Reads from stack manifest

env:

sections (merged via inheritance) or OS environment variables:

yaml

vars:
  api_key: !env API_KEY
  app_name: !env APP_NAME my-app
  description: !env 'APP_DESC "my application"'

Resolution order: stack manifest

env:

sections -> OS environment variables -> default value.

从栈清单的

env:

部分（通过继承合并）或操作系统环境变量中读取：

yaml

vars:
  api_key: !env API_KEY
  app_name: !env APP_NAME my-app
  description: !env 'APP_DESC "my application"'

解析顺序：栈清单

env:

部分 -> 操作系统环境变量 -> 默认值。

!exec

-- Shell Script Execution

!exec

-- Shell脚本执行

Executes shell scripts and assigns the output:

yaml

vars:
  timestamp: !exec date +%s

  # Multi-line script
  result: |
    !exec
      foo=0
      for i in 1 2 3; do
        foo+=$i
      done
      echo $foo

  # Complex types must be returned as JSON
  config: !exec get-config.sh --format json

执行shell脚本并将输出赋值给变量：

yaml

vars:
  timestamp: !exec date +%s

  # 多行脚本
  result: |
    !exec
      foo=0
      for i in 1 2 3; do
        foo+=$i
      done
      echo $foo

  # 复杂类型必须以JSON格式返回
  config: !exec get-config.sh --format json

!include

-- File Inclusion

!include

-- 文件包含

Includes local or remote files, parsing them based on extension:

yaml

vars:
  config: !include ./config.yaml
  vpc_defaults: !include stacks/catalog/vpc/defaults.yaml
  region_config: !include https://raw.githubusercontent.com/org/repo/main/config.yaml
  cidr: !include ./vpc_config.yaml .vars.ipv4_primary_cidr_block
  vars: !include config/prod.tfvars
  description: !include ./description.md

Supported protocols: local files, HTTP/HTTPS, GitHub (

github://

), S3 (

s3::

), GCS (

gcs::

), SCP/SFTP, OCI.

包含本地或远程文件，根据扩展名进行解析：

yaml

vars:
  config: !include ./config.yaml
  vpc_defaults: !include stacks/catalog/vpc/defaults.yaml
  region_config: !include https://raw.githubusercontent.com/org/repo/main/config.yaml
  cidr: !include ./vpc_config.yaml .vars.ipv4_primary_cidr_block
  vars: !include config/prod.tfvars
  description: !include ./description.md

支持的协议：本地文件、HTTP/HTTPS、GitHub（

github://

）、S3（

s3::

）、GCS（

gcs::

）、SCP/SFTP、OCI。

!template

-- Go Template Evaluation

!template

-- Go模板计算

Evaluates Go template expressions and converts JSON output to proper YAML types. Essential for handling complex outputs (maps, lists) from

atmos.Component

yaml

vars:
  subnet_ids: !template '{{ toJson (atmos.Component "vpc" .stack).outputs.private_subnet_ids }}'
  config: !template '{{ toJson (atmos.Component "config" .stack).outputs.config_map }}'
  cidrs: !template '{{ toJson .settings.allowed_ingress_cidrs }}'

计算Go template表达式并将JSON输出转换为正确的YAML类型。对于处理

atmos.Component

的复杂输出（映射、列表）至关重要：

yaml

vars:
  subnet_ids: !template '{{ toJson (atmos.Component "vpc" .stack).outputs.private_subnet_ids }}'
  config: !template '{{ toJson (atmos.Component "config" .stack).outputs.config_map }}'
  cidrs: !template '{{ toJson .settings.allowed_ingress_cidrs }}'

!literal

-- Bypass Template Processing

!literal

-- 绕过模板处理

Preserves values exactly as written, preventing Atmos from evaluating template-like syntax:

yaml

vars:
  annotation: !literal "{{ .Values.ingress.class }}"
  user_data: !literal "#!/bin/bash\necho ${hostname}"
  config_url: !literal "{{external.config_url}}"

按原样保留值，防止Atmos计算类模板语法：

yaml

vars:
  annotation: !literal "{{ .Values.ingress.class }}"
  user_data: !literal "#!/bin/bash\necho ${hostname}"
  config_url: !literal "{{external.config_url}}"

!random

-- Random Number Generation

!random

-- 随机数生成

Generates cryptographically secure random integers:

yaml

vars:
  port: !random 1024 65535
  id: !random 1000 9999
  default_random: !random

生成加密安全的随机整数：

yaml

vars:
  port: !random 1024 65535
  id: !random 1000 9999
  default_random: !random

AWS Identity Functions

AWS身份函数

yaml

vars:
  account_id: !aws.account_id
  org_id: !aws.organization_id
  caller_arn: !aws.caller_identity_arn
  caller_user_id: !aws.caller_identity_user_id
  region: !aws.region

yaml

vars:
  account_id: !aws.account_id
  org_id: !aws.organization_id
  caller_arn: !aws.caller_identity_arn
  caller_user_id: !aws.caller_identity_user_id
  region: !aws.region

Utility Functions

实用工具函数

yaml

vars:
  working_dir: !cwd
  repo_root: !repo-root

yaml

vars:
  working_dir: !cwd
  repo_root: !repo-root

When to Use YAML Functions vs. Go Templates

何时使用YAML函数 vs Go模板

Scenario	Use
Reading Terraform outputs	`!terraform.state` or `!terraform.output`
Reading store values	`!store` or `!store.get`
Environment variables	`!env`
Including files	`!include`
Complex outputs (lists/maps)	`!template` with `toJson`
Passing syntax to external tools	`!literal`
Conditional logic ( `if/else` )	Go templates (see `atmos-templates` skill)
Loops and iteration	Go templates (see `atmos-templates` skill)
Dynamic key generation	Go templates (see `atmos-templates` skill)
Advanced string manipulation	Go templates (see `atmos-templates` skill)

场景	使用方式
读取Terraform输出	`!terraform.state` 或 `!terraform.output`
读取存储值	`!store` 或 `!store.get`
环境变量	`!env`
包含文件	`!include`
复杂输出（列表/映射）	结合 `toJson` 使用 `!template`
传递语法给外部工具	`!literal`
条件逻辑（if/else）	Go模板（参考 `atmos-templates` 技能）
循环与迭代	Go模板（参考 `atmos-templates` 技能）
动态键生成	Go模板（参考 `atmos-templates` 技能）
高级字符串操作	Go模板（参考 `atmos-templates` 技能）

Performance Best Practices

性能最佳实践

Prefer
!terraform.state
over
!terraform.output
-- 10-100x faster (no Terraform init)
Prefer
!store
over
atmos.Component
for outputs -- Avoids Terraform initialization
All YAML functions cache results per execution for repeated calls
Cold-start errors --
```
!terraform.output
```
and
```
!store
```
fail if the referenced component is not yet provisioned. Use YQ defaults (
```
//
```
) or
```
| default
```
to handle this.

优先使用
!terraform.state
而非
!terraform.output
-- 速度快10-100倍（无需Terraform初始化）
优先使用
!store
而非
atmos.Component
读取输出 -- 避免Terraform初始化
所有YAML函数会为重复调用缓存结果（每次执行内）
冷启动错误 -- 如果引用的组件尚未部署，
```
!terraform.output
```
和
```
!store
```
会执行失败。使用YQ默认值（
```
//
```
）或
```
| default
```
来处理这种情况。

Additional Resources

额外资源

For the full YAML functions reference with detailed syntax and examples, see references/yaml-functions.md

如需包含详细语法和示例的完整YAML函数参考，请查看references/yaml-functions.md