Version v1.39 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Docker Build

Skaffold supports building with Dockerfile

  1. locally
  2. in cluster
  3. on Google CloudBuild

Dockerfile with Docker locally

If you have Docker installed, Skaffold can be configured to build artifacts with the local Docker daemon.

By default, Skaffold connects to the local Docker daemon using Docker Engine APIs, though it can also use the Docker command-line interface instead, which enables artifacts with BuildKit.

After the artifacts are successfully built, Docker images will be pushed to the remote registry. You can choose to skip this step.

Configuration

To use the local Docker daemon, add build type local to the build section of skaffold.yaml. The following options can optionally be configured:

Option Description Default
push should images be pushed to a registry. If not specified, images are pushed only if the current Kubernetes context connects to a remote cluster.
tryImportMissing whether to attempt to import artifacts from Docker (either a local or remote registry) if not in the cache. false
useDockerCLI use docker command-line interface instead of Docker Engine APIs. false
useBuildkit use BuildKit to build Docker images. If unspecified, uses the Docker default.
concurrency how many artifacts can be built concurrently. 0 means “no-limit”. 1

The docker builder replaces cache references to the artifact image with the tagged image to allow caching from the previously built image.

Example

The following build section instructs Skaffold to build a Docker image gcr.io/k8s-skaffold/example with the local Docker daemon:

build:
  artifacts:
  - image: gcr.io/k8s-skaffold/example
    docker:
      cacheFrom:
      # Local Docker builder replaces cache references to the artifact image with
      # the tagged image reference, useful for caching from the previous build.
      - gcr.io/k8s-skaffold/example
  local: {}

Which is equivalent to:

build:
  artifacts:
  - image: gcr.io/k8s-skaffold/example
  local:
    useDockerCLI: false
    useBuildkit: false

Artifact dependency

You can additionally define dependency on other artifacts using the requires expression:

build:
  artifacts:
  - image: image1
    requires:
      - image: image2
        alias: IMAGE2
  - image: image2
  local: {}

The specified alias IMAGE2 becomes available as a build-arg in the Dockerfile for image1 and its value automatically set to the image built from image2.

Dockerfile in-cluster with Kaniko

Kaniko is a Google-developed open source tool for building images from a Dockerfile inside a container or Kubernetes cluster. Kaniko enables building container images in environments that cannot easily or securely run a Docker daemon.

Skaffold can help build artifacts in a Kubernetes cluster using the Kaniko image; after the artifacts are built, kaniko must push them to a registry.

Configuration

To use Kaniko, add build type kaniko to the build section of skaffold.yaml. The following options can optionally be configured:

Option Description Default
cleanup to clean the filesystem at the end of the build. false
insecure if you want to push images to a plain HTTP registry. false
insecurePull if you want to pull images from a plain HTTP registry. false
noPush if you only want to build the image, without pushing to a registry. false
force building outside of a container. false
logTimestamp to add timestamps to log format. false
reproducible used to strip timestamps out of the built image. false
singleSnapshot 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
skipTLS skips TLS certificate validation when pushing to a registry. false
skipTLSVerifyPull skips TLS certificate validation when pulling from a registry. false
skipUnusedStages builds only used stages if defined to true. Otherwise it builds by default all stages, even the unnecessaries ones until it reaches the target stage / end of Dockerfile. false
useNewRun to Use the experimental run implementation for detecting changes without requiring file system snapshots. In some cases, this may improve build performance by 75%. false
whitelistVarRun used to ignore /var/run when taking image snapshot. Set it to false to preserve /var/run/* in destination image. false
dockerfile locates the Dockerfile relative to workspace. Dockerfile
target to indicate which build stage is the target build stage.
initImage image used to run init container which mounts kaniko context.
image Docker image used by the Kaniko pod. Defaults to the latest released version of gcr.io/kaniko-project/executor.
digestFile to specify a file in the container. This file will receive the digest of a built image. This can be used to automatically track the exact image built by kaniko.
imageFSExtractRetry number of retries that should happen for extracting an image filesystem.
imageNameWithDigestFile specify a file to save the image name with digest of the built image to.
logFormat <text|color|json> to set the log format.
ociLayoutPath to specify a directory in the container where the OCI image layout of a built image will be placed. This can be used to automatically track the exact image built by kaniko.
registryMirror if you want to use a registry mirror instead of default index.docker.io.
snapshotMode how Kaniko will snapshot the filesystem.
pushRetry Set this flag to the number of retries that should happen for the push of an image to a remote destination.
tarPath path to save the image as a tarball at path instead of pushing the image.
verbosity <panic|fatal|error|warn|info|debug|trace> to set the logging level.
insecureRegistry to use plain HTTP requests when accessing a registry. []
skipTLSVerifyRegistry skips TLS certificate validation when accessing a registry. []
env environment variables passed to the kaniko pod. It also accepts environment variables via the go template syntax. []
cache configures Kaniko caching. If a cache is specified, Kaniko will use a remote cache which will speed up builds.
registryCertificate to provide a certificate for TLS communication with a given registry. my.registry.url: /path/to/the/certificate.cert is the expected format. {}
label key: value to set some metadata to the final image. This is equivalent as using the LABEL within the Dockerfile. {}
buildArgs arguments passed to the docker build. It also accepts environment variables and generated values via the go template syntax. Exposed generated values: IMAGE_REPO, IMAGE_NAME, IMAGE_TAG. {}
volumeMounts volume mounts passed to kaniko pod. []

Artifact dependency

Similar to the local Docker builder, you can define dependency on other artifacts using the requires expression:

build:
  artifacts:
  - image: image1
    requires:
    - image: image2
      alias: IMAGE2
    kaniko: {}
  - image: image2
  cluster: {}

The specified alias IMAGE2 becomes available as a build-arg in the Dockerfile for image1 and its value automatically set to the image built from image2.

Since Kaniko builds images directly to a registry, it requires active cluster credentials. These credentials are configured in the cluster section with the following options:

Option Description Default
HTTP_PROXY for kaniko pod.
HTTPS_PROXY for kaniko pod.
pullSecretPath path to the Google Cloud service account secret key file.
pullSecretName name of the Kubernetes secret for pulling base images and pushing the final image. If given, the secret needs to contain the Google Cloud service account secret key under the key kaniko-secret. kaniko-secret
pullSecretMountPath path the pull secret will be mounted at within the running container.
namespace Kubernetes namespace. Defaults to current namespace in Kubernetes configuration.
timeout amount of time (in seconds) that this build is allowed to run. Defaults to 20 minutes (20m).
dockerConfig describes how to mount the local Docker configuration into a pod.
serviceAccount describes the Kubernetes service account to use for the pod. Defaults to ‘default’.
tolerations describes the Kubernetes tolerations for the pod. []
nodeSelector describes the Kubernetes node selector for the pod. {}
annotations describes the Kubernetes annotations for the pod. {}
runAsUser defines the UID to request for running the container. If omitted, no SecurityContext will be specified for the pod and will therefore be inherited from the service account.
resources define the resource requirements for the kaniko pod.
concurrency how many artifacts can be built concurrently. 0 means “no-limit”. 0
volumes defines container mounts for ConfigMap and Secret resources. []
randomPullSecret adds a random UUID postfix to the default name of the pull secret to facilitate parallel builds, e.g. kaniko-secretdocker-cfgfd154022-c761-416f-8eb3-cf8258450b85. false
randomDockerConfigSecret adds a random UUID postfix to the default name of the docker secret to facilitate parallel builds, e.g. docker-cfgfd154022-c761-416f-8eb3-cf8258450b85. false

To set up the credentials for Kaniko refer to the kaniko docs (Note: Rename the downloaded JSON key to kaniko-secret without appending .json). Alternatively, the path to a credentials file can be set with the pullSecretPath option:

build:
  cluster:
    pullSecretName: pull-secret-in-kubernetes
    # OR
    pullSecretPath: path-to-service-account-key-file

Similarly, when pushing to a docker registry:

build:
  cluster:
    dockerConfig:
      path: ~/.docker/config.json
      # OR
      secretName: docker-config-secret-in-kubernetes

Note that the Kubernetes secret must not be of type kubernetes.io/dockerconfigjson which stores the config json under the key ".dockerconfigjson", but an opaque secret with the key "config.json".

Example

The following build section, instructs Skaffold to build a Docker image gcr.io/k8s-skaffold/example with Kaniko:

build:
  artifacts:
    - image: gcr.io/k8s-skaffold/example
      kaniko: {}
  cluster:
    pullSecretName: YOUR-PULL-SECRET-NAME

Dockerfile remotely with Google Cloud Build

Skaffold can build the Dockerfile image remotely with Google Cloud Build.

Configuration

To configure, add googleCloudBuild to build section to skaffold.yaml. The following options can optionally be configured:

Option Description Default
projectId ID of your Cloud Platform Project. If it is not provided, Skaffold will guess it from the image name. For example, given the artifact image name gcr.io/myproject/image, Skaffold will use the myproject GCP project.
diskSizeGb disk size of the VM that runs the build. See Cloud Build Reference.
machineType type of the VM that runs the build. See Cloud Build Reference.
timeout amount of time (in seconds) that this build should be allowed to run. See Cloud Build Reference.
logging specifies the logging mode. Valid modes are: LOGGING_UNSPECIFIED: The service determines the logging mode. LEGACY: Stackdriver logging and Cloud Storage logging are enabled (default). GCS_ONLY: Only Cloud Storage logging is enabled. See Cloud Build Reference.
logStreamingOption specifies the behavior when writing build logs to Google Cloud Storage. Valid options are: STREAM_DEFAULT: Service may automatically determine build log streaming behavior. STREAM_ON: Build logs should be streamed to Google Cloud Storage. STREAM_OFF: Build logs should not be streamed to Google Cloud Storage; they will be written when the build is completed. See Cloud Build Reference.
dockerImage image that runs a Docker build. See Cloud Builders. gcr.io/cloud-builders/docker
kanikoImage image that runs a Kaniko build. See Cloud Builders. gcr.io/kaniko-project/executor
mavenImage image that runs a Maven build. See Cloud Builders. gcr.io/cloud-builders/mvn
gradleImage image that runs a Gradle build. See Cloud Builders. gcr.io/cloud-builders/gradle
packImage image that runs a Cloud Native Buildpacks build. See Cloud Builders. gcr.io/k8s-skaffold/pack
concurrency how many artifacts can be built concurrently. 0 means “no-limit”. 0
workerPool configures a pool of workers to run the build.
region configures the region to run the build. If WorkerPool is configured, the region will be deduced from the WorkerPool configuration. If neither WorkerPool nor Region is configured, the build will be run in global(non-regional). See Cloud Build locations.

The googleCloudBuild builder replaces cache references to the artifact image with the tagged image to allow caching from the previously built image.

Example

The following build section, instructs Skaffold to build a Docker image gcr.io/k8s-skaffold/example with Google Cloud Build:

build:
  artifacts:
  - image: gcr.io/k8s-skaffold/example
    docker:
      cacheFrom:
      # googleCloudBuild replaces cache references to the artifact image with
      # the tagged image reference, useful for caching from the previous build.
      - gcr.io/k8s-skaffold/example
  googleCloudBuild:
    projectId: YOUR-GCP-PROJECT