Reference on function-hcl

DSL Specification

Mon, 01 Jan 0001 00:00:00 +0000

Source of truth

This page is derived from spec.md in the repository. If you find a discrepancy, the repository version is authoritative.

Input Format

The function accepts its HCL program in txtar format via the input field of the Composition pipeline step. All files are treated as one unit.

External Variables

Created automatically from the RunFunctionRequest. Accessed as req.<field>.

Variable	Type	Description
`req.composite`	object	Observed composite resource (XR)
`req.composite_connection`	map(string, bytes)	Observed connection details of the composite
`req.resource`	map(string, object)	Observed resource bodies, keyed by crossplane name
`req.connection`	map(string, map(string, bytes))	Observed connection details, keyed by resource name
`req.resources`	map(string, list(object))	Observed resource collections, keyed by base name
`req.connections`	map(string, list(map(string, bytes)))	Connection details of collections
`req.context`	map(string, any)	Pipeline context
`req.extra_resources`	map(string, list(object))	Extra resources from `requirement` blocks

Top-Level Blocks

`locals`

locals {
 <name> = <expression>
}

Accessed by name directly (no local. prefix).
Ordering does not matter; locals with incomplete values are evaluated lazily.
Circular references are an error.
Cannot shadow names from parent scopes.
Can be defined at: top level, resource, resources template, group, requirement, function.

`resource`

resource <crossplane-name> {
 condition = <bool> # optional
 locals { ... } # optional
 body = { <k8s-manifest> } # required
 composite status { body = { ... } } # optional, repeatable
 composite connection { body = { ... } } # optional, repeatable
 ready { value = <string> } # optional
}

Special variables: self.name, self.resource, self.connection

Built-in Functions

Mon, 01 Jan 0001 00:00:00 +0000

function-hcl supports most Terraform functions as of v1.5.7. Exceptions are noted at the end of the page.

Available Functions by Category

Numeric

Function	Description
`abs(n)`	Absolute value
`ceil(n)`	Round up to nearest integer
`floor(n)`	Round down to nearest integer
`log(n, base)`	Logarithm
`max(n1, n2, ...)`	Maximum value
`min(n1, n2, ...)`	Minimum value
`parseint(str, base)`	Parse integer from string
`pow(base, exp)`	Exponentiation
`signum(n)`	Sign of number (-1, 0, 1)

String

Function	Description
`chomp(str)`	Remove trailing newlines
`endswith(str, suffix)`	Check suffix
`format(fmt, args...)`	String formatting (sprintf-style)
`formatlist(fmt, list...)`	Format each element
`indent(spaces, str)`	Indent all lines
`join(sep, list)`	Join list elements
`lower(str)`	Lowercase
`regex(pattern, str)`	Regex match
`regexall(pattern, str)`	All regex matches
`replace(str, old, new)`	String replacement
`split(sep, str)`	Split string
`startswith(str, prefix)`	Check prefix
`strrev(str)`	Reverse string
`substr(str, offset, length)`	Substring
`title(str)`	Title case
`trim(str, chars)`	Trim characters
`trimprefix(str, prefix)`	Trim prefix
`trimsuffix(str, suffix)`	Trim suffix
`trimspace(str)`	Trim whitespace
`upper(str)`	Uppercase

Collection

Function	Description
`alltrue(list)`	All elements are true
`anytrue(list)`	Any element is true
`chunklist(list, size)`	Split list into chunks
`coalesce(vals...)`	First non-null, non-empty value
`coalescelist(lists...)`	First non-empty list
`compact(list)`	Remove empty strings
`concat(lists...)`	Concatenate lists
`contains(list, val)`	Check membership
`distinct(list)`	Remove duplicates
`element(list, idx)`	Get element by index (wraps)
`flatten(list)`	Flatten nested lists
`index(list, val)`	Find index of value
`keys(map)`	Map keys
`length(val)`	Length of string, list, or map
`list(vals...)`	Create a list
`lookup(map, key, default)`	Safe map lookup
`map(k1, v1, k2, v2, ...)`	Create a map
`matchkeys(vals, keys, search)`	Filter by matching keys
`merge(maps...)`	Merge maps
`one(list)`	Extract single element or null
`range(start, limit, step)`	Generate number sequence
`reverse(list)`	Reverse list
`setintersection(sets...)`	Set intersection
`setproduct(sets...)`	Cartesian product
`setsubtract(a, b)`	Set difference
`setunion(sets...)`	Set union
`slice(list, start, end)`	List slice
`sort(list)`	Sort strings lexicographically
`sum(list)`	Sum numbers
`transpose(map)`	Transpose map of lists
`values(map)`	Map values
`zipmap(keys, values)`	Create map from key/value lists

