ksonnet

README

ksonnet

Official Site

ksonnet is a framework for writing, sharing, and deploying Kubernetes application manifests. With its CLI, you can generate a complete application from scratch in only a few commands, or manage a complex system at scale.

Specifically, ksonnet allows you to:

• Reuse common manifest patterns (within your app or from external libraries)
• Customize manifests directly with powerful object concatenation syntax
• Deploy app manifests to multiple environments
• Diff across environments to compare two running versions of your app
• Track the entire state of your app configuration in version controllable files

All of this results in a more iterative process for developing manifests, one that can be supplemented by continuous integration (CI).

Install

The ksonnet CLI, ks, can be installed in three different ways. Choose the method that best matches your setup:

Homebrew on macOS

If you are using Homebrew on macOS, you can install ks with the following command:

brew install ksonnet/tap/ks

Download a prebuilt binary for your OS

See the releases page to download the latest released binary.

Manually build and install

You can download and manually build from source by following these instructions.

Run through an example

Here we provide some commands that show some basic ksonnet features in action. You can run these commands to deploy and update a basic web app UI, via a Kubernetes Service and Deployment. This app is shown below:

Note that we will not be implementing the entire app in this example, so the buttons will not work!

Minimal explanation is provided here, and only basic ksonnet features are shown---this is intended to be a quick demonstration. If you are interested in learning more, see Additional Documentation.

Prerequisites

• You should have access to an up-and-running Kubernetes cluster — supported versions are 1.7 (default) and 1.8 (beta).

  If you do not have a cluster, choose a setup solution from the official Kubernetes docs.

• You should have kubectl installed. If not, follow the instructions for installing via Homebrew (MacOS) or building the binary (Linux).

• Your $KUBECONFIG should specify a valid kubeconfig file, which points at the cluster you want to use for this demonstration.

Commands

Start by creating your app directory. If you are running Kubernetes 1.8.x, you'll need to add --api-spec=version:v1.8.0 to the end of the following command:

# The ks-example app directory is created at the current path, and the
# app itself references your current cluster using $KUBECONFIG
ks init ks-example

You can copy and paste the commands below to deploy the web app UI:

# 'ks' commands should be run within a ksonnet app directory
cd ks-example

# Autogenerate a basic manifest
ks generate deployed-service guestbook-ui \
  --image gcr.io/heptio-images/ks-guestbook-demo:0.1 \
  --type ClusterIP

# Deploy your manifest to your cluster
ks apply default

Now there should be a Deployment and Service running on your cluster! Try accessing the guestbook-ui service in your browser. (How you do this may depend on your cluster setup).

If you are unsure what to do, we suggest using kubectl proxy.

# Set up an API proxy so that you can access the 'guestbook-ui' service locally
kubectl proxy > /dev/null &
PROXY_PID=$!
QUICKSTART_NAMESPACE=$(kubectl get svc guestbook-ui -o jsonpath="{.metadata.namespace}")
GUESTBOOK_SERVICE_URL=http://localhost:8001/api/v1/proxy/namespaces/$QUICKSTART_NAMESPACE/services/guestbook-ui
open $GUESTBOOK_SERVICE_URL

(Remember, the buttons won't work in this example.)

Now let's try upgrading the container image to a new version:

# Bump the container image to a different version
ks param set guestbook-ui image gcr.io/heptio-images/ks-guestbook-demo:0.2

# View updated param values
ks param list

# Update your cluster with your latest changes
ks apply default

Check out the webpage again in your browser (force-refresh to update the javascript). Notice that it looks different! Clean up:

# Teardown
ks delete default

# There should be no guestbook service left running
kubectl get svc guestbook-ui

(If you ended up copying and pasting the kubectl proxy code above, make sure to clean up that process with kill -9 $PROXY_PID).

Now, even though you've made modifications to the Guestbook app and removed it from your cluster, ksonnet still tracks all your manifests locally:

# View all expanded manifests (YAML)
ks show default

If you're still wondering how ksonnet differs from existing tools, the tutorial shows you how to use other ksonnet features to implement the rest of the Guestbook app (and yes, the buttons will work!).

Additional documentation

ksonnet is a feature-rich framework. To learn more about how to integrate it into your workflow, check out the resources below:

• Tutorial - What can I build with ksonnet and why? This finishes the Guestbook app from the example above.

• Interactive tour of ksonnet - How do ks commands work under the hood?

• CLI Reference - What ksonnet commands are available, and how do I use them?

• Concept Reference - What do all these special ksonnet terms mean (e.g. prototypes) ?

• Design Docs - What are the detailed design specs, and what's next on the feature roadmap?

Troubleshooting

If you encounter any problems that the documentation does not address, file an issue.

Contributing

Thanks for taking the time to join our community and start contributing!

Before you start

• Please familiarize yourself with the Code of Conduct before contributing.
• Read the contribution guidelines in CONTRIBUTING.md.
• There is a mailing list or the #ksonnet channel on Slack if you want to interact with other members of the community.

Pull requests

• We welcome pull requests. Feel free to dig through the issues and jump in.

Changelog

See the list of releases to find out about feature changes.