Testing Upbound's New Go Text Template integration with Visual Studio Code

Upbound provides a powerful development platform for Platform Engineers with VSCode integration, autocompletion, schema validation, artifact builds, and testing.

Included in version 0.39.0 of the up CLI, Upbound has extended this rich developer experience to Go Templates, alongside the existing support for Go, KCL, and Python.

Go Templates are used in many infrastructure tools like Helm and in one of the most popular Crossplane functions, function-go-templating. A Go Template to define an Azure Resource Group mixes YAML with variables and functions surrounded by double-brace characters {{ }}:

In this blog, we'll port an existing Composition to a Go Template, covering dependencies, schema generation, rendering, and testing.

Prerequisites

You'll need a minimum version v0.39.0 of Upbound's up binary. Download instructions are available at  https://docs.upbound.io/operate/cli/. 

Run up version to confirm you have the binary installed and at the proper release:

You'll also need a Crossplane environment, either running in a Kubernetes cluster or in a local development environment like kind. See the Crossplane installation guide for more information.

Upbound provides free development Control Planes that delete after 24 hours see build-with-upbound that can also be used for development and testing.

Visual Studio Code Extensions
To enable the best developer experience with Go Templates, several VSCode Extensions should be installed:

• Modelines
• YAML

Porting an Existing KCL Function To Go Templating

Let's take an existing Upbound Control Plane Project and rewrite an Embedded Function in Go Templating. This way we can reuse the existing tests to ensure we are not introducing any breaking changes.

Upbound's configuration-azure-network has one function that is written in KCL: main.k. The KCL function creates an Azure Resource Group, Virtual Network, and one or more Subnets based on what the end user requests.

Every Control Plane Project contains several directories and files:

• apis Where Platform APIs are defined
• examples Example manifests for documentation and testing
• functions Embedded Composition Functions where resources are defined
• tests Composition and End-to-End (e2e) Tests
• upbound.yaml a Project definition file used to track dependencies and name the artifacts

Clone the repo and enter the configuration-azure-network directory:

The apis/xnetworks directory now contains the existing and new composition files:

Generate the Function

Now that the Composition is defined, generate a Function with the --language CLI option set to go-templating, and pointing at the Composition that was just generated.

This will create .gotmpl files in the functions/<function-name> directory:

The .gotmpl files are compatible with function-go-templating templates, and the machinery in the up binary generates schemas for type checks and autocompletion.

Multiple .gotmpl files can be stored in the function directory. During a project build they are concatenated and packaged into a runnable Docker image.

Added to the Composition apis/xnetworks/composition-go-templating.yaml file will be a Pipeline step pointing to the function. The name of the function is based on values in the upbound.yaml Project file and the function name.

The First Build

To generate our schemas, up uses the dependencies in the upbound.yaml project file. Running up project build generates schemas and packages the APIs, Compositions and Functions into a Package that can be pushed to any Docker-compatible registry:

A hidden directory .up is created or updated every time up project build is run. This directory contains the multi-language schemas for the project dependencies. A typical development workflow is to add dependencies to the project and build it.

Azure ResourceGroups are part of the base "family" Azure Provider.

Go Templates use the models stored in the json directory.

The new Composition has been generated, dependencies downloaded, and the schema updated. The next step is to define the Managed Resource.

Update the 01-compose.yaml.gotmpl file to define the ResourceGroup. The code: and yaml-language-server comments that start the file are required to support schema validation in VSCode.

Render the Composition using up composition render to make sure everything is working.

Completing the Composition

Now that we know the Composition Pipeline works, we can complete the Embedded Function. Compare the version below to the original KCL version:

Testing the Composition

Testing is a critical part when developing an Infrastructure Platform. Now that the Composition has been rewritten in Go Templating, it needs to be validated.

Control Plane Project tests support two ways of testing: Composition Tests run locally and ensure that the rendered manifests match a desired output, while End-to-End tests provision infrastructure in a cloud provider.

configuration-azure-network includes a comprehensive Composition Test at tests/test-xnetwork/main.k written in KCL. Since Control Plane Projects support mixing languages between Functions and Tests, we can reuse the existing test suites.

There are 4 separate tests in the test main.k file. Change the compositionPath for each of the 4 tests to point to the new Go Template Composition, from:

to:

Run the test using up test run and fix any errors that are reported until all four tests pass: