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.

Build

Skaffold supports different tools for building images:

Local Build In Cluster Build Remote on Google Cloud Build
Dockerfile Yes Yes Yes
Jib Maven and Gradle Yes - Yes
Cloud Native Buildpacks Yes - Yes
Bazel Yes - -
ko Yes - Yes
Custom Script Yes Yes -

Configuration

The build section in the Skaffold configuration file, skaffold.yaml, controls how artifacts are built. To use a specific tool for building artifacts, add the value representing the tool and options for using that tool to the build section.

For detailed per-builder Skaffold Configuration options, see skaffold.yaml References.

Local Build

Local build execution is the default execution context. Skaffold will use your locally-installed build tools (such as Docker, Bazel, Maven or Gradle) to execute the build.

Configuration

To configure the local execution explicitly, add build type local to the build section of skaffold.yaml

build:
  local: {}

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

Faster builds

There are a few options for achieving faster local builds.

Avoiding pushes

When deploying to a local cluster, Skaffold defaults push to false to speed up builds. The push setting can be set from the command-line with --push.

Parallel builds

The concurrency controls the number of image builds that are run in parallel. Skaffold disables concurrency by default for local builds as several image builder types (custom, jib) may change files on disk and result in side-effects. concurrency can be set to 0 to enable full parallelism, though this may consume significant resources. The concurrency setting can be set from the command-line with the --build-concurrency flag.

When artifacts are built in parallel, the build logs are still printed in sequence to make them easier to read.

Build avoidance with tryImportMissing

tryImportMissing: true causes Skaffold to avoid building an image when the tagged image already exists in the destination. This setting can be useful for images that are expensive to build.

tryImportMissing is disabled by default to avoid the risk from importing a stale image, where the imported image is different from the image that would have been built from the artifact source. tryImportMissing is best used with a tagging policy such as imageDigest or gitCommit's TreeSha or AbbrevTreeSha variants, where the tag is computed using the artifact’s contents.

In Cluster Build

Skaffold supports building in cluster via Kaniko or Custom Build Script.

Configuration

To configure in-cluster Build, add build type cluster to the build section of skaffold.yaml.

build:
  cluster: {}

The following options can optionally be configured:

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

Faster builds

Skaffold can build multiple artifacts in parallel, by settings a value higher than 1 to concurrency. For in-cluster builds, the default is to build all the artifacts in parallel. If your cluster is too small, you might want to reduce the concurrency. Setting concurrency to 1 will cause artifacts to be built sequentially.

Remotely on Google Cloud Build

Skaffold supports building remotely with Google Cloud Build.

Google Cloud Build is a Google Cloud Platform service that executes your builds using Google infrastructure. To get started with Google Build, see Cloud Build Quickstart.

Skaffold can automatically connect to Cloud Build, and run your builds with it. After Cloud Build finishes building your artifacts, they will be saved to the specified remote registry, such as Google Container Registry.

Skaffold Google Cloud Build process differs from the gcloud command gcloud builds submit. Skaffold will create a list of dependent files and submit a tar file to GCB. It will then generate a single step cloudbuild.yaml and will start the building process. Skaffold does not honor .gitignore or .gcloudignore exclusions. If you need to ignore files use .dockerignore. Any cloudbuild.yaml found will not be used in the build process.

Configuration

To use Cloud Build, add build type googleCloudBuild to the build section of skaffold.yaml.

build:
  googleCloudBuild: {}

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.

Faster builds

Skaffold can build multiple artifacts in parallel, by settings a value higher than 1 to concurrency. For Google Cloud Build, the default is to build all the artifacts in parallel. If you hit a quota restriction, you might want to reduce the concurrency.

Restrictions

Skaffold currently supports Docker, Jib on Google Cloud Build.

Cross-platform build support

Skaffold selectively supports building for a platform that is different than the host machine platform. The target platform for an artifact can be specified in one of the following ways:

  • The pipeline’s platforms property in the skaffold.yaml file.
build:
  platforms: ["linux/arm64"]
  artifacts:
    - image: example

  • The artifact’s platforms constraints in the skaffold.yaml file. This overrides the value specified in the pipeline’s platforms property.
build:
  artifacts:
    - image: app1
      platforms: ["linux/arm64"]
    - image: app2
      platforms: ["linux/amd64"]

  • The CLI flag --platform which overrides the values set in both the previous ways.
skaffold build --platform=linux/arm64

Additionally, for skaffold dev, skaffold debug and skaffold run commands, where the build output gets deployed immediately, skaffold checks the platform for the kubernetes cluster nodes and attempts to build artifacts for that target platform.

The final list of target platforms need to ultimately be supported by the target builder, otherwise it’ll fail the build. The cross-platform build support for the various builders can be summarized in the following table:

Local Build In Cluster Build Remote on Google Cloud Build
Dockerfile Cross-platform supported Cross-platform supported but platform should match cluster node running the pod. Cross-platform supported
Jib Maven and Gradle Cross-platform and multi-platform supported - Cross-platform and multi-platform supported
Cloud Native Buildpacks Only supports linux/amd64 - Only supports linux/amd64
Bazel Cross-platform supported but requires explicit platform specific rules. Not yet implemented - -
ko Cross-platform and multi-platform supported - Cross-platform and multi-platform supported
Custom Script Cross-platform and multi-platform supported but requires user to implement it in the build script Cross-platform and multi-platform supported but requires user to implement it in the build script -