apis.md

Application Programming Interfaces of ytt

There are two strategies for integrating with ytt:

1. as an executable — invoke ytt out-of-process as an executable running as a separate process.
2. as a Go module — construct, configure, execute, and inspect the results of a ytt command object, in-process.

For most use-cases, the as-an-executable integration is more appropriate:

• decouples versioning of your tooling from ytt itself making it easier to upgrade "in the field."
• maintains well-defined integration interfaces making development and troubleshooting far easier.
• provides lots of safety checks to ensure that inputs are well-formed and valid.
• allows your tooling to be implemented in any language/platform that supports shelling out a process.

Integrating with ytt as a Go module is more appropriate when:

• your use-case is narrow enough that few (if any) of the ytt-isms are useful to the end-user.
• your tooling must be distributed/integrated via a single binary (e.g. supplying a container image is undesirable)

Performance is typically not a concern when deciding whether to go out-of-process or in-process: with reasonable computing resources and sources residing on-machine, ytt can execute over a reasonably complex library typically less than a second.

As an Executable

By "integrate with ytt as an executable" we simply mean invoking the ytt binary, passing in the parameters required.

How one does this depends largely on the platform from which you're integrating.

Examples of how this can be done in Go:

• https://github.com/carvel-dev/kapp-controller/blob/develop/pkg/template/ytt.go
• https://github.com/carvel-dev/terraform-provider-carvel/blob/develop/pkg/ytt/ytt.go

As a Go Module

ytt does have a programmatic means of being invoked. However, there are no formal APIs: we can commit to backwards compatible behavior, but interfaces can and will change. Integrators need to be prepared to migrate with version bumps.

Overview

1. add ytt as a dependency:

   ...
   require  (
       ...
       carvel.dev/ytt v0.40.0
       ...
   )

2. create and populate an instance of the template command:

   opts := template.NewOptions()

3. invoke the command to evaluate:

   output := opts.RunWithFiles(inputs, ui)

Examples

• ./internal-templating/main.go — "Hello, world" with ytt.
• https://github.com/carvel-dev/kapp/blob/develop/pkg/kapp/yttresmod/overlay_contract_v1_mod.go — using ytt to overlay some existing YAML (here, a Kubernetes resource).

Next Steps

We are always happy to support you in your use of ytt. You can:

• find us at Kubernetes Slack: #carvel (if your not yet in the workspace, get an invite).
• pose a question or report an issue in our GitHub repo.