Exec

The exec step executes an external program and captures its output. It follows Terraform’s external data source protocol, making it easy to integrate with existing scripts and tools.

Configuration

ExecStep executes an external program following Terraform's external data source protocol.

• program - Required Template ([]string)

  Program is the command to execute. The first element is the program path, subsequent elements are arguments.

• input - Optional (map[string]any)

  Input is passed to the program as JSON on stdin.

• working_dir - Optional (string)

  WorkingDir is the working directory for the command. Relative paths are resolved from the current working directory.

• timeout - Optional (string)

  Timeout is the maximum duration to wait for the command to complete. Defaults to "30s".

  Defaults to 30s.
• format - Optional (string)

  Format specifies how to interpret the program's output. "json" (default): parse stdout as JSON "raw": base64 encode stdout

  Must be one of: json , raw .
• env - Optional Template (map[string]string)

  Env specifies additional environment variables for the command. These are merged with the parent environment.

Protocol

The exec step communicates with the external program using a simple protocol:

• Input: The input field is encoded as JSON and passed to the program on stdin
• Output: The program’s stdout is captured and processed based on the format setting
• Errors: If the program exits with a non-zero status, stderr is included in the error message

Output format

The format option controls how stdout is interpreted:

• json (default): Parses stdout as JSON and includes the resulting structure in the output
• raw: Base64 encodes stdout and returns it as {"output": "<base64-encoded-content>"}

Environment

For security, the exec step does not inherit the full parent process environment. Instead, it passes through only:

• Safe variables: PATH, HOME, TMPDIR, SHELL, USER, LOGNAME, TERM, LANG
• Passed variables: Variables explicitly passed via the --pass-env CLI flag
• Step-defined variables: Variables set in the step’s env field

Additional variables can be added using the env field. Environment values support template expansion.

To pass additional environment variables from the parent process, use the --pass-env CLI flag:

infracollect collect job.yaml --pass-env AWS_REGION --pass-env KUBECONFIG

Or pass all environment variables (use with caution):

infracollect collect job.yaml --pass-all-env

Examples

Run a shell command

steps:
  - id: date
    exec:
      program: ["date", "+%Y-%m-%d"]
      format: raw

Process JSON with jq

steps:
  - id: transform
    exec:
      program: ["jq", ".items | map(.name)"]
      input:
        items:
          - name: foo
          - name: bar
      format: json

Run a script with environment variables

steps:
  - id: api-call
    exec:
      program: ["./scripts/fetch-data.sh"]
      working_dir: ./scripts
      timeout: 60s
      env:
        API_KEY: ${API_KEY}
        API_URL: https://api.example.com

Collect Helm releases

steps:
  - id: helm-releases
    exec:
      program: ["helm", "list", "--all-namespaces", "--output", "json"]
      timeout: 60s
      format: json

Use kubectl to get resources

steps:
  - id: pods
    exec:
      program: ["kubectl", "get", "pods", "-A", "-o", "json"]
      format: json

Template expansion in program arguments

The program field supports template expansion, allowing you to use environment variables in command arguments:

steps:
  - id: fetch-cluster
    exec:
      program: ["kubectl", "get", "pods", "-A", "-o", "json", "--context", "${KUBE_CONTEXT}"]
      format: json

Custom script with stdin input

steps:
  - id: custom-transform
    exec:
      program: ["python3", "-c", "import json, sys; data = json.load(sys.stdin); print(json.dumps({'count': len(data['items'])}))"]
      input:
        items: [1, 2, 3, 4, 5]
      format: json