yampl

README

Yampl

Yampl (yaml + tmpl) is a simple tool to template 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 is an Action provided for use during CI/CD. See clevyr/yampl-action for more details.

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 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
   

Usage

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

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 }}.

The previous value is always available via .Value (.Val or .V if you're feeling lazy).

Functions

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

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

Examples

Simple Examples

1. Template with a single value:

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

2. Template with multiple values:

   $ cat example.yaml
   image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}
   $ yampl -v tag=stable example.yaml
   image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }}
   

3. Using a Sprig function:

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

Kubernetes Deployment

Here is a simple Kubernetes Deployment with an Nginx image:

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

Notice the yaml comment on the same line as image.

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

yampl -i nginx.yaml -v tag=1.21.6

The file would be updated in-place:

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

If I wanted to repeat myself even less, I could utilize the repo function to pull the existing repo through. I could define the image template as:

image: nginx:1.21.6 #yampl {{ repo .Value }}:{{ .tag }}

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

Tags

By default, templated values are not explicitly quoted. This can cause problems with some tools that require specific types. If you require a field 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

For example, the following could be interpreted as either a string or an int:

$ cat example.yaml
num: "" #yampl {{ .num }}
$ yampl -v num=2009 example.yaml
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 -v num=2009 example.yaml
num: "2009" #yampl:str {{ .num }}