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 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 yampl example.yaml ...
APT Repository (Ubuntu, Debian)
Click to expand
-
If you don't have it already, install the
ca-certificatespackagesudo apt install ca-certificates -
Add Clevyr's apt repository
echo 'deb [trusted=yes] https://apt.clevyr.com /' | sudo tee /etc/apt/sources.list.d/clevyr.list -
Update apt repositories
sudo apt update -
Install yampl
sudo apt install yampl
RPM Repository (CentOS, RHEL)
Click to expand
-
If you don't have it already, install the
ca-certificatespackagesudo yum install ca-certificates -
Add Clevyr's rpm repository to
/etc/yum.repos.d/clevyr.repo[clevyr] name=Clevyr baseurl=https://rpm.clevyr.com enabled=1 gpgcheck=0 -
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.
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
-
Template with a single value:
$ cat example.yaml name: Clevyr #yampl {{ .name }} $ yampl example.yaml -v name='Clevyr Inc.' name: Clevyr Inc. #yampl {{ .name }} -
Template with multiple values:
$ cat example.yaml image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }} $ yampl example.yaml -v tag=stable image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }} -
Using a Sprig function:
$ cat example.yaml name: Clevyr #yampl {{ upper .Value }} $ yampl example.yaml name: CLEVYR #yampl {{ upper .Value }} -
Using the
repohelper function:$ cat example.yaml image: nginx:1.20.1 #yampl {{ repo .Value }}:{{ .tag }} $ yampl example.yaml -v tag=1.21.8 image: nginx:1.21.8 #yampl {{ repo .Value }}:{{ .tag }}
Kubernetes Deployment
Click to expand
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.
Advanced Usage
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 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 }}
Documentation
¶
There is no documentation for this package.
Source Files
Directories