!include.raw

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

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 the following local file sources. Atmos resolves local file paths using the following strategies in order, finding the first match that points to an existing file:

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

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

2. Stack Manifest-relative paths (./ or ../) — Paths that start with ./ or ../ are resolved relative to the directory containing the manifest file where the !include.raw function is used. Atmos rewrites the path by joining it with the manifest's directory before checking if the file exists. For example, if the manifest is at stacks/deploy/dev.yaml, then ../config/policy.rego resolves to stacks/config/policy.rego.

   # 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.

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