Variable Interpolation & Lookups

Relevant source files

The following files were used as context for generating this wiki page:

• tests/data/placebo/test_bedrock_agent_encryption/bedrock-agent.GetAgent_2.json
• tools/sandbox/c7n_autodoc/c7n-autodoc.py
• c7n/resources/sagemaker.py
• README.md
• tools/sandbox/c7n_autodoc/example_config_file.yml
• tools/dev/data_updatearnref.py

Variable interpolation and lookups provide dynamic data injection and resource attribute resolution across policies, documentation, and agent prompts. The system replaces placeholders with runtime values to enable contextual behavior in automation tasks.

This system supports multiple contexts:

• Agent Prompts: Injecting conversation history and user queries into LLM templates.
• Documentation: Rendering HTML reports from policy metadata using Jinja2.
• Resource Management: Resolving resource attributes like ARNs or status via specialized parsers.

Agent Prompt Interpolation

Bedrock agents utilize prompt templates that contain specific variable placeholders. The agent runtime identifies these placeholders and substitutes them with real-time data before sending the prompt to the foundation model.

Prompt Template Variables

The system recognizes several reserved variable names within XML-based or JSON-based templates:

• $question$: Represents the current user input or query.
• $conversation_history$: Contains the previous turns in the current session.
• $functions$: Lists the tools and API definitions available to the agent.
• $responses$: Tracks the history of actions and their outputs.
• $agent_scratchpad$: Stores internal reasoning steps for the orchestration layer.

Sources: tests/data/placebo/test_bedrock_agent_encryption/bedrock-agent.GetAgent_2.json:52-59, tests/data/placebo/test_bedrock_agent_encryption/bedrock-agent.GetAgent_2.json:104-106

Interpolation Flow

The orchestration engine follows a sequence to prepare the final prompt for the AI assistant.

This diagram illustrates how user input and session data are combined with static templates to create instructions for the AI model.
Sources: tests/data/placebo/test_bedrock_agent_encryption/bedrock-agent.GetAgent_2.json:302-330

Documentation Rendering

The c7n-autodoc utility performs variable interpolation to generate HTML documentation for policies. It uses the jinja2 environment to map policy metadata to visual templates.

Interpolation Variables in Autodoc

The system passes a render_vars dictionary to the template engine.

Variable	Description	Source
timestamp	The UTC time when the documentation was generated.	System Clock
c7n_data	The structured dictionary of all crawled policies.	Policy YAML files
environment_column	Boolean flag indicating if environment tags are present.	Configuration
environment_tags	Mapping of tag keys to display names (e.g., 'Sandbox').	example_config_file.yml

Sources: tools/sandbox/c7n_autodoc/c7n-autodoc.py:35-47, tools/sandbox/c7n_autodoc/example_config_file.yml:45-50

Path Interpolation

The system uses regular expressions to interpolate local file paths into web URLs for documentation links. The get_file_url function applies a file_url_regex and a file_url_base to transform local paths into repository links.
Sources: tools/sandbox/c7n_autodoc/c7n-autodoc.py:57-62

Resource Attribute Lookups

Cloud Custodian resource managers perform lookups to identify specific attributes for filtering and action execution.

Query Parsers

Resource managers like SagemakerJob and SagemakerProcessingJob use a QueryParser to resolve attributes from the cloud provider's API responses. This allows policies to reference specific fields like StatusEquals or NameContains.

class SagemakerJobQueryParser(QueryParser):
    QuerySchema = {
        'NameContains': str,
        'StatusEquals': ('InProgress', 'Completed', 'Failed', 'Stopping', 'Stopped'),
        'CreationTimeAfter': 'date',
    }

Sources: c7n/resources/sagemaker.py:270-279

ARN Reference Resolution

The data_updatearnref.py tool automates the lookup of Amazon Resource Name (ARN) formats across AWS services. It scrapes official documentation to map service prefixes to their respective resource ARN templates, enabling the project to correctly interpolate ARNs for various resource types.
Sources: tools/dev/data_updatearnref.py:350-357

Policy Filtering Lookups

Policies define lookups within YAML configuration to identify resources matching specific criteria.

Filter Types

The system supports nested lookups and boolean logic in the filters block:

1. Value Lookups: Compares a resource attribute against a static value.
2. Tag Lookups: Resolves values from the resource's metadata tags (e.g., tag:Environment).
3. Boolean Operators: Combines lookups using or or and blocks.

filters:
  - State.Name: running
  - "tag:Environment": absent
  - or:
      - "tag:OwnerContact": absent
      - "tag:DeptID": absent

Sources: README.md:144-150

Implementation Components

This flowchart shows how the system resolves policy definitions into active filters during execution.
Sources: README.md:120-135, c7n/resources/sagemaker.py:48-60

Summary

Variable interpolation and lookups allow Cloud Custodian to remain flexible across different environments and cloud providers. The Bedrock agent implementation relies on XML placeholder substitution for AI orchestration, while the autodoc tools use Jinja2 for report generation. Resource managers provide technical lookups for status and ARNs, ensuring policies act on the correct infrastructure assets.