yampl

README

Yampl

Yampl (yaml + tmpl) templates YAML values based on line-comments.

Installation

Yampl is available in brew or as a Docker container.

Homebrew (macOS, Linux)

Click to expand

brew install clevyr/tap/yampl

GitHub Actions

Click to expand

There are two actions available for CI/CD usage:

• clevyr/setup-yampl-action: Installs yampl during a GitHub Action run.
• clevyr/yampl-action: Installs yampl, runs yampl with the given inputs, then optionally creates a commit for you.

Docker

Click to expand

yampl has a Docker image available at ghcr.io/clevyr/yampl

docker pull ghcr.io/clevyr/yampl

To use this image, you will need to volume bind the desired directory into the Docker container. The container uses /data as its workdir, so if you wanted to template example.yaml in the current directory, you could run:

docker run --rm -it -v "$PWD:/data" ghcr.io/clevyr/yampl example.yaml ...

APT Repository (Ubuntu, Debian)

Click to expand

1. If you don't have it already, install the ca-certificates package

   sudo apt install ca-certificates
   

2. Add Clevyr's apt repository

   echo 'deb [trusted=yes] https://apt.clevyr.com /' | sudo tee /etc/apt/sources.list.d/clevyr.list
   

3. Update apt repositories

   sudo apt update
   

4. Install yampl

   sudo apt install yampl
   

RPM Repository (CentOS, RHEL)

Click to expand

1. If you don't have it already, install the ca-certificates package

   sudo yum install ca-certificates
   

2. Add Clevyr's rpm repository to /etc/yum.repos.d/clevyr.repo

   [clevyr]
   name=Clevyr
   baseurl=https://rpm.clevyr.com
   enabled=1
   gpgcheck=0
   

3. Install yampl

   sudo yum install yampl
   

AUR (Arch Linux)

Click to expand

Install yampl-bin with your AUR helper of choice.

Usage

View the generated docs for flag and command reference. Also, see templating and example sections.

Examples

Simple Examples

1. Template with a single value:

   $ cat example.yaml
   name: Clevyr #yampl {{ .name }}
   $ yampl example.yaml -v name='Clevyr Inc.'
   name: Clevyr Inc. #yampl {{ .name }}
   

2. Template with multiple values:

   $ cat example.yaml
   image: nginx:stable #yampl {{ .repo }}:{{ .tag }}
   $ yampl example.yaml -v repo=docker.io/nginx -v tag=1.27.0
   image: docker.io/nginx:1.27.0 #yampl {{ .repo }}:{{ .tag }}
   

[!NOTE] All variables must be set for a node to be changed.

1. Using a Sprig function:

   $ cat example.yaml
   name: Clevyr #yampl {{ upper current }}
   $ yampl example.yaml
   name: CLEVYR #yampl {{ upper current }}
   

2. Using the repo helper function:

   $ cat example.yaml
   image: nginx:1.26.1 #yampl {{ repo current }}:{{ .tag }}
   $ yampl example.yaml -v tag=1.27.0
   image: nginx:1.27.0 #yampl {{ repo current }}:{{ .tag }}
   

Kubernetes Deployment

Click to expand

Here is a simple Kubernetes Deployment with an Nginx image:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.26.1 #yampl nginx:{{ .tag }}
          ports:
          - containerPort: 80

Notice the yaml comment on the same line as image.

If this file was called nginx.yaml, then you could replace the image tag by running:

yampl -i nginx.yaml -v tag=1.27.0

The file would be updated in-place:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27.0 #yampl nginx:{{ .tag }}
          ports:
            - containerPort: 80

If you wanted to repeat yourself even less, you could use the repo function to pull the existing repo through to the output. For example, you could change the image line to:

image: nginx:1.27.0 #yampl {{ repo current }}:{{ .tag }}

This would generate the same output, but you wouldn't have to type nginx twice. This becomes more useful when using custom Docker registries where repo names can get long.

Templating

Variables

All variables passed in with the -v flag are available during templating.
For example, the variable -v tag=latest can be used as {{ .tag }}.

Functions

All Sprig functions are available in templates, along with some extras:

current

Returns the current YAML node's value.

repo

Splits a Docker repo and tag into the repo component:

repo "nginx:stable-alpine"

The above produces nginx.

tag

Splits a Docker repo and tag into the tag component:

tag "nginx:stable-alpine"

The above produces stable-alpine

Advanced Usage

Tags

By default, templated values are not explicitly quoted. This can cause problems with tools that require specific types. If you require a specific type for a field, you can add a tag to the template prefix.

Supported tags:

• #yampl:bool
• #yampl:str
• #yampl:int
• #yampl:float
• #yampl:seq
• #yampl:map

Examples

1. String

   The following could be interpreted as either a string or an int:

   $ cat example.yaml
   num: #yampl {{ .num }}
   $ yampl example.yaml -v num=2009
   num: 2009 #yampl {{ .num }}
   

   If this field must be a string, you could add the str tag:

   $ cat example.yaml
   num: #yampl:str {{ .num }}
   $ yampl example.yaml -v num=2009
   num: "2009" #yampl:str {{ .num }}
   

2. Sequence

   $ cat example.yaml
   seq: #yampl:seq {{ .seq }}
   $ yampl example.yaml -v seq='[a, b, c]'
   seq: #yampl {{ .seq }}
     - a
     - b
     - c
   

3. Map

   $ cat example.yaml
   map: #yampl:map {{ .map }}
   $ yampl example.yaml -v map='{message: hello world}'
   map: #yampl {{ .map }}
     message: hello world