:warning: CBI is no longer under active development, in favor of Tekton. See tektoncd/pipeline and tektoncd/catalog.

---

CBI: Container Builder Interface for Kubernetes

CBI provides a vendor-neutral interface for building (and pushing) container images on top of a Kubernetes cluster, with support for several backends such as Docker, BuildKit, Buildah, kaniko, img, Google Cloud Container Builder, Azure Container Registry Build and OpenShift Source-to-Image (S2I).

<!-- TOC generator: https://github.com/stakiran/intoc -->

• Current status
  • Specification
  • Implementation
• Quick start
  • Installation
  • Run your first buildjob
• Advanced usage
  • Push to a registry
  • Build contexts
    • ConfigMap context
    • Git context
    • HTTP(S) context
    • Rclone context (S3, Dropbox, SFTP, and many)
  • Plugin
    • Specify the plugin explicitly
    • Google Cloud Container Builder plugin
    • Azure Container Registry Build plugin
    • Openshift Source-to-Image plugin
• Design (subject to change)
  • Components
  • Build context
    • BuildkitSession (Planned)
• Contribute to CBI
  • Testing
  • Local testing with DinD
• FAQs
  • Q: Does CBI standardize the Dockerfile specification?
  • Q: Does CBI replace BuildKit?
  • Q: Is CBI a part of Kubernetes, a Kubernetes incubator, or a CNCF project?

Current status

Specification

• CBI CRD: pre-alpha, see pkg/apis/cbi/v1alpha1/types.go.
• CBI plugin API: pre-alpha, see pkg/plugin/api/plugin.proto.

Implementation

• CBI controller daemon (cbid): pre-alpha, see cmd/cbid.

• Plugins (all of them are pre-alpha):

Plugin |Backend |Dockerfile|cloudbuild.yaml|OpenShift S2I|BuildKit LLB|ACB Pipeline ----------|------------------------------------------------------------------------------------------|----------|-----------------|-------------|------------|------------ docker |Docker |Yes ✅ | | | | buildkit|BuildKit |Yes ✅ | | |Planned | buildah |Buildah |Yes ✅ | | | | kaniko |kaniko |Yes ✅ | | | | img |img |Yes ✅ | | | | gcb |Google Cloud Container Builder |Yes ✅ |Yes ✅ | | | acb |Azure Container Registry Build|Yes ✅ | | |Planned |Planned s2i |OpenShift Source-to-Image (S2I) | | |Yes ✅ | |

• Planned plugins (subject to change): Bazel, Singularity, OpenShift Image Builder, Orca, ...

• Context providers (available for all plugins)

  • ConfigMap
  • Git, with support for SSH secret
  • HTTP(S)
  • Rclone: Amazon Drive, Amazon S3, Backblaze B2, Box, Ceph, DigitalOcean Spaces, Dreamhost, Dropbox, FTP, Google Cloud Storage, Google Drive, HTTP, Hubic, IBM COS S3, Memset Memstore, Microsoft Azure Blob Storage, Microsoft OneDrive, Minio, Nextloud, OVH, Openstack Swift, Oracle Cloud Storage, Ownloud, pCloud, put.io, QingStor, Rackspace Cloud Files, SFTP, Wasabi, WebDAV, Yandex Disk

• Planned context providers: BuildKitSession

Please feel free to open PRs to add other plugins.

Quick start

Requires Kubernetes 1.9 or later.

Installation

$ kubectl apply -f https://raw.githubusercontent.com/containerbuilding/cbi/master/cbi-latest.yaml

Everything (except CustomResourceDefinition, ClusterRole, and ClusterRoleBinding) will be installed to the cbi-system namespace.

You may edit the YAML file to change the namespace or to add NetworkPolicy.

<details> <summary>Hint for Google Kubernetes Engine (GKE) users</summary> <p> If you hit <a href="https://stackoverflow.com/questions/46307325/gke-clusterrolebinding-for-cluster-admin-fails-with-permission-error">an error while creating <code>clusterrolebindings</code></a>, you need to execute <code>kubectl</code> command as follows: <pre> $ pw=$(gcloud --format json container clusters describe ${YOUR_GKE_CLUSTER_NAME} | jq -r .masterAuth.password) $ kubectl --username=admin --password=${pw} ... </pre> </p> </details> <details> <summary>Hint for OpenShift users</summary> <p> <code>oc login -u system:admin -n default</code> might be needed before running <code>kubectl</code>.

You would also need to enable privileged containers for most plugins. (how?)

</p> </details>

The CBI controller daemon and the following plugins will be installed:

Plugin | Requirements --------- | ------------------------------ docker | Docker needs to be installed on the hosts buildah | Privileged containers needs to be enabled buildKit| Privileged containers needs to be enabled kaniko | None (Google Cloud is not needed) img | Privileged containers needs to be enabled (See kubernetes/community#1934 and Jess's blog for the ongoing work to remove this requirement) gcb | Requires Google Cloud service account with IAM roles, see this section (Your cluster does not need to be GKE or on GCE) acb | Requires Azure service principal with IAM roles, see this section (Your cluster does not need to be AKS or on Azure VMs) s2i | Docker needs to be installed on the hosts (OpenShift is not needed)

The default plugin is docker.

You may edit the YAML file to remove unneeded plugins or change the priorities.

Run your first buildjob

Create a buildjob ex-git-nopush from examples/ex-git-nopush.yaml:

$ kubectl create -f https://raw.githubusercontent.com/containerbuilding/cbi/master/examples/ex-git-nopush.yaml
buildjob "ex-git-nopush" created

Make sure the buildjob is created:

$ kubectl get buildjobs
NAME      AGE
ex-git-nopush       3s

Inspect the underlying job and the result:

$ kubectl get job $(kubectl get buildjob ex-git-nopush --output=jsonpath={.status.job})
NAME      DESIRED   SUCCESSFUL   AGE
ex-git-nopush-job   1         1            30s
$ kubectl logs $(kubectl get pods --selector=job-name=ex-git-nopush-job --show-all --output=jsonpath={.items..metadata.name})
Sending build context to Docker daemon 79.87 kB
Step 1 : FROM alpine:latest
...
Successfully built bef4a548fb02

Delete the buildjob (and the underlying job)

$ kubectl delete buildjobs ex-git-nopush
buildjob "ex-git-nopush" deleted

Advanced usage

Push to a registry

First you need to create a credential using kubectl create secret docker-registry .... See Kubernetes's manual.

<details> <summary>Hint for Amazon Elastic Container Registry (ECR) users</summary> <p> You can create the credential as follows (expires per 12 hours): <pre> $ TOKEN=`aws ecr get-authorization-token --output text --query authorizationData[].authorizationToken | base64 -d | cut -d: -f2` $ kubectl create secret docker-registry my-registry-secret \ --docker-server=https://12345678.dkr.ecr.ap-northeast-1.amazonaws.com \ --docker-username=AWS \ --docker-password="${TOKEN}" \ --docker-email="${EMAIL}" </pre> </p> </details> <details> <summary>Hint for Google Container Registry (GCR) users</summary> <p> See <a href="http://docs.heptio.com/content/private-registries/pr-gcr.html">here</a> for creating the credential. </p> </details> <details> <summary>Hint for Azure Container Registry (ACR)