Write a template for yoink add

Create a template manifest and a service template, add the template from a branch, and correct permission failures on the first deploy.

Read as MarkdownEdit on GitHub

The example is a working clickhouse template of two files. After you push the files to a repo, yoink add gh:you/yourrepo/templates/clickhouse adds the template.

Before you start

  • A GitHub repo that you can push to. Consumers of the template get it from a GitHub commit.
  • A host that you can break, or a local Docker daemon, for the test deploy.

All manifest fields are in the Template manifest reference.

Write and test the template

Create the manifest

Create this directory layout in the repo. The path in a gh: ref is the path of the template directory from the repo root, here templates/clickhouse.

templates/
└── clickhouse/
    ├── template.yaml
    └── service.yaml.tmpl

Write the manifest. The manifest declares the variables, the files, and the secrets.

# templates/clickhouse/template.yaml
name: clickhouse
kind: accessory
description: ClickHouse with sealed credentials and a named volume.
yoink_min_version: "0.12.0"

variables:
  - name: service_name
    prompt: Service name
    default: clickhouse
    pattern: "^[a-z][a-z0-9-]*$"
  - name: version
    prompt: ClickHouse major version
    default: "24"
    choices: ["23", "24"]
  - name: memory
    prompt: Memory limit
    default: 1g

files:
  - dest: "services/{{ service_name }}.yaml"
    template: service.yaml.tmpl

secrets:
  - name: "{{ service_name | upper }}_PASSWORD"
    generate: random:32

include_glob: "services/*.yaml"

notes: |
  Connect from another service:
    depends_on: [{{ service_name }}]
    env:
      CLICKHOUSE_URL: tcp://{{ service_name }}:9000
    env_from_secrets:
      CLICKHOUSE_PASSWORD: {{ service_name | upper }}_PASSWORD

Give each variable a default. A yoink add --yes run (CI) fails when a variable has no default and no --var override.

Create the service template

Write the file that yoink renders through minijinja:

# templates/clickhouse/service.yaml.tmpl
services:
  - name: {{ service_name }}
    image: clickhouse/clickhouse-server
    tag: "{{ version }}-alpine"
    env:
      CLICKHOUSE_USER: app
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
    env_from_secrets:
      CLICKHOUSE_PASSWORD: {{ service_name | upper }}_PASSWORD
    run:
      volumes:
        - clickhouse-{{ service_name }}-data:/var/lib/clickhouse
      options:
        memory: {{ memory }}
        # ClickHouse needs root briefly to chown its data volume.
        user: "0:0"
        cap_add: [CHOWN, DAC_OVERRIDE, FOWNER]
        read_only: false

Make sure that the env_from_secrets: reference uses the same name that secrets[].name: in the manifest produces.

Push to a feature branch

Use a branch name with no /. In a gh: ref, the first / after the repo name ends the ref, so a branch such as feat/clickhouse-template does not resolve.

git push -u origin clickhouse-template

Add the template from the branch

Use the commit SHA, or the branch name with --refresh:

yoink add gh:you/yourrepo@clickhouse-template/templates/clickhouse \
  --refresh --yes

--refresh makes yoink resolve the branch to its latest commit SHA again. Without --refresh, yoink uses the cached branch → sha mapping and a stale version of your template.

To test a local copy with no push, pass --from-path <template-directory> in place of the gh: ref.

Deploy to a test host

yoink up --service clickhouse

The manifest validation and the validation of the rendered YAML do not find permission failures. These failures occur only when the container starts, so do not skip this step.

If the container starts with no permission failure, the template passes the test. After each change to the template, do the push, add, and deploy steps again.

Correct a permission failure on the first deploy

The container defaults of yoink are strict, and some popular images need overrides. For the reasons and for worked examples in the bundled templates, see Hardening overrides.

  1. Run docker logs <container> to get the error string.
  2. Find the error in this table.
  3. Add the override to run.options: in the service template.
  4. In a comment in the template, explain why the override is necessary.
Symptom Likely cause Override
Operation not permitted during chmod/chown of a volume cap_drop: [ALL] removes CHOWN/FOWNER cap_add: [CHOWN, DAC_OVERRIDE, FOWNER]
Operation not permitted during user-switch (gosu, su-exec, and others) Caps removed, and a user: nobody mismatch user: "0:0" + cap_add: [SETGID, SETUID]
Read-only file system (os error 30) mid-request The app writes to the rootfs (logs, pidfiles, payload buffers) read_only: false
Permission denied on a write to a volume Root owns the volume, and the container runs as nobody user: "0:0" (the entrypoint of the image usually lowers its privileges itself)

Clear the template cache

The cache is at ~/.cache/yoink/templates/<owner>__<repo>__<sha>/, or below $XDG_CACHE_HOME/yoink/templates/ if that variable is set.

If yoink uses an old version of the template, remove the cache. The next yoink add fetches the template again.

rm -rf ~/.cache/yoink/templates

See also

Type a flag, a config field, or a task.