Custom Build Script

Custom build scripts allow Skaffold users the flexibility to build artifacts with any builder they desire. Users can write a custom build script which must abide by the following contract for Skaffold to work as expected:

Contract between Skaffold and Custom Build Script

Skaffold will pass in the following additional environment variables to the custom build script:

As described above, the custom build script is expected to:

1. Build and tag the $IMAGE image
2. Push the image if $PUSH_IMAGE=true

Once the build script has finished executing, Skaffold will try to obtain the digest of the newly built image from a remote registry (if $PUSH_IMAGE=true) or the local daemon (if $PUSH_IMAGE=false). If Skaffold fails to obtain the digest, it will error out.

Configuration

To use a custom build script, add a custom field to each corresponding artifact in the build section of the skaffold.yaml. Supported schema for custom includes:

buildCommand is required and points Skaffold to the custom build script which will be executed to build the artifact. The Go templates syntax can be used to inject environment variables into the build command. For example: buildCommand: ./build.sh --flag={{ .SOME_FLAG }} will replace {{ .SOME_FLAG }} with the value of the SOME_FLAG environment variable.

Artifact Dependency

You can define dependency on other artifacts using the requires keyword. Skaffold will provide each required artifact’s built image as an environment variable keyed on the alias field that can be referenced directly in the build script.

build:
  artifacts:
  - image: image1
    custom:
      # environment variable $IMG2 will be set to the build of image2
      buildCommand: |
        cat <<EOF | docker build --tag=$IMAGE --build-arg $IMG2 -
        FROM busybox
        ARG IMG2
        RUN echo 'Got ARG IMG2=$IMG2'
        EOF        
    requires:
    - image: image2
      alias: IMG2
  - image: image2
    custom:
      buildCommand: echo 'FROM busybox' | docker build --tag=$IMAGE -

Custom Build Script Locally

In addition to these environment variables Skaffold will pass in the following additional environment variables for local builder:

Configuration

To configure custom build script locally, in addition to adding a custom field to each corresponding artifact in the build add local to you build config.

Custom Build Script in Cluster

In addition to these environment variables Skaffold will pass in the following additional environment variables for cluster builder:

Configuration

To configure custom build script in cluster, in addition to adding a custom field to each corresponding artifact in the build, add cluster to your build config.

Custom Build Script on Google Cloud Build

This configuration is currently not supported.

Dependencies for a Custom Artifact

dependencies tells the skaffold file watcher which files should be watched to trigger rebuilds and file syncs. Supported schema for dependencies includes:

Paths and Ignore

Paths and Ignore are arrays used to list dependencies. Any paths in Ignore will be ignored by the skaffold file watcher, even if they are also specified in Paths. Ignore will only work in conjunction with Paths, and with none of the other custom artifact dependency types.

custom:
  buildCommand: ./build.sh
  dependencies:
    paths:
    - pkg/**
    - src/*.go
    ignore:
    - vendor/**

Dockerfile

Skaffold can calculate dependencies from a Dockerfile for a custom artifact. Passing in the path to the Dockerfile and any build args, if necessary, will allow skaffold to do dependency calculation.

custom:
  buildCommand: ./build.sh
  dependencies:
    dockerfile:
      path: path/to/Dockerfile
      buildArgs:
        file: foo

Dependencies from a command

Sometimes you might have a builder that can provide the dependencies for a given artifact. For example bazel has the bazel query deps command. Custom artifact builders can ask Skaffold to execute a custom command, which Skaffold can use to get the dependencies for the artifact for file watching.

The command must return dependencies as a JSON array, otherwise skaffold will error out.

For example, the following configuration is valid, as executing the dependency command returns a valid JSON array.

custom:
  buildCommand: ./build.sh
  dependencies:
    command: echo ["file1","file2","file3"]

File Sync

Syncable files must be included in both the paths section of dependencies, so that the skaffold file watcher knows to watch them, and the sync section, so that skaffold knows to sync them.

Logging

STDOUT and STDERR from the custom build script will be redirected and displayed within skaffold logs.

Example

The following build section instructs Skaffold to build an image gcr.io/k8s-skaffold/example with a custom build script build.sh:

build:
  artifacts:
    - image: example
      custom:
        buildCommand: ./build.sh
        dependencies:
          paths:
            - .
          ignore:
            - README*

A sample build.sh file, which builds an image with bazel and docker:

#!/bin/bash

bazel build //:skaffold_example.tar
TAR_PATH=$(bazel info bazel-bin)
docker load -i $TAR_PATH/skaffold_example.tar

image=$(echo $IMAGE)

if [ ! -z "$image" ]; then
  pack build $image
  if $PUSH_IMAGE
  then
    docker push $image
  fi
fi