Learn how to create a filesystem registry
A registry is a repository of packages. ksonnet supports adding a registry from Github, Helm, and a local filesystem. Registries can then be shared, used offline, or kept under version control.
The goal is to create a minimalist registry with the structure below. For a registry containing more than one package, reference the registry example in concepts.
tutorial_registry ├── example │ ├── example.libsonnet │ ├── parts.yaml │ └── prototypes │ └── example.jsonnet └── registry.yaml
Before we begin, ensure that:
Create a new directory,
tutorial_registry, with a file inside called
registry.yaml. This file contains a list of all the packages in the registry and information about the registry API.
apiVersion is 0.1.0 and
kind identifies the file for ksonnet.
libraries contain a list of all the packges in the registry.
Each package has a
path relative to
registry.yaml. Optionally a
version can be provided to specify a branch if the registry will live in Github.
versioncannot be used to specify a local git branch.
Create a directory with the name of the package.
parts.yaml provides additional metadata on the package.
Identify the YAML for its purpose with
description are used to populate the output of
ks pkg describe.
Create another file called
example.libsonnet. This file describes the parts used to capture common elements of the prototypes.
Note: A Jsonnet file with the purpose of being used as a library should have a
.libsonnetextension by convention.
The example below contains a function that returns a value of 443 that can be used by prototypes.
Make a directory called
prototypes and a new
A prototype is annotated with additional metadata using a series of comments at the beginning of the file. The required metadata, also called a directive, are
Add the required
@param name string <Description of the param> to pass
@name where it can be imported to Jsonnet.
Optional params can be added with the following syntax:
@optionalParam <name> <type> <value> <Description of optional param>
A prototype param can have the following possible types:
Import the Jsonnet library under a local variable then call the function in the metadata.
Note: In addition to the import syntax above, param and optional param can be accessed by the keyword
params. For example, the optional namespace param can be written as
Navigate to your ksonnet application. First, add a new registry with the name
$ ks registry add tutorial /path/to/tutorial_registry
Metadata of the added registry is saved to
The example package will be visible with
ks pkg list. Install the package by specifying a
$ ks pkg install tutorial/example
Verify package installation with
ks pkg list --installed. Observe that the package files from the registry are copied to
app.yaml is updated with the installed package.
After installing the package, list all available prototypes. The
@shortDescription metadata from the commented section of the prototype are used here.
$ ks prototype list NAME DESCRIPTION ==== =========== example-prototype An example prototype
ks generate example-prototype example-component to create a new component.
components/params.libsonnet will update with the object defined from the prototype. A newly generated
component/example-component.jsonnet will be used to generate the manifest.
Finally, see the YAML output. Observe how the name under metadata is passed from
ks generate in addition to the return value of function from parts.
$ ks show default --- apiVersion: v1 kind: Service metadata: name: example-component annotations: default selector: app: example spec: ports: - port: 80 targetPort: 443
Push the registry to Github to share packages among teams.
Note: Private repositories requiring authentication are not supported at this time.
Then from a ksonnet app, add a registry from Github with the repository URI.
ks registry add <registry-name> <registry-uri>
By default, the incubator is added when creating a ksonnet application. This can be turned off by passing the
ks init <app-name> --skip-default-registry flag.
In order to generate manifests that are usable on a cluster, use ksonnet libraries to write libraries and prototypes using Jsonnet and the Kubernetes API.