Language Guide on function-hcl

Source Format

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

HCL Syntax

function-hcl source code is written in HCL syntax. Code may be spread across multiple files – all files are treated as one unit. The only difference between having multiple files versus a single file is that line numbers will differ in error messages.

txtar Format

The function accepts its input as text in the input field of a Composition pipeline step. This must be in txtar format so that original file names are maintained and line numbers match the source code.

HCL Basics

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

Before diving into function-hcl specifics, it helps to understand the fundamental building blocks of HCL syntax. This page covers the essentials; for the full language specification see the HCL Native Syntax Specification.

People who have worked with Terraform before should feel free to skip this section.

Blocks

A block is a container that has a type, zero or more labels, and a body enclosed in braces. The body contains attributes and/or nested blocks.

The req Variable

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

function-hcl provides a built-in req variable that gives you access to the Crossplane request state. It is available everywhere in the script – top-level locals, resource blocks, groups, and nested blocks.

Fields

Expression	Type	Description
`req.composite`	k8s object	The observed composite resource (XR)
`req.composite_connection`	map(string, bytes)	Connection details of the composite resource
`req.resource`	map(string, k8s object)	Observed composed resources, keyed by crossplane resource name
`req.connection`	map(string, map(string, bytes))	Connection details of observed resources, keyed by resource name
`req.resources`	map(string, list(k8s object))	Observed resource collections, keyed by collection base name
`req.connections`	map(string, list(map(string, bytes)))	Connection details of resource collections
`req.context`	map(string, any)	Pipeline context values from upstream functions
`req.extra_resources`	map(string, list(k8s object))	Extra resources fetched via `requirement` blocks

Example

locals {
 comp = req.composite
 compName = comp.metadata.name
 params = comp.spec.parameters
 region = params.region

 # Access an observed resource by its crossplane name
 observedBucket = req.resource.my-bucket

 # Access pipeline context
 upstreamValue = req.context["upstream-function/some-key"]
}

Accessing Observed Resources

Use req.resource.<name> to access any observed composed resource by its crossplane name. This is useful when one resource needs to reference the status of another:

Local Variables

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

Local variables in function-hcl work like Terraform locals, with some important differences.

Basics

Define locals in a locals block. Access them directly by name – no local. prefix needed.

locals {
 baseName = req.composite.metadata.name
 computedName = "${baseName}-bucket"
}

Ordering Doesn’t Matter

All locals blocks in a given scope are processed together and variable ordering doesn’t matter. Dependencies are resolved automatically. This is the same behavior as Terraform.

# These two blocks are treated identically:
locals {
 computedName = "${baseName}-bucket"
}

locals {
 baseName = req.composite.metadata.name
}

Circular references (e.g. locals { a = b; b = a }) are an error.

Resource Blocks

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

The resource block is the primary way to declare a desired composed resource.

Syntax

resource <crossplane-name> {
 locals { ... } # optional: resource-scoped locals

 body = { ... } # required: the Kubernetes manifest

 composite status { } # optional: write to composite status
 composite connection { } # optional: write connection details
 ready { } # optional: set readiness
}

The `body` Attribute

body is an HCL object expression that produces the full Kubernetes manifest for the composed resource. It must be assigned with =.

Resource Collections

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

The resources (plural) block creates multiple resources by iterating over a collection.

Syntax

resources <base-name> {
 locals { ... } # optional: collection-scoped locals

 for_each = <expression> # required: list, set, or map to iterate over

 name = <expression> # optional: how to generate each crossplane name
 # default: "${self.basename}-${each.key}"

 template { # required: the template for each resource
 locals { ... } # optional: template-scoped locals
 body = { ... } # required: the Kubernetes manifest
 composite status { } # optional
 composite connection { } # optional
 ready { } # optional
 }
}

Example

resources additional_buckets {
 locals {
 params = req.composite.spec.parameters
 suffixes = params.suffixes
 }

 for_each = suffixes

 template {
 locals {
 resourceName = "${req.composite.metadata.name}-${self.name}"
 }

 body = {
 apiVersion = "s3.aws.upbound.io/v1beta1"
 kind = "Bucket"
 metadata = {
 name = resourceName
 }
 spec = {
 forProvider = {
 forceDestroy = true
 region = params.region
 }
 }
 }
 }
}

The `for_each` Attribute

Must evaluate to a list, set, or map.

Groups

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

The group block allows you to group related resources together and share local variables among them without polluting the top-level namespace.

Syntax

group {
 condition = <bool> # optional: skip the entire group
 locals { ... } # optional: shared locals for resources in this group

 resource <name> { }
 resource <name> { }
 resources <name> { }
}

Example

group {
 locals {
 vpcParams = req.composite.spec.parameters.vpc
 region = vpcParams.region
 }

 resource my-vpc {
 body = {
 apiVersion = "ec2.aws.upbound.io/v1beta1"
 kind = "VPC"
 metadata = { name = "${req.composite.metadata.name}-vpc" }
 spec = { forProvider = { region = region, cidrBlock = vpcParams.cidr } }
 }
 }

 resource my-subnet {
 body = {
 apiVersion = "ec2.aws.upbound.io/v1beta1"
 kind = "Subnet"
 metadata = { name = "${req.composite.metadata.name}-subnet" }
 spec = {
 forProvider = {
 region = region
 vpcId = req.resource.my-vpc.status.atProvider.id
 cidrBlock = vpcParams.subnetCidr
 }
 }
 }
 }
}

# vpcParams and region are NOT available here

