Part of k14s.io: ytt | kbld | kapp | kwt

Features

  • Orchestrates image builds (delegates to tools like Docker) and registry pushes
  • Works with local Docker daemon and remote registries, for development and production cases
  • Records metadata about image sources in annotation on Kubernetes resources (see examples below)
  • Resolves image references to their digest form (immutable) (see "why" below)
  • Provides a way to transport set of images in a single tarball between registries
  • Not specific to Kubernetes, but works really well with Kubernetes configuration files

Why Digest References?

Docker images can be referenced by their name (nginx), name-tag pair (nginx:1.14), or a digest (nginx@sha256:c398dc3f2...). One can avoid potential deployment inconsistencies by using digest references as they are immutable, and therefore always points to an exact image. kbld helps Kubernetes users convert image references to their digest form to make sure exact image is used during deploys.

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

Input file stdout

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

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.7.9
        ports:
        - containerPort: 80
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
  annotations:
    kbld.k14s.io/images: |
      - Metas:
        - Tag: 1.7.9
          Type: resolved
          URL: nginx:1.7.9
        URL: index.docker.io/library/nginx@sha256:c398dc3f2...
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: index.docker.io/library/nginx@sha256:c398dc3f2...
        ports:
        - containerPort: 80

Builds app from local directory (configured via Sources), pushes image as docker.io/dkalinin/simple-app (configured via ImageDestinations), and finally resolves it to a digest reference index.docker.io/dkalinin/simple-app@sha256:e932e46fd....

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

#! Specifies where to find app1 image source
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Sources
sources:
- image: app1
  path: .

#! Specifies where to push app1 image
---
apiVersion: kbld.k14s.io/v1alpha1
kind: ImageDestinations
destinations:
- image: app1
  newImage: docker.io/dkalinin/simple-app

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app1-deployment
  labels:
    app: app1
  annotations:
    kbld.k14s.io/images: |
      - Metas:
        - 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/dkalinin/simple-app@sha256:e932e46fd...
spec:
  replicas: 3
  selector:
    matchLabels:
      app: app1
  template:
    metadata:
      labels:
        app: app1
    spec:
      containers:
      - name: app1
        image: index.docker.io/dkalinin/simple-app@sha256:e932e46fd...
        ports:
        - containerPort: 80