sheaf

Manages bundles of Kubernetes components.

sheaf is a tool that can create a bundle of Kubernetes components. It can generate an archive from the bundle that can be distributed for use in Kubernetes clusters. The initial idea was inspired by inspired by CNAB. It answers the question: how can I distribute Kubernetes manifests with their associated images?

Why sheaf?

You want to create a distributable archive of Kubernetes manifests and their images
The Kubernetes clusters you are working with are potentially air-gapped and don't have access to the Internet.

Features:

Manages a bundle of Kubernetes manifests
Package a bundle into an archive
Relocate images referenced in a bundle archive to another registry
Generate manifests contained in a bundle archive with optionally relocated images

Getting started

sheaf is currently in an alpha state. We are releasing the tool early as a preview.

Install/Upgrade

go get -u github.com/bryanl/sheaf/cmd/sheaf

Initialize Bundle

sheaf init <bundle directory>

Initialize a sheaf project:

Creates the directory bundle directory.
Creates a bundle configuration in project/bundle.json
Creates a manifests directory in project/app/manifests

Add Manifests to Bundle

Repeat the following for each manifest (or pass multiple -f switches):

sheaf manifest add <bundle directory> -f <manifest path or URL>

Package Bundle

sheaf archive pack <bundle directory> <archive path>

Create an archive of <bundle directory> with any images found by scanning the manifests together with any listed in bundle.json.

Stage Bundle

sheaf archive reloate <archive path> <prefix>

Relocate the images located in the archive to a registry repository with <prefix>. Images will be renamed.

Generate Manifest

sheaf manifest show <archive path> [--prefix=<prefix>]

Generate manifests stored in the archive to stdout. If <prefix> is specified, the images in the manifests will be rewritten to the prefixed location.

Create user defined images

With Custom Resource Definitions, it is possible to define locations that sheaf cannot detect automatically. sheaf allows the user to create user defined images. For example, if you have a custom resource with API version x.bryanl.dev/v1 and kind Config with a container image specified at .spec.image, you can use the following command to update the sheaf configuration.

sheaf config set-udi --bundle-path project-path --api-version x.bryanl.dev/v1 --kind Config --json-path '{.spec.image}'

There is also support for arrays of images as well.

sheaf config set-udi --bundle-path project-path \
  --api-version x.bryanl.dev/v1 \
  --kind SecondaryConfig \
  --json-path '{.spec.images}'
  --type multiple

When sheaf is building a bundle archive or generating manifests, it will use the user defined mappings.

Finding images

There are myriad ways to specify an image in a manifest. sheaf can detect images defined in pod specs that are in Pods themselves or in a pod Spec template (e.g., in a Deployment). This heuristic works in a large number of cases. With Kubernetes and Custom Resource Definitions it is possible to define images in other locations as well. sheaf has a method called "user defined images", that allows custom locations to be created.

Example:

sheaf config set-udi --bundle-path project-path --api-version caching.internal.knative.dev/v1alpha1 --kind Image --json-path '.spec.image'

In this case, when sheaf is parsing the Image kind API version caching.internal.knative.dev/v1alpha1 it will use the JSON path .spec.image to locate an image. In this case:

---
apiVersion: caching.internal.knative.dev/v1alpha1
kind: Image
metadata:
  labels:
    serving.knative.dev/release: "v0.12.0"
  name: queue-proxy
  namespace: knative-serving
spec:
  image: gcr.io/knative-releases/knative.dev/serving/cmd/queue@sha256:3932262d4a44284f142f4c49f707526e70dd86317163a88a8cbb6de035a401a9

sheaf will identify gcr.io/knative-releases/... as an image.

Examples of JSON path queries:

.spec.images[*]: Looks for an array of images in .spec.images
..spec.containers[*].image: This is the method that sheaf uses to find images in a Pod spec template

fstrudel/sheaf