Scoping

Locals defined in a group block are available to all resources within the group.
They are not available outside the group.
Resources in the group still have access to top-level locals.
Groups can contain resource, resources, and nested group blocks.

Conditional Groups

A group can have a condition attribute to skip the entire group:

Conditions

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

Use a condition attribute to create resources only when specific conditions are met. This is the function-hcl equivalent of Terraform’s count = var.create ? 1 : 0.

On a Resource

resource s3_acl {
 condition = try(req.composite.spec.parameters.createAcls, true)

 body = {
 # ...
 }
}

The condition expression must evaluate to a boolean value. If the value is false, the resource is skipped entirely.

On a Resource Collection

When applied to a resources block, the condition controls the entire collection. To filter individual elements, filter the collection that for_each iterates over instead.

Composite Status

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

The composite status block writes values to the composite resource’s (XR) status. It can be specified any number of times, and each block can update specific fields.

At the Top Level

composite status {
 body = {
 foobarId = req.resource.foobar.status.atProvider.id
 }
}

Inside a Resource Block

This is the more common pattern, since self.resource gives you direct access to the observed state of the current resource:

resource foobar {
 body = { ... }

 composite status {
 body = {
 foobarId = self.resource.status.atProvider.id
 }
 }
}

Merging Multiple Status Blocks

Multiple composite status blocks can update different fields. Objects are merged:

Composite Connection Details

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

The composite connection block writes connection details to the composite resource. It works the same way as composite status in terms of scoping and merging.

Syntax

composite connection {
 body = {
 <key> = <base64-encoded-string>
 }
}

All values must be strings that are base64 encoded. The function returns an error otherwise.

At the Top Level

composite connection {
 body = {
 url = base64encode(req.resource.foobar.status.atProvider.url)
 }
}

Inside a Resource Block

resource my-database {
 body = { ... }

 composite connection {
 body = {
 connectionString = base64encode(self.resource.status.atProvider.connectionString)
 password = self.connection["password"] # already base64 from the provider
 }
 }
}

Merging and Conflict Detection

Multiple composite connection blocks can set different keys. Two blocks cannot set the same key to different values – this is an error.

Resource Ready Status

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

The ready block lets you assign a ready state for a resource. Usually you would use function-auto-ready to automatically set the resource status.

This allows you to set the ready status explicitly.

Syntax

resource foo {
 body = { /* ... */ }

 ready {
 value = "READY_TRUE"
 }
}

Valid Values

The value attribute must evaluate to a string and be one of:

Value	Meaning
`"READY_UNSPECIFIED"`	Ready state is not known
`"READY_TRUE"`	Resource is ready
`"READY_FALSE"`	Resource is not ready

Example: Custom Readiness Check

resource my-database {
 body = { /* ... */ }

 ready {
 value = self.resource.status.atProvider.state == "available" ? "READY_TRUE" : "READY_FALSE"
 }
}

If self.resource is incomplete (resource not yet created), the ready block follows the same deferral rules as other blocks.

Context

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

The context block writes values into the Crossplane pipeline context, making them available to downstream functions in the pipeline.

Syntax

context {
 key = <string>
 value = <any>
}

Example

context {
 key = "example.com/foo-bar-baz"
 value = {
 foo = { bar = "baz" }
 bar = 10
 baz = "quux"
 }
}

Merging Multiple Context Blocks

You can write to the same context key from multiple blocks. Object values are merged using the same rules as composite status:

Requirements (Extra Resources)

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

The requirement block lets you request extra resources from Crossplane. These are typically used to read configuration data (like EnvironmentConfig objects) that aren’t part of the composition’s resource tree.

Syntax

requirement <name> {
 condition = <bool> # optional
 locals { ... } # optional

 select {
 apiVersion = <string>
 kind = <string>
 matchName = <string> # match by name
 # OR
 matchLabels = <map(string)> # match by labels
 }
}

You must specify either matchName or matchLabels, but not both.

User-Defined Functions

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

function-hcl lets you define reusable functions in your HCL code.

Defining Functions

Functions are defined with the function block. They must be defined at the top level (not inside a group or other block).

function addNumbers {
 arg a {}
 arg b { default = 1 }

 locals {
 output = a + b
 }

 body = output
}

Structure

arg blocks define the function’s parameters. Each arg can have an optional default value and an optional description.
locals blocks can be used for temporary calculations.
body is the return value of the function.

Scoping Rules

Functions do not have access to external state. You cannot use req.composite, self, or any other variable from the calling context inside a function. Only the declared arguments and locals within the function are accessible.

Language Guide on function-hcl

Source Format

HCL Syntax

txtar Format

HCL Basics

Blocks

The req Variable

Fields

Example

Accessing Observed Resources

Local Variables

Basics

Ordering Doesn’t Matter

Resource Blocks

Syntax

The body Attribute

Resource Collections

Syntax

Example

The for_each Attribute

Groups

Syntax

Example

Scoping

Conditional Groups

Conditions

On a Resource

On a Resource Collection

Composite Status

At the Top Level

Inside a Resource Block

Merging Multiple Status Blocks

Composite Connection Details

Syntax

At the Top Level

Inside a Resource Block

Merging and Conflict Detection

Resource Ready Status

Syntax

Valid Values

Example: Custom Readiness Check

Context

Syntax

Example

Merging Multiple Context Blocks

Requirements (Extra Resources)

Syntax

User-Defined Functions

Defining Functions

Structure

Scoping Rules

The `body` Attribute

The `for_each` Attribute