From 799b496c4b16937c82f912af29a2cc4fa60ffb09 Mon Sep 17 00:00:00 2001 From: Dmitriy Kalinin Date: Thu, 23 May 2019 22:24:33 +0200 Subject: [PATCH] improve description --- README.md | 19 +++++------ pkg/kbld/website/js/app.css | 1 + pkg/kbld/website/templates/index.html | 45 +++++++++++++++++++++------ 3 files changed, 47 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index bb21ba44..55a94796 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,21 @@ - Website: https://get-kbld.io - Slack: [#k14s in Kubernetes slack](https://slack.kubernetes.io) -`kbld` can +`kbld` seamlessly incorporates image building and image pushing into your development and deployment workflows. -- resolve images to their *immutable* image references (digests) -- optionally build Docker images (by delegating to tools such as Docker) -- export set of images as a single tarball, and import into a different registry +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*) ([details](https://get-kbld.io/#why)) +- Provides a way to transport set of images in a single tarball between registries - maintaining exactly same digests, hence guaranteeing exactly same content +- Not specific to Kubernetes, but works really well with Kubernetes configuration files ![](docs/kbld-screenshot.png) -Example of using [ytt](https://github.com/k14s/ytt) + kbld + [kapp](https://github.com/k14s/kapp) to deploy an application: - -```bash -ytt template -f kubernetes-manifests/ | kbld -f- | kapp -y deploy -a app1 -f- -``` +See [building and deploying simple Go application to Kubernetes example](https://github.com/k14s/k8s-simple-app-example#step-3-building-container-images-locally) that uses kbld. ## Docs diff --git a/pkg/kbld/website/js/app.css b/pkg/kbld/website/js/app.css index 10ba2c60..4d027b72 100644 --- a/pkg/kbld/website/js/app.css +++ b/pkg/kbld/website/js/app.css @@ -139,6 +139,7 @@ code, .terminal, .logo { border-width: 0; vertical-align: text-top; } +#before-after th { font-weight: bold; } #before-after .before, #before-after .after { font-size: 80%; diff --git a/pkg/kbld/website/templates/index.html b/pkg/kbld/website/templates/index.html index 36ec8eeb..abd464d6 100644 --- a/pkg/kbld/website/templates/index.html +++ b/pkg/kbld/website/templates/index.html @@ -14,8 +14,8 @@

-

kbld is a tool centered around immutable
- Docker image references (i.e. digests) for Kubernetes configuration.

+

kbld seamlessly incorporates image building
+ and image pushing into your development and deployment workflows.

Github @@ -26,20 +26,26 @@

-

Why?

+

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
    • +
-

Docker images can be referenced by their name (nginx), name-tag pair (nginx:1.14), or a digest (nginx@sha256:c398dc3f2...). Using non-digest methods may lead to hard to find deployment inconsistencies, hence it's a good practice to use image digests as they uniquely represent a particular image and cannot change.

+

Why Digest References?

-

kbld helps Kubernetes users convert non-digest image references to their digest form so that it's easier to track which images are used and how they change over time.

- -

Additionally, kbld can orchestrate image building (delegates to tools like Docker) and pushing (to registries) and capture digest references of built images.

+

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 -R -f examples/cassandra/ | kubectl apply -f -
+$ 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 -
@@ -48,13 +54,17 @@ 
Basic Usage

 $ kustomize build ./some-app | kbld -f - | kubectl apply -f -
 
 # ... or templated with ytt and deployed with kapp
-$ ytt template -R -f ./some-app | kbld -f - | kapp -y deploy -a some-app -f -
+$ ytt template -f ./some-app | kbld -f - | kapp -y deploy -a some-app -f -

Examples

+ + + + @@ -91,6 +101,13 @@

Examples

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: @@ -162,6 +179,16 @@

Examples

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:
Input filestdout

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