# Tutorial

The **ksonnet** [readme][readme] 
shows you how to create a default 
`deployment.json` file that lets you deploy an nginx container 
to an existing Kubernetes cluster. This tutorial shows you how to:

* Modify the deployment using **ksonnet** definitions
* Define other Kubernetes objects
* Work with mixins to develop complex configurations

## Prerequisites

This tutorial assumes that you have performed the following 
tasks. For details, see the [readme][readme].

* Installed **Jsonnet**
* Cloned the **ksonnet** repository locally
* Installed and configured the VisualStudio Code extension 
(optional)
* Created a test Kubernetes cluster

NOTE: All import paths are relative to the root of the 
*ksonnet** repository.

## Modify the default deployment

**ksonnet** lets you configure or modify any Kubernetes object. 

For example, to customize the default <> deployment, you can write:

```javascript
// TODO: provide ksonnet example
```

Save the file as `customDeploy.libsonnet` 
and run:

```bash
jsonnet customDeploy.libsonnet
kubectl apply -f deployment.json
```

(here we seem to be looking at YAML we get from running 
`kubectl get deployment <appName> -o yaml` but in other examples
we're looking at JSON generated from ksonnet. Figure out, fix.)
And the generated YAML looks like this. You can see the new <> 
and <> fields:

```yaml
# TODO: provide example
```

## Define other Kubernetes objects

**ksonnet** lets you define any Kubernetes object. For example, 
you can define a container:

```javascript
// TODO: update ksonnet example; container is probably a good one
// consider whether nginx is the right one for deployment 
// (issue also in previous example)
```

Save this snippet as `container.libsonnet`, and run:

```bash
jsonnet container.libsonnet
```

The JSON output looks like this:

TODO: fix up to be consistent with YAML vs JSON
across tutorial examples

```json
(EXAMPLE)
```

You can include a liveness probe with your container:

```javascript
// TODO: ksonnet example. Is liveness probe appropriate here?
```

Save the file again -- `container.libsonnet` -- 
and run:

```bash
jsonnet container.libsonnet
```

(As above, YAML or JSON?)
The JSON output now looks like this:

```json
(EXAMPLE)
```

Now you can define a pod that runs this container:

```javascript
// TODO: ksonnet example
```

Save the file as `pod.libsonnet`, and run the following commands 
to deploy the pod to your cluster:

```bash
jsonnet pod.libsonnet // create pod.json
kubectl apply -f pod.json // apply pod definition to cluster
```

## Work with mixins

You've seen how to modify the default deployment by writing 
**mixins** to add custom fields. 
As the Jsonnet tutorial explains in more detail, mixins provide 
dynamic inheritance, at runtime instead of compile time. This 
approach means that different team members can define the 
Kubernetes objects that they need. You can then mix them into 
your master definition without having to copy all the details.

For example, you could write the following code to define a 
container for your application:

```javascript
// TODO: ksonnet example
```

And your teammate could write the following code to define 
the VolumeMounts:

```javascript
//TODO: ksonnet example
```

Then, you write a deployment definition for the container that 
adds the VolumeMounts for logging using mixins:

```javascript
//TODO: ksonnet example with mixins
```

[readme]: ../readme.md "ksonnet readme"