Kaniko

Description

This plugin enables you to build and publish Docker images in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-kaniko

Registry: https://hub.docker.com/r/target/vela-kaniko

Usage

NOTE:
Users should refrain from using latest as the tag for the Docker image.
It is recommended to use a semantically versioned tag instead.

Sample of building and publishing an image:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of building an image without publishing:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     dry_run: true
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of attempting the publishing of an image three times:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     push_retry: 3
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of building and publishing an image with custom tags:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world
+     tags:
+       - latest
+       - foobar

Sample of building and publishing an image with automatic tags:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     auto_tag: true
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Depending on the type of event, the image will be tagged as follows:

tag event (using v1.0.0 as an example):
- index.docker.io/octocat/hello-world:latest
- index.docker.io/octocat/hello-world:v1.0.0
all other events:
- index.docker.io/octocat/hello-world:latest
- index.docker.io/octocat/hello-world:eeea105fed7fc11bda4b43a00edfc49a5c982968

Sample of building and publishing an image with build arguments:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     build_args:
+       - FOO=bar
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of building and publishing an image with caching:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     cache: true
+     cache_repo: index.docker.io/octocat/hello-world
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of building using a snapshot mode and publishing an image with caching:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     snapshot_mode: redo
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of building using a custom platform:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world
+     custom_platform: linux/arm64/v8

NOTE: This option will only work if your Vela worker is configured appropriately.

Sample of only including repository topics starting with “id” as a value in the “io.vela.build.topics” that gets applied to the built image:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     repo_topics_filter: "^id"
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Sample of using zstd layer compression:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world
+     compression: zstd
+     compression_level: 3

NOTE: Be aware that while this may yield better compression and/or performance, many common container tools are not yet compatible with this type of compression. Use at your own risk.

Secrets

NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.

Internal

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
+   secrets: [ kaniko_username, kaniko_password ]
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world
-     username: octocat
-     password: superSecretPassword

This example will add the secrets to the publish_hello-world step as environment variables:
KANIKO_USERNAME=<value>
KANIKO_PASSWORD=<value>

External

The plugin accepts the following files for authentication:

Parameter	Volume Configuration
`password`	`/vela/parameters/kaniko/password`, `/vela/secrets/kaniko/password`, `/vela/secrets/managed-auth/password`
`username`	`/vela/parameters/kaniko/username`, `/vela/secrets/kaniko/username`, `/vela/secrets/managed-auth/username`

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
+   secrets: [ kaniko_username, kaniko_password ]
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world
-     username: octocat
-     password: superSecretPassword

This example will read the secret values in the volume stored at /vela/secrets/

Parameters

NOTE:
The plugin supports reading all parameters via environment variables or files.
Any values set from a file take precedence over values set from the environment.
The Snapshot mode can help improve performance but it is recommend to follow Kaniko’s guidelines for picking the mode.

The following parameters are used to configure the image:

Name	Description	Required	Default	Environment Variables
`auto_tag`	enables automatic tagging of images (tag or sha, and `latest`)	`false`	`false`	`PARAMETER_AUTO_TAG` `KANIKO_AUTO_TAG`
`build_args`	variables passed to image at build-time	`false`	`N/A`	`PARAMETER_BUILD_ARGS` `KANIKO_BUILD_ARGS`
`cache`	enable caching of image layers	`false`	`false`	`PARAMETER_CACHE` `KANIKO_CACHE`
`cache_repo`	specific repo to enable caching for	`false`	`N/A`	`PARAMETER_CACHE_REPO` `KANIKO_CACHE_REPO`
`compression`	compression to use (`gzip` or `zstd` - kaniko uses `gzip` if not defined)	`false`	`N/A`	`PARAMETER_COMPRESSION` `KANIKO_COMPRESSION`
`compression_level`	compression level to use (1 - 9, inclusive)	`false`	`N/A`	`PARAMETER_COMPRESSION_LEVEL` `KANIKO_COMPRESSION_LEVEL`
`context`	path to context for building the image	`true`	`.`	`PARAMETER_CONTEXT` `KANIKO_CONTEXT`
`dockerfile`	path to the file for building the image	`true`	`Dockerfile`	`PARAMETER_DOCKERFILE` `KANIKO_DOCKERFILE`
`dry_run`	enable building the image without publishing	`false`	`false`	`PARAMETER_DRY_RUN` `KANIKO_DRY_RUN`
`event`	event generated for build	`true`	set by Vela	`PARAMETER_EVENT` `KANIKO_EVENT` `VELA_BUILD_EVENT`
`force_build_metadata`	enable force adding metadata layers to build image	`false`	`false`	`PARAMETER_FORCE_BUILD_METADATA` `KANIKO_FORCE_BUILD_METADATA`
`repo_topics_filter`	regex expression to filter out repository topics	`false`	`empty slice`	`PARAMETER_REPO_TOPICS_FILTER` `KANIKO_REPO_TOPICS_FILTER`
`ignore_var_run`	sets `--ignore-var-run` kaniko flag to control whether /var/run is included in image snapshot	`false`	`true`	`PARAMETER_IGNORE_VAR_RUN` `KANIKO_IGNORE_VAR_RUN` `VELA_IGNORE_VAR_RUN`
`labels`	unique labels to add to the image	`false`	`N/A`	`PARAMETER_LABELS` `KANIKO_LABELS`
`log_level`	set the log level for the plugin	`true`	`info`	`PARAMETER_LOG_LEVEL` `KANIKO_LOG_LEVEL`
`mirror`	name of the mirror registry to use	`false`	`N/A`	`PARAMETER_MIRROR` `KANIKO_MIRROR`
`password`	password for communication with the registry	`true`	`N/A`	`PARAMETER_PASSWORD` `KANIKO_PASSWORD` `DOCKER_PASSWORD`
`push_retry`	number of retries for pushing an image to a remote destination	`false`	`0`	`PARAMETER_PUSH_RETRY` `KANIKO_PUSH_RETRY`
`registry`	name of the registry for the repository	`true`	`index.docker.io`	`PARAMETER_REGISTRY` `KANIKO_REGISTRY`
`repo`	name of the repository for the image	`true`	`N/A`	`PARAMETER_REPO` `KANIKO_REPO`
`sha`	SHA-1 hash generated for commit	`true`	set by Vela	`PARAMETER_SHA` `KANIKO_SHA` `VELA_BUILD_COMMIT`
`use_new_run`	use experimental run implementation for detecting changes without requiring file system snapshots	`false`	`false`	`PARAMETER_USE_NEW_RUN` `KANIKO_USE_NEW_RUN`
`single_snapshot`	takes a single snapshot of the filesystem at the end of the build, so only one layer will be appended to the base image	`false`	`false`	`PARAMETER_SINGLE_SNAPSHOT` `KANIKO_SINGLE_SNAPSHOT`
`snapshot_mode`	control how to snapshot the filesystem. - options: `full`, `redo`, or `time`	`false`	`N/A`	`PARAMETER_SNAPSHOT_MODE` `KANIKO_SNAPSHOT_MODE`
`tag`	tag generated for build	`false`	set by Vela	`PARAMETER_TAG` `KANIKO_TAG` `VELA_BUILD_TAG`
`tags`	unique tags of the image	`true`	`latest`	`PARAMETER_TAGS` `KANIKO_TAGS`
`tar_path`	save the image as a tarball at path	`false`	`N/A`	`PARAMETER_TAR_PATH` `KANIKO_TAR_PATH`
`target`	set the target build stage for the image	`false`	`N/A`	`PARAMETER_TARGET` `KANIKO_TARGET`
`username`	user name for communication with the registry	`true`	`N/A`	`PARAMETER_USERNAME` `KANIKO_USERNAME` `DOCKER_USERNAME`
`custom_platform`	set the custom platform for the image	`false`	`N/A`	`PARAMETER_CUSTOM_PLATFORM` `KANIKO_CUSTOM_PLATFORM`
`insecure_registries`	insecure docker registries to push or pull to/from	`false`	`empty slice`	`PARAMETER_INSECURE_REGISTRIES` `KANIKO_INSECURE_REGISTRIES`
`insecure_pull`	enable pulling from any insecure registry	`false`	`false`	`PARAMETER_INSECURE_PULL` `KANIKO_INSECURE_PULL`
`insecure_push`	enable pushing to any insecure registry	`false`	`false`	`PARAMETER_INSECURE_PUSH` `KANIKO_INSECURE_PUSH`

Template

COMING SOON!

Troubleshooting

You can start troubleshooting this plugin by tuning the level of logs being displayed:

steps:
  - name: publish_hello-world
    image: target/vela-kaniko:latest
    pull: always
    parameters:
+     log_level: trace
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world

Below are a list of common problems and how to solve them:

Last modified March 8, 2022: feat(openssh): Add SSH & SCP documentation (#287) (fe29de8f)