Watch our latest talk from KubeCon + CloudNativeCon EU 2024!
Carvel Logo

Image solver for your configuration

kbld seamlessly incorporates image building, pushing, and resolution into your development and deployment workflows. Result is configuration with immutable image references.

Build Orchestration

kbld behind the scenes uses existing mature products to build images (such as Docker and Buildpack's pack) and automatically updates your configuration with the newly built digest references.

Lock References

kbld automatically finds image references within your configuration, and can produce an image lock file. Lock file can later be used to ensure exactly same image versions (with digests) are used.

YAML in, YAML out

kbld works with any YAML configuration (e.g. Kubernetes resources), hence can work with wide variety of deployment tools.

Features

Delegates building to proven tools

Orchestrates image builds (delegates to tools like Docker) and registry pushes.

Saves sources of built images

Records metadata about image sources in annotation on Kubernetes resources.

Immutable image references

Resolves image references to their digest form (immutable).

Basic Usage

# Configurations picked up from a directory
$ kbld -f examples/cassandra/ | kubectl apply -f -
# Can be used with helm charts
$ helm template my-chart --values my-vals.yml | kbld -f - | kubectl apply -f -
# ... and with kustomize
$ kustomize build ./some-app | kbld -f - | kubectl apply -f -
# ... or templated with ytt and deployed with kapp
$ ytt -f ./some-app | kbld -f - | kapp -y deploy -a some-app -f -

Examples

Resolves name-tag pair reference (nginx:1.17) into digest reference (index.docker.io/library/nginx@sha256:2539d4344...)

Input:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.17 # <-- tag reference
        ports:
        - containerPort: 80

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
  annotations:
    kbld.k14s.io/images: |
      - origins:
        - tag: 1.17
          type: resolved
          url: nginx:1.17
        url: index.docker.io/library/nginx@sha256:2539d4344...      
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: index.docker.io/library/nginx@sha256:2539d4344... # <-- resolved to digest form
        ports:
        - containerPort: 80

Builds app from local directory (configured via Config's sources), pushes image as docker.io/hk/simple-app (configured via Config's destinations), and finally resolves it to a digest reference index.docker.io/hk/simple-app@sha256:e932e46fd....

Input:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app1-deployment
  labels:
    app: app1
spec:
  replicas: 3
  selector:
    matchLabels:
      app: app1
  template:
    metadata:
      labels:
        app: app1
    spec:
      containers:
      - name: app1
        image: app1
        ports:
        - containerPort: 80
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
sources:
- image: app1
  path: . # <-- where to find app1 source
destinations:
- image: app1
  newImage: docker.io/hk/simple-app # <-- where to push app1 image

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app1-deployment
  labels:
    app: app1
  annotations:
    # informational metadata about how image was built
    kbld.k14s.io/images: |
      - origins:
        - path: /users/pivotal/workspace/simple-app
          type: local
        - dirty: false
          remoteURL: git@github.com:k14s/super-secret-simple-app
          sha: e877718521f7ccea0ab0844db0f86fe123a8d8ef
          type: git
        url: index.docker.io/hk/simple-app@sha256:e932e46fd...      
spec:
  replicas: 3
  selector:
    matchLabels:
      app: app1
  template:
    metadata:
      labels:
        app: app1
    spec:
      containers:
      - name: app1
        image: index.docker.io/hk/simple-app@sha256:e932e46fd... # <-- built and pushed image
        ports:
        - containerPort: 80

Getting started

To help you get started, see the documentation.