Usage

Getting started

To get started with Jalapeno, you need to install the CLI tool. You can find the installation instructions here.

Then you can bootstrap a new recipe (aka template) by running:

jalapeno create recipe my-recipe

After this you should have a new folder called my-recipe with the following structure:

my-recipe
├── recipe.yml
├── templates
│   └── README.md
└── tests
    └── defaults
        ├── test.yml
        └── files
            └── README.md

The templates directory contains the templates which will be rendered to the project directory. You can add and edit files there or you can already execute the recipe (render the templates) to your project directory by running:

mkdir my-project && cd my-project
jalapeno execute my-recipe

# OR

mkdir my-project
jalapeno execute my-recipe -d my-project

tip

You can also execute any of the examples from the Jalapeno repository, for example:

git clone git@github.com:futurice/jalapeno.git
jalapeno execute ./jalapeno/examples/variable-types

Or execute them directly from GitHub Container Registry:

jalapeno execute oci://ghcr.io/futurice/jalapeno/examples/variable-types:v0.0.0

tip

You can also set the values with --set flag or with environment variables when executing the recipe. For example:

jalapeno execute my-recipe --set MY_VAR=foo

# OR

export JALAPENO_VAR_MY_VAR=foo
jalapeno execute my-recipe

After this, the project directory should have the following files:

my-project
├── .jalapeno
│   └── sauces.yml
└── README.md

The .jalapeno directory contains files which Jalapeno uses internally. For example sauces.yml is Jalapeno metadata file which contains information about the sauces (aka executed recipes). This file is used to check for updates for the recipes later.

The rest of the files are rendered from the templates. You can edit the templates and execute the recipe again to update the files.

Templating

Templates are done by using Go templates extended with sprig functions. Examples of how to write these templates can be found in this article and in the example recipe.

The following context is available on the templates:

• .Recipe: Metadata object of the recipe
  • .Recipe.APIVersion: The API version which the recipe file uses
  • .Recipe.Name: The name of the recipe
  • .Recipe.Version: The current version of the recipe
  • .Recipe.Source: URL to source code for this recipe
• .ID: An UUID which is generated after the first execution of the recipe. It can be used to generate unique pseudo-random values which stay the same over the upgrades, for example my-resource-{{ sha1sum .ID | trunc 5 }}
• .Variables: Object which contains the values of the variables defined for the recipe. Example: {{ .Variables.FOO }}

tip

You can use templates in the filenames as well. For example, if you want to create a file with a name defined by a variable, you can use {{ .Variables.MY_FILE_NAME }}.md. See the example recipe. The same context is available for the filenames as for normal templates.

note

Template files starting with _ are not rendered to the output. This is useful when you have a file which contains helper templates for other files, like _helpers.yml.

Template only specific type of files

By defining templateExtension property in the recipe.yml file, you can define that only the files with the given file extensions should be rendered from the templates directory. The rest of the files will be copied as is. This is useful when there are files that do not need templating, but you would still need to escape the {{ and }} characters (for example Taskfiles).

Variables

Recipe variables let you define values which users need to provide to be able to render the templates. Variables are defined in the recipe.yml file. You can check the schema here.

Variable types

Recipe variables support the following types:

• String
• Boolean
• Select (predefined options)
• Multi-select (predefined options)
• Table

You can see examples of all the possible variables in the example recipe.

note

If you need to use numbers in the templates, you can use the atoi function to convert a string variable to an integer: {{ .Variables.FOO | atoi }}

Validation

Variables can be validated by defining validators property for the variable. Validators support regular expression pattern matching, and table validators also have column value uniqueness validator.

Publishing recipes

Jalapeno supports publishing and storing recipes in OCI-compatible registries. This means that versioned recipes can be pushed and pulled to/from ordinary Container Registries. This is useful when you want to make your recipes available or you want to check for updates for the recipe manually or programmatically from a CI/CD pipeline.

Pushing a recipe to Container registry

You can push a recipe to a Container registry by using the jalapeno push command. For authentication, you can use docker login before pushing the recipe or provide credentials directly to the jalapeno push command by using flags. For example:

jalapeno create recipe my-recipe

# You can find possible authentication methods to Github Container Registry at https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry
docker login ghcr.io -u my-user

jalapeno push my-recipe ghcr.io/my-user/my-recipe

After this, you should be able to see the recipe in the Container registry from the UI or by running:

docker inspect ghcr.io/my-user/my-recipe:v0.0.0

note

The tag of the recipe in Container Registry is automatically determined by the version in the recipe.yml file. So if you want to push a new version of the recipe, you need to update the version in the recipe.yml file first. If you want to use the latest tag, set the --latest flag when pushing the recipe.

Executing a recipe from Container registry

You can execute a recipe directly from Container registry by using the jalapeno execute command. For example:

mkdir my-project && cd my-project
jalapeno execute oci://ghcr.io/my-user/my-recipe:v0.0.0

Another way is to pull the recipe first on your local machine and then execute it:

mkdir my-project && cd my-project
jalapeno pull oci://ghcr.io/my-user/my-recipe:v0.0.0
jalapeno execute my-recipe

Executing multiple recipes with a manifest file

You can execute multiple recipes at once by using a manifest file. The manifest file is a YAML file which contains the list of recipes which should be executed. The manifest file should be in the following format:

apiVersion: v1
recipes:
  - name: recipe-a
    version: v0.0.1
    repository: ./path/to/local/recipe-a
  - name: recipe-b
    version: v0.0.1
    repository: oci://url/to/remote/recipe-b
    values:
      MY_VAR: "Hello World" # Predefined values for the recipe

After you've created the manifest file, you can execute the recipes by running:

jalapeno execute ./path/to/manifest.yml -d my-project

Checking updates for a recipe

After you have executed a recipe, Jalapeno will create a .jalapeno/sauces.yml file in the project directory. This file contains information about the executed recipes and their versions. If the recipe was executed directly from a Container Registry, the registry URL is also stored in the file for checking for new versions. To check the new versions for the recipes, you can run:

jalapeno check

This will check for updates for all the recipes in the project directory. You can also check for updates for a specific recipe by running:

jalapeno check --recipe my-recipe

If you've executed the recipe from a local directory and the registry URL is still unknown, you can set the registry URL manually by running:

jalapeno check --recipe my-recipe --from oci://ghcr.io/my-user/my-recipe

tip

If you want to run the check in a CI/CD pipeline (like Github Actions), you can check the examples/github-action recipe on how to do it or you can execute it in your project with jalapeno execute oci://ghcr.io/futurice/jalapeno/examples/github-action:v0.0.0.

If you want to start upgrading the recipes to the latest version right away, you can run:

jalapeno check --upgrade

Upgrading recipes

You can upgrade a recipe by running:

jalapeno upgrade oci://ghcr.io/my-user/my-recipe:v2.0.0

Note that the new recipe version needs to be the same or newer than the previous version. Doing rollbacks with the upgrade command is not supported at the moment.

If you've modified the files which were originally generated by the recipe, Jalapeno will notice them while doing the upgrade. It will ask if you want to overwrite the modified files with the newer versions or keep the modified ones.

Updating recipe version and changelog

You can update the recipe version number and write a changelog with

jalapeno bumpver path/to/recipe

This will prompt you for the semver increment (patch/minor/major) of the update and an optional multiline comment for the changelog. Ctrl+S exits the multiline editor and saves your changes. If a changelog doesn't already exist for a given recipe, bumpver will initialize it with the current version number and message "Init version"

You can alternatively specify a version number and message directly with

jalapeno bumpver path/to/recipe --version=v0.0.2 --message="Hello world"

Creating tests for a recipe

To bootstrap a test case for a recipe, you can run:

jalapeno create test -d ./my-recipe

After that, the following structure should be created in the recipe directory:

my-recipe
├── ...
└── tests
    └── example
        ├── files/
        └── test.yml

The test.yml file contains the configuration for the test case which will be executed when running the jalapeno test command. The configuration contains, for example, the values for the template variables which should be used when rendering the recipe. The files directory contains the expected files which the recipe should generate. You can add more test cases by creating new directories under the tests directory. In this case, the test case name is example.

To update the current recipe output as the expected output to all tests, you can run:

jalapeno test ./my-recipe --update-snapshots

After you've created the test cases, you can run the tests by running:

jalapeno test ./my-recipe