Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ksonnet/ksonnet

A CLI-supported framework that streamlines writing and deployment of Kubernetes configurations to multiple clusters.
https://github.com/ksonnet/ksonnet

Last synced: 3 months ago
JSON representation

A CLI-supported framework that streamlines writing and deployment of Kubernetes configurations to multiple clusters.

Awesome Lists containing this project

README 

        
# ksonnet



**The team behind ksonnet is stepping back from the project. As a result, work on ksonnet will end and the GitHub repositories will be archived. You can read more about our decision [here.](https://blogs.vmware.com/cloudnative/2019/02/05/welcoming-heptio-open-source-projects-to-vmware/)**



[**Official Site**](https://ksonnet.io/)



[![Build Status](https://travis-ci.org/ksonnet/ksonnet.svg?branch=master)](https://travis-ci.org/ksonnet/ksonnet)

[![Go Report Card](https://goreportcard.com/badge/github.com/ksonnet/ksonnet)](https://goreportcard.com/report/github.com/ksonnet/ksonnet)



*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](https://brew.sh/) 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](https://github.com/ksonnet/ksonnet/releases) to download the latest released binary.



### Build a docker image



A docker image can be built and used similarly to our manual build [as seen here](/docs/docker-image-build.md) 



### Manually build and install



You can download and manually build from source by following [these instructions](/docs/build-install.md).



## 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:





guestbook screenshot




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](#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](https://kubernetes.io/docs/setup/) from the official Kubernetes docs.



* *You should have `kubectl` installed.* If not, follow the instructions for [installing via Homebrew (MacOS)](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos) or [building the binary (Linux)](https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1).



* *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**:

```bash

# 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:



```bash

# '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:



```bash

# 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:



```bash

# 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:



```bash

# View all expanded manifests (YAML)

ks show default

```



If you're still wondering how ksonnet differs from existing tools, the [tutorial](https://ksonnet.io/docs/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](https://ksonnet.io/docs/tutorial)** - What can I build with ksonnet and why? This finishes the Guestbook app from the [example](#run-through-an-example) above.



* **[Interactive tour of ksonnet](https://ksonnet.io/tour/welcome)** - How do `ks` commands work under the hood?



* **[CLI Reference](/docs/cli-reference#command-line-reference)** - What ksonnet commands are available, and how do I use them?



* **[Concept Reference](/docs/concepts.md)** - What do all these special ksonnet terms mean (e.g. *prototypes*) ?



* **[Design Docs](/design)** - 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](https://github.com/ksonnet/ksonnet/issues).



## Contributing



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



#### Before you start



* Please familiarize yourself with the [Code of

Conduct](CODE-OF-CONDUCT.md) before contributing.

* Read the contribution guidelines in [CONTRIBUTING.md](CONTRIBUTING.md).

* There is a [mailing list](https://groups.google.com/forum/#!forum/ksonnet) or the #ksonnet channel on [Slack](http://kubernetes.slack.com/messages/ksonnet) if you want to interact with

other members of the community.



#### Pull requests



* We welcome pull requests. Feel free to dig through the [issues](https://github.com/ksonnet/ksonnet/issues) and jump in.



## Changelog



See [the list of releases](https://github.com/ksonnet/ksonnet/releases) to find out about feature changes.