Mastering Knative Build: Key Features and Practical YAML Examples

Key Features of Knative Build

A Build consists of a Pipeline made up of multiple Builders, each executing one or more actions.

Each Builder runs as a container; the image is user‑specified, allowing any command to be run inside.

Kaniko can be used within a Builder to build and push container images.

BuildTemplate enables reusable step definitions.

Build can clone code from a Git repo and push images to a registry, with all authentication handled via a ServiceAccount using native Kubernetes capabilities.

Basic Build Example

apiVersion: build.knative.dev/v1alpha1
kind: Build
metadata:
  name: example-build-name
spec:
  serviceAccountName: build-auth-example
  source:
    git:
      url: https://github.com/example/build-example.git
      revision: master
  steps:
    - name: ubuntu-example
      image: ubuntu
      args: ["ubuntu-build-example", "SECRETS-example.md"]
    - image: gcr.io/example-builders/build-example
      args: ["echo", "hello-example", "build"]
    - name: dockerfile-pushexample
      image: gcr.io/example-builders/push-example
      args: ["push", "${IMAGE}"]
      volumeMounts:
        - name: docker-socket-example
          mountPath: /var/run/docker.sock
  volumes:
    - name: example-volume
      emptyDir: {}

The steps field defines the pipeline actions; it is mutually exclusive with template. Each step specifies an image that runs as a container to perform its task.

BuildTemplate for Reusable Pipelines

BuildTemplate is a Kubernetes CRD that allows sharing step definitions across builds. It can also define parameters so users can customize steps when invoking the template.

spec:
  parameters:
    - name: IMAGE
      description: Where to publish the resulting image.
    - name: DIRECTORY
      description: The directory containing the build context.
      default: /workspace
    - name: DOCKERFILE_NAME
      description: The name of the Dockerfile
      default: Dockerfile
  steps:
    - name: dockerfile-build
      image: gcr.io/cloud-builders/docker
      workingDir: "${DIRECTORY}"
      args:
        - "build"
        - "--no-cache"
        - "--tag"
        - "${IMAGE}"
        - "--file"
        - "${DOCKERFILE_NAME}"
        - "."
      volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock
    - name: dockerfile-push
      image: gcr.io/cloud-builders/docker
      args: ["push", "${IMAGE}"]
      volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock
  volumes:
    - name: docker-socket
      hostPath:
        path: /var/run/docker.sock
        type: Socket

Source Configuration

Typical sources are Git repositories or emptyDir volumes for sharing data between steps.

spec:
  source:
    git:
      url: https://github.com/knative/build.git
      revision: master
  steps:
    - image: ubuntu
      args: ["cat", "README.md"]

For shared data:

spec:
  steps:
    - image: ubuntu
      entrypoint: ["bash"]
      args: ["-c", "curl https://foo.com > /var/my-volume"]
      volumeMounts:
        - name: my-volume
          mountPath: /var/my-volume
    - image: ubuntu
      args: ["cat", "/etc/my-volume"]
      volumeMounts:
        - name: my-volume
          mountPath: /etc/my-volume
  volumes:
    - name: my-volume
      emptyDir: {}

ServiceAccount for Authentication

Builds that need to clone private repositories or push images can reference a ServiceAccount that holds the necessary secrets.

apiVersion: build.knative.dev/v1alpha1
kind: Build
metadata:
  name: test-build-with-serviceaccount-git-ssh
spec:
  serviceAccountName: test-build-robot-git-ssh
  source:
    git:
      url: [email protected]:knative/build.git
      revision: master
  steps:
    - name: config
      image: ubuntu
      command: ["/bin/bash"]
      args: ["-c", "cat README.md"]

apiVersion: v1
kind: ServiceAccount
metadata:
  name: test-build-robot-git-ssh
secrets:
  - name: test-git-ssh

apiVersion: v1
kind: Secret
metadata:
  name: test-git-ssh
  annotations:
    build.knative.dev/git-0: github.com
type: kubernetes.io/ssh-auth
data:
  ssh-privatekey: LS0tLS1CRUdJTiBSU0EgUFJJVk... (base64)
  known_hosts: Z2l0aHViLmNvbSBzc2g... (base64)

Custom Timeout

The default build timeout is 10 minutes; it can be overridden with the timeout field.

spec:
  timeout: 20m
  source:
    git:
      url: https://github.com/knative/build.git
      revision: master
  steps:
    - image: ubuntu
      args: ["cat", "README.md"]