kaniko

README

drone-kaniko

Drone kaniko plugin uses kaniko to build and publish Docker images to a container registry.

Plugin images are published with 1.6.0 as well as 1.9.1 kaniko version from 1.5.1 release tag. plugins/kaniko:<release-tag> uses 1.6.0 version while plugins/kaniko:<release-tag>-kaniko1.9.1 uses 1.9.1 version. Similar convention is used for plugins/kaniko-ecr & plugins/kaniko-gcr images as well.

Run the following script to install git-leaks support to this repo.

chmod +x ./git-hooks/install.sh
./git-hooks/install.sh

Build

Build the binaries with the following commands:

export GOOS=linux
export GOARCH=amd64
export CGO_ENABLED=0
export GO111MODULE=on

go build -v -a -tags netgo -o release/linux/amd64/kaniko-docker ./cmd/kaniko-docker
go build -v -a -tags netgo -o release/linux/amd64/kaniko-gcr ./cmd/kaniko-gcr
go build -v -a -tags netgo -o release/linux/amd64/kaniko-ecr ./cmd/kaniko-ecr
go build -v -a -tags netgo -o release/linux/amd64/kaniko-acr ./cmd/kaniko-acr

Docker

Build the Docker images with the following commands:

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/docker/Dockerfile.linux.amd64 --tag plugins/kaniko .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/acr/Dockerfile.linux.amd64 --tag plugins/kaniko-acr .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/gcr/Dockerfile.linux.amd64 --tag plugins/kaniko-gcr .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/ecr/Dockerfile.linux.amd64 --tag plugins/kaniko-ecr .

Usage

Operation Modes

Default Mode (Build and Push):

When neither no_push nor push_only is provided. Plugin builds and pushes the Docker image to a container registry.

Build-Only Mode (no-push):

When no_push is true and destination_tar_path is defined. Plugin performs only the image build operation and saves the resulting image tarball to the specified destination_tar_path It does not push the image to any registry.

Push-Only Mode (push-only):

When push_only is true and source_tar_path is defined. Plugin loads an existing image tarball from the specified source_tar_path and pushes the loaded image to a Container Registry. It skips the build process.

Mutually Exclusive Inputs

If both no_push and push_only inputs are provided, the plugin will:

Terminate the operation and throw an error with the message: "Inputs no-push and push-only cannot be used together. Please define only one."

Manual Tagging

docker run --rm \
    -e PLUGIN_TAGS=1.2,latest \
    -e PLUGIN_DOCKERFILE=/drone/Dockerfile \
    -e PLUGIN_REPO=foo/bar \
    -e PLUGIN_USERNAME=foo \
    -e PLUGIN_PASSWORD=bar \
    -v $(pwd):/drone \
    -w /drone \
    plugins/kaniko:linux-amd64

With expanded tagging enabled, semantic versions can be passed to PLUGIN_TAGS directly for expansion.

Note: this feature only works for build labels. Artifact labels are not supported.

docker run --rm \
    -e PLUGIN_TAGS=v1.2.3,latest \
    -e PLUGIN_EXPAND_TAG=true \
    -v $(pwd):/drone \
    -w /drone \
    plugins/kaniko:linux-amd64

would both be equivalent to

PLUGIN_TAGS=1,1.2,1.2.3,latest

This allows for passing $DRONE_TAG directly as a tag for repos that use semver tags.

To avoid confusion between repo tags and image tags, PLUGIN_EXPAND_TAG also recognizes a semantic version without the v prefix. As such, the following is also equivalent to the above:

docker run --rm \
    -e PLUGIN_TAGS=1.2.3,latest \
    -e PLUGIN_EXPAND_TAG=true \
    -v $(pwd):/drone \
    -w /drone \
    plugins/kaniko:linux-amd64

Auto Tagging

The auto tag feature of docker plugin is also supported.

When auto tagging is enabled, if any of the case is matched below, a docker build will be pushed with auto generated tags. Otherwise the docker build will be skipped.

Note: this feature only works for build labels. Artifact labels are not supported.

Git Tag Push:

docker run --rm \
    -e DRONE_COMMIT_REF=refs/tags/v1.2.3 \
    -e PLUGIN_REPO=foo/bar \
    -e PLUGIN_USERNAME=foo \
    -e PLUGIN_PASSWORD=bar \
    -e PLUGIN_AUTO_TAG=true \
    -v $(pwd):/drone \
    -w /drone \
    plugins/kaniko:linux-amd64

Tags to push:

• 1.2.3
• 1.2
• 1

Git Commit Push in default branch:

docker run --rm \
    -e DRONE_COMMIT_REF=refs/heads/master \
    -e DRONE_REPO_BRANCH=main \
    -e PLUGIN_REPO=foo/bar \
    -e PLUGIN_USERNAME=foo \
    -e PLUGIN_PASSWORD=bar \
    -e PLUGIN_AUTO_TAG=true \
    -v $(pwd):/drone \
    -w /drone \
    plugins/kaniko:linux-amd64

Tags to push:

• latest

Documentation

Index

• func MockCraneLoad(path string, loadErr error) func(string) (v1.Image, error)
• func MockCranePush(pushErr error) func(v1.Image, string) error
• type Artifact
• type Build
  • func (b Build) AutoTags() (tags []string, err error)
• type Output
• type Plugin
  • func (p Plugin) Exec() error

Functions

func MockCraneLoad

func MockCraneLoad(path string, loadErr error) func(string) (v1.Image, error)

func MockCranePush

func MockCranePush(pushErr error) func(v1.Image, string) error

Types

type Artifact

type Artifact struct {
	Tags         []string                  // Docker artifact tags
	Repo         string                    // Docker artifact repository
	Registry     string                    // Docker artifact registry
	RegistryType artifact.RegistryTypeEnum // Rocker artifact registry type
	ArtifactFile string                    // Artifact file location
}

Artifact defines content of artifact file

type Build

type Build struct {
	Args                []string // Docker build args
	ArgsNew             []string // docker build args with comma seperated values
	AutoTag             bool     // Set this to auto detect tags from git commits and semver-tagged labels
	AutoTagSuffix       string   // Suffix to append to the auto detect tags
	CacheRepo           string   // Remote repository that will be used to store cached layers
	CacheTTL            int      // Cache timeout in hours
	Context             string   // Docker build context
	DigestFile          string   // Digest file location
	Dockerfile          string   // Docker build Dockerfile
	DroneCommitRef      string   // Drone git commit reference
	DroneRepoBranch     string   // Drone repo branch
	EnableCache         bool     // Whether to enable kaniko cache
	ExpandTag           bool     // Set this to expand the `Tags` into semver-tagged labels
	IsMultipleBuildArgs bool     // env variable for fallback for docker build args
	Labels              []string // Label map
	Mirrors             []string // Docker repository mirrors
	NoPush              bool     // Set this flag if you only want to build the image, without pushing to a registry
	Platform            string   // Allows to build with another default platform than the host, similarly to docker build --platform
	PushOnly            bool     // Specify if the operation is push-only.
	Repo                string   // Docker build repository
	SkipTlsVerify       bool     // Docker skip tls certificate verify for registry
	SkipUnusedStages    bool     // Build only used stages
	SnapshotMode        string   // Kaniko snapshot mode
	SourceTarPath       string   // Path to the local tarball to be pushed
	Tags                []string // Docker build tags
	TarPath             string   // Set this flag to save the image as a tarball at path
	Target              string   // Docker build target
	Verbosity           string   // Log level

	Cache                       bool     // Enable or disable caching during the build process.
	CacheDir                    string   // Directory to store cached layers.
	CacheCopyLayers             bool     // Enable or disable copying layers from the cache.
	CacheRunLayers              bool     // Enable or disable running layers from the cache.
	Cleanup                     bool     // Enable or disable cleanup of temporary files.
	CompressedCaching           *bool    // Enable or disable compressed caching.
	ContextSubPath              string   // Sub-path within the context to build.
	CustomPlatform              string   // Platform to use for building.
	Force                       bool     // Force building the image even if it already exists.
	Git                         bool     // Branch to clone if build context is a git repository .
	ImageNameWithDigestFile     string   // Write image name with digest to a file.
	ImageNameTagWithDigestFile  string   // Write image name with tag and digest to a file.
	Insecure                    bool     // Allow connecting to registries without TLS.
	InsecurePull                bool     // Allow insecure pulls from the registry.
	InsecureRegistry            string   // Use plain HTTP for registry communication.
	Label                       string   // Add metadata to an image.
	LogFormat                   string   // Set the log format for build output.
	LogTimestamp                bool     // Show timestamps in build output.
	OCILayoutPath               string   // Directory to store OCI layout.
	PushRetry                   int      // Number of times to retry pushing an image.
	RegistryCertificate         string   // Path to a file containing a registry certificate.
	RegistryClientCert          string   // Path to a file containing a registry client certificate.
	RegistryMirror              string   // Mirror for registry pulls.
	SkipDefaultRegistryFallback bool     // Skip Docker Hub and default registry fallback.
	Reproducible                bool     // Create a reproducible image.
	SingleSnapshot              bool     // Only create a single snapshot of the image.
	SkipTLSVerify               bool     // Skip TLS verification when connecting to the registry.
	SkipPushPermissionCheck     bool     // Skip permission check when pushing.
	SkipTLSVerifyPull           bool     // Skip TLS verification when pulling.
	SkipTLSVerifyRegistry       bool     // Skip TLS verification when connecting to a registry.
	UseNewRun                   bool     // Use the new container runtime (`runc`) for builds.
	IgnoreVarRun                *bool    // Ignore `/var/run` when copying from the context.
	IgnorePath                  string   // Ignore files matching the specified path pattern.
	IgnorePaths                 []string // Ignore files matching the specified path pattern.
	ImageFSExtractRetry         int      // Number of times to retry extracting the image filesystem.
	ImageDownloadRetry          int      // Number of times to retry downloading layers.
}

Build defines Docker build parameters.

func (Build) AutoTags

func (b Build) AutoTags() (tags []string, err error)

Returns the auto detected tags. See the AutoTag section of https://plugins.drone.io/drone-plugins/drone-docker/ for more info.

type Output

type Output struct {
	OutputFile string // File where plugin output are saved
}

Output defines content of output file

type Plugin

type Plugin struct {
	Build    Build    // Docker build configuration
	Artifact Artifact // Artifact file content
	Output   Output   // Output file content

	// parameters for UTs to mock crane functionality
	LoadImageFromTarball func(string) (v1.Image, error)
	PushImageToRegistry  func(v1.Image, string) error
}

Plugin defines the Docker plugin parameters.

func (Plugin) Exec

func (p Plugin) Exec() error

Exec executes the plugin step