!include.raw

The !include.raw function forces any file to be included as a raw string, bypassing automatic parsing based on file extension.

Availability and evaluation

Supported locations:

• CLI configuration (atmos.yaml, atmos.d, and profiles): during file loading.
• Stack manifests: during file loading, before inheritance and merging.
• Workflow manifests: during manifest loading.
• Scaffold manifests: during manifest loading.

The path cannot depend on the final merged component context.

Automatic evaluation requires native YAML tags from edition 2026-10-20, including unpinned projects. Quoted function strings remain literal; earlier editions retain legacy string-form behavior.

See YAML function scope for field restrictions, import timing, and native tags versus quoted strings.

While the regular !include function parses files based on their extension (JSON, YAML, HCL), !include.raw always returns the file content as a plain string. This is useful when you need the actual file content as text rather than parsed data structures.

Usage

vars:
  # Always injects content from file or URL as string
  json_string: !include.raw config.json
  yaml_string: !include.raw settings.yaml
  hcl_string: !include.raw terraform.tfvars

Common Use Cases

Template Files

Include template files that need to be processed later:

components:
  terraform:
    my-service:
      vars:
        # Kubernetes manifest template as string
        manifest_template: !include.raw k8s-deployment-template.yaml

        # JSON config template for interpolation
        config_template: !include.raw config-template.json

        # Terraform HCL template
        tf_template: !include.raw module-template.tf

Documentation and Scripts

Include documentation or scripts as strings:

metadata:
  # Include markdown documentation
  readme: !include.raw README.md
  release_notes: !include.raw docs/release-notes.md

  # Include shell scripts
  install_script: !include.raw ./scripts/install.sh
  deploy_script: !include.raw ./scripts/deploy.sh

Preserving Formatting

When you need to preserve the exact formatting of a file:

vars:
  # Preserve JSON formatting for display or logging
  example_config: !include.raw example-config.json

  # Keep YAML with comments intact
  annotated_yaml: !include.raw annotated-config.yaml

  # Include HCL with original formatting
  terraform_example: !include.raw example.tf

Configuration as Strings

When you need configuration files as strings for further processing:

components:
  terraform:
    app:
      vars:
        # Pass JSON config as string to Terraform
        json_config_string: !include.raw app-config.json

        # YAML config for base64 encoding
        yaml_config_string: !include.raw settings.yaml

Remote Files

The !include.raw function works with all remote sources supported by !include:

vars:
  # GitHub raw content
  remote_template: !include.raw https://raw.githubusercontent.com/org/repo/main/template.yaml

  # S3 bucket files
  s3_script: !include.raw s3://my-bucket/scripts/deploy.sh

  # Google Cloud Storage
  gcs_config: !include.raw gcs://my-bucket/configs/app.json

  # With query parameters (extension detection ignores query strings)
  versioned_template: !include.raw https://api.example.com/template.yaml?version=2

Comparison with !include

Function	File: config.json	Content	Result
!include	config.json	{"key": "value"}	Parsed JSON object: {key: value}
!include.raw	config.json	{"key": "value"}	Raw string: '{"key": "value"}'

Example

Given a file config.json:

{
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

Using in a stack manifest:

components:
  terraform:
    app:
      vars:
        # Parsed as JSON object
        config_parsed: !include config.json
        # Result: {database: {host: localhost, port: 5432}}

        # Raw string
        config_string: !include.raw config.json
        # Result: '{"database":{"host":"localhost","port":5432}}'

YQ Expressions Not Supported

NOTE:

The !include.raw function does not support YQ expressions since it always returns raw strings. Use the regular !include function when you need to query structured data with YQ.

vars:
  # ❌ YQ expressions are not supported with !include.raw
  # This will fail - !include.raw does not process YQ expressions
  invalid: !include.raw config.json .database.host

  # ✅ Use regular !include for YQ expressions
  valid: !include config.json .database.host

File Extension Handling

Unlike !include which uses file extensions to determine parsing behavior, !include.raw completely ignores file extensions:

vars:
  # All return raw strings regardless of extension
  json_raw: !include.raw data.json          # Raw string
  yaml_raw: !include.raw config.yaml        # Raw string
  hcl_raw: !include.raw terraform.tfvars    # Raw string
  text_raw: !include.raw readme.txt         # Raw string
  no_ext_raw: !include.raw LICENSE          # Raw string

Supported Sources

Local Files

The !include.raw function supports three kinds of local file paths. The kind is decided by how the path is written, and Atmos never falls back from one kind to another:

Path	Resolved relative to
/abs/script.sh	Nothing — used as written
./script.sh, ../script.sh	The directory of the file that contains the !include.raw
scripts/script.sh	base_path

Each kind has one primary location. If the file does not exist there, !include.raw fails with an error that names where it looked. The only fallback is for bare paths in stack manifests, which are also checked against the directory you run Atmos from (see below). A ./ path that is missing next to the including file is never replaced by a same-named file under base_path; when one exists, the error suggests dropping the ./ prefix.

1. Absolute paths — Used as-is with no resolution needed.

   vars: !include.raw /Users/me/Documents/policy.rego

2. Paths relative to the including file (./ or ../) — Paths that start with ./ or ../ are resolved relative to the directory of the file that contains the !include.raw — the stack manifest, or the imported catalog file, where the tag is written. For example, if the manifest is at stacks/deploy/dev.yaml, then ../config/policy.rego resolves to stacks/config/policy.rego. Only that location is checked.

   # Resolved relative to the directory of the current manifest file
   vars: !include.raw ../config/policy.rego
   script: !include.raw ./scripts/deploy.sh

   NOTE:

   Use ./ or ../ prefixes when you want to explicitly reference files relative to the current manifest's location. This is the most unambiguous way to include files that live near the manifest.

3. Paths relative to base_path — All other relative paths (those without a ./ or ../ prefix) are resolved relative to the base_path defined in atmos.yaml. This is the most common pattern for referencing shared configuration files (e.g., in a config/ or stacks/catalog/ directory) from any stack manifest, regardless of where that manifest is in the directory tree.

   # Resolved relative to `base_path` in atmos.yaml (typically the repo root)
   policy: !include.raw stacks/catalog/policies/deny.rego
   readme: !include.raw config/README.md

   For example, given this atmos.yaml:

   base_path: "./"

   The path config/README.md in any manifest resolves to <repo-root>/config/README.md.

   For stack manifests, a bare path that does not exist under base_path is checked against the directory you run Atmos from as a last resort. Don't rely on it: the result then depends on where Atmos is invoked.

Remote Files

• HTTP/HTTPS: !include.raw https://example.com/config.json
• S3: !include.raw s3::https://bucket.s3.amazonaws.com/file.yaml
• GCS: !include.raw gcs::gs://bucket/path/file.hcl
• Git: !include.raw git::https://github.com/org/repo.git//file.txt?ref=v1.0.0

See Also

• !include - Standard include function with automatic parsing based on file extension
• YAML Functions - Overview of all YAML functions in Atmos