Encoding

Function	Description
`base64decode(str)`	Decode base64
`base64encode(str)`	Encode to base64
`base64gzip(str)`	Gzip then base64 encode
`csvdecode(str)`	Parse CSV
`jsondecode(str)`	Parse JSON
`jsonencode(val)`	Encode to JSON
`textdecodebase64(str, enc)`	Decode base64 with encoding
`textencodebase64(str, enc)`	Encode with encoding then base64
`urlencode(str)`	URL encode
`yamldecode(str)`	Parse YAML
`yamlencode(val)`	Encode to YAML

Hash and Crypto

Function	Description
`base64sha256(str)`	Base64-encoded SHA256
`base64sha512(str)`	Base64-encoded SHA512
`md5(str)`	MD5 hash
`sha1(str)`	SHA1 hash
`sha256(str)`	SHA256 hash
`sha512(str)`	SHA512 hash

IP Network

Function	Description
`cidrhost(prefix, hostnum)`	Calculate host IP
`cidrnetmask(prefix)`	Network mask
`cidrsubnet(prefix, newbits, netnum)`	Calculate subnet
`cidrsubnets(prefix, newbits...)`	Calculate multiple subnets

Type Conversion

Function	Description
`can(expr)`	Test if expression evaluates without error
`nonsensitive(val)`	Remove sensitive marking
`sensitive(val)`	Mark as sensitive
`tobool(val)`	Convert to bool
`tolist(val)`	Convert to list
`tomap(val)`	Convert to map
`tonumber(val)`	Convert to number
`toset(val)`	Convert to set
`tostring(val)`	Convert to string
`try(exprs...)`	First expression that doesn’t error
`type(val)`	Get type of value

Custom Functions

`invoke`

invoke("functionName", { arg1: value1, arg2: value2 })

Calls a user-defined function. The first argument must be a static string. See the language guide for details.

Error Conditions

Mon, 01 Jan 0001 00:00:00 +0000

The following conditions are treated as errors by function-hcl. When an error occurs, the function returns a Fatal result that surfaces on the composite resource.

Parsing Errors

Error	Description
HCL syntax error	Invalid HCL syntax in the source files
Schema violation	Block structure doesn’t match the expected schema

Variable Errors

Error	Description
Unknown local variable	Reference to a local variable name that doesn’t exist
Circular reference	Circular dependencies in locals (e.g. `locals { a = b; b = a }`)
Local shadowing	A local variable in an inner scope has the same name as one in a parent scope

Resource Errors

Error	Description
Duplicate resource name	Two resources produce the same crossplane name
Existing resource became incomplete	A resource that exists in the observed state now has an incomplete value. This is a safety check to prevent accidental deletion.

Condition Errors

Error	Description
Incomplete condition	A `condition` value that cannot be evaluated (note: incomplete conditions are treated as `false`, but certain evaluation failures are errors)
Non-boolean condition	A `condition` evaluates to something other than `true` or `false`

Status and Connection Errors

Error	Description
Conflicting status values	Two `composite status` blocks set the same non-object leaf attribute to different values
Conflicting connection values	Two `composite connection` blocks set the same key to different values
Non-string connection value	A connection detail value is not a base64-encoded string

Requirement Errors

Error	Description
Both matchName and matchLabels	A `requirement` block specifies both selection methods
Neither matchName nor matchLabels	A `requirement` block specifies no selection method
Type mismatch	Data type mismatch in `select` attributes

Function Errors

Error	Description
Invalid function name	A `function` or `arg` has a name that is not a valid identifier
Unknown function	`invoke` references a non-existent function
Bad invocation	`invoke` called with missing required arguments or unrecognized argument names
Stack overflow	Call stack exceeds 100 frames (infinite recursion protection)

Context Errors

Error	Description
Conflicting context values	Two `context` blocks write different non-object values to the same key path

fn-hcl-tools CLI

Mon, 01 Jan 0001 00:00:00 +0000

fn-hcl-tools is a companion CLI for function-hcl that helps package, format, and analyze HCL compositions.

Installation

go install github.com/crossplane-contrib/function-hcl/function-hcl/cmd/fn-hcl-tools@v0.2.0-rc9

Commands

`package`

Packages a directory of HCL files into a single txtar bundle, suitable for embedding in a Composition’s input field.

fn-hcl-tools package *.hcl

The tool runs basic static analysis on the HCL before packing, catching syntax errors early.

Example:

Given a directory:

my-composition/
 main.hcl
 bucket.hcl
 database.hcl

Run:

fn-hcl-tools package my-composition/*.hcl

Output (suitable for pasting into a Composition YAML input field):