@@ -24,7 +24,7 @@ The following diagram shows how the ksonnet framework works holistically:
### Application
A ksonnet application represents a well-structured directory of Kubernetes [manifests](#manifests). This directory is autogenerated by [`ksonnet init`](docs/cli-reference/ksonnet_init.md). These manifests typically tie together in some way—for example, they might collectively define a web service like the following:
A ksonnet application represents a well-structured directory of Kubernetes [manifests](#manifests). This directory is autogenerated by [`ksonnet init`](/docs/cli-reference/ksonnet_init.md). These manifests typically tie together in some way—for example, they might collectively define a web service like the following:
@@ -64,7 +64,7 @@ A ksonnet *application* can be broken down into a series of discrete components:
Components can be as simple as a single Kubernetes resource (e.g. a Deployment) or as complex as a complete logging stack (e.g. EFK). More concretely, a component corresponds to a Kubernetes manifest in `components/`. There are two ways to add this manifest:
* Typically, **you autogenerate it** with the [`ks generate`](docs/cli-reference/ks_generate.md) command. In this case, the manifest is expressed in a language called [Jsonnet](#jsonnet).
* Typically, **you autogenerate it** with the [`ks generate`](/docs/cli-reference/ks_generate.md) command. In this case, the manifest is expressed in a language called [Jsonnet](#jsonnet).
* Alternatively, you can **manually drop in** a file. In this case, your manifest can be any one of YAML, JSON, or Jsonnet. Because all three languages are supported, *this approach allows you to introduce ksonnet to existing codebases without significant rewrites*.
...
...
@@ -74,7 +74,7 @@ How does the autogeneration process work? When you use `ks generate`, the compon
<imgalt="component class analogy"src="/docs/img/component_and_prototype.svg"height="180px">
</p>
All of the component files in an *app* can be deployed to a specified *environment* using [`ks apply`](docs/cli-reference/ks_apply.md).
All of the component files in an *app* can be deployed to a specified *environment* using [`ks apply`](/docs/cli-reference/ks_apply.md).
---
...
...
@@ -92,13 +92,13 @@ Why is this useful? Prototypes allow you to avoid copying and pasting boilerplat
Out of the box, ksonnet comes with some system prototypes (like `io.ksonnet.pkg.deployed-service`) that you can explore with the various [`ks prototype`](docs/cli-reference/ks_prototype.md) commands. See [*package*](#package) for information on downloading or sharing additional prototypes.
Out of the box, ksonnet comes with some system prototypes (like `io.ksonnet.pkg.deployed-service`) that you can explore with the various [`ks prototype`](/docs/cli-reference/ks_prototype.md) commands. See [*package*](#package) for information on downloading or sharing additional prototypes.
---
### Parameter
Parameters allow you to customize your prototypes—both at the time of their creation, and after the fact. You can use the various [`ks param`](docs/cli-reference/ks_param.md) commands to view or modify current parameters. Params can be set globally or per-environment.
Parameters allow you to customize your prototypes—both at the time of their creation, and after the fact. You can use the various [`ks param`](/docs/cli-reference/ks_param.md) commands to view or modify current parameters. Params can be set globally or per-environment.
Under the hood, the `ks param` commands update a couple of local [*Jsonnet*](#jsonnet) files, so that you always have a version-controllable representation of what you `ks apply` onto your Kubernetes cluster. These are structured as follows:
***App params** (`components/params.libsonnet`) — treated like defaults
...
...
@@ -159,7 +159,7 @@ A package contains:
***A set of related *prototypes*** (e.g. `redis-persistent`, `redis-stateless`)
***Associated helper libraries** that define the prototype *parts* (e.g. `redis.libsonnet`)
Packages allow you to easily distribute and reuse code in any ksonnet *application*, using the various [`ks pkg`](docs/cli-reference/ks_pkg.md) commands. The CLI writes package code into the `vendor/` directory.
Packages allow you to easily distribute and reuse code in any ksonnet *application*, using the various [`ks pkg`](/docs/cli-reference/ks_pkg.md) commands. The CLI writes package code into the `vendor/` directory.
To be recognized and imported by ksonnet, packages need to follow a specific schema. See the annotated file tree below, as an example:
```
...
...
@@ -173,7 +173,7 @@ To be recognized and imported by ksonnet, packages need to follow a specific sch
└── redis.libsonnet // Helper library, includes prototype parts
```
`parts.yaml` metadata is used to populate the output of the [`ks prototype describe`](docs/cli-reference/ks_prototype_describe.md) command. The official packages in [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) also use `parts.yaml` to autogenerate `README.md` documentation.
`parts.yaml` metadata is used to populate the output of the [`ks prototype describe`](/docs/cli-reference/ks_prototype_describe.md) command. The official packages in [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) also use `parts.yaml` to autogenerate `README.md` documentation.
You can take a look at the [nginx](https://github.com/ksonnet/parts/tree/master/incubator/nginx) and [Redis](https://github.com/ksonnet/parts/tree/master/incubator/redis) packages as additional examples.
...
...
@@ -185,7 +185,7 @@ Registries are essentially repositories for *packages*. (We mean registry here i
The ability to add new registries is under development. In the meantime, ksonnet allows you do download *packages* from the [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) registry.
Use the various [`ks registry`](docs/cli-reference/ks_registry.md) commands to see what packages are available.
Use the various [`ks registry`](/docs/cli-reference/ks_registry.md) commands to see what packages are available.
Jessica Yao <jessica@heptio.com>