https://github.com/clevyr/yampl
Template YAML values based on line-comments.
https://github.com/clevyr/yampl
docker gotemplate kubernetes yaml
Last synced: 4 months ago
JSON representation
Template YAML values based on line-comments.
- Host: GitHub
- URL: https://github.com/clevyr/yampl
- Owner: clevyr
- License: apache-2.0
- Created: 2022-05-06T15:55:30.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-02-10T23:11:13.000Z (4 months ago)
- Last Synced: 2026-02-11T02:03:23.055Z (4 months ago)
- Topics: docker, gotemplate, kubernetes, yaml
- Language: Go
- Homepage:
- Size: 601 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Yampl
[](https://github.com/clevyr/yampl/releases)
[](https://github.com/clevyr/yampl/actions/workflows/build.yml)
[](https://goreportcard.com/report/github.com/clevyr/yampl)
[](https://sonarcloud.io/summary/new_code?id=clevyr_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
```shell
brew install clevyr/tap/yampl
```
### GitHub Actions
Click to expand
There are two actions available for CI/CD usage:
- **[clevyr/setup-yampl-action](https://github.com/clevyr/setup-yampl-action):** Installs yampl during a GitHub Action run.
- **[clevyr/yampl-action](https://github.com/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`](https://ghcr.io/clevyr/yampl)
```shell
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:
```shell
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
```shell
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
```shell
sudo apt update
```
4. Install yampl
```shell
sudo apt install yampl
```
### RPM Repository (CentOS, RHEL)
Click to expand
1. If you don't have it already, install the `ca-certificates` package
```shell
sudo yum install ca-certificates
```
2. Add Clevyr's rpm repository to `/etc/yum.repos.d/clevyr.repo`
```ini
[clevyr]
name=Clevyr
baseurl=https://rpm.clevyr.com
enabled=1
gpgcheck=0
```
3. Install yampl
```shell
sudo yum install yampl
```
### AUR (Arch Linux)
Click to expand
Install [yampl-bin](https://aur.archlinux.org/packages/yampl-bin) with your [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) of choice.
## Usage
[View the generated docs](docs/yampl.md) for flag and command reference.
Also, see [templating](#templating) and [example](#examples) sections.
## Examples
### Simple Examples
1. Template with a single value:
```shell
$ cat example.yaml
name: Clevyr #yampl {{ .name }}
$ yampl example.yaml -v name='Clevyr Inc.'
name: Clevyr Inc. #yampl {{ .name }}
```
2. Template with multiple values:
```shell
$ 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.
3. Using a [Sprig](https://masterminds.github.io/sprig/) function:
```shell
$ cat example.yaml
name: Clevyr #yampl {{ upper current }}
$ yampl example.yaml
name: CLEVYR #yampl {{ upper current }}
```
4. Using the [`repo`](#repo) helper function:
```shell
$ 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:
```yaml
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:
```shell
yampl -i nginx.yaml -v tag=1.27.0
```
The file would be updated in-place:
```yaml
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`](#repo) function to pull the existing repo through to the output.
For example, you could change the `image` line to:
```yaml
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](https://masterminds.github.io/sprig/) 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:
```gotemplate
repo "nginx:stable-alpine"
```
The above produces `nginx`.
#### `tag`
Splits a Docker repo and tag into the tag component:
```gotemplate
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:
```shell
$ 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:
```shell
$ cat example.yaml
num: #yampl:str {{ .num }}
$ yampl example.yaml -v num=2009
num: "2009" #yampl:str {{ .num }}
```
2. Sequence
```shell
$ cat example.yaml
seq: #yampl:seq {{ .seq }}
$ yampl example.yaml -v seq='[a, b, c]'
seq: #yampl {{ .seq }}
- a
- b
- c
```
3. Map
```shell
$ cat example.yaml
map: #yampl:map {{ .map }}
$ yampl example.yaml -v map='{message: hello world}'
map: #yampl {{ .map }}
message: hello world
```