Ksonnet provides a CLI (invoked with ks) that allows you to generate Kubernetes resource manifests locally (in jsonnet) and synchronize them with your remote cluster(s).
The files in this directory enumerate each of the possible ks commands and their flags. Note that you can also find this info with the CLI itself, using the --help flag.
Suggested command usage is described below:
Set up a ksonnet application
Generate components for your app (e.g. Redis)
ks generate (alias of ks prototype use)Deploy to a cluster
Delete resources running on a cluster
Learn about existing prototypes (ks prototype)
Learn about and download currently available packages (ks pkg)
Learn about existing registries (ks registry)
List and remove existing components
Managing environments (ks env)
Customizing environments with parameters (ks param)
Comparing environments
View expanded manifests
Import a manifest
Validate manifests against the Kubernetes API
View metadata about the ksonnet binary
Apply local Kubernetes manifests (components) to remote clusters
The applycommand uses local manifest(s) to update (and optionally create)
Kubernetes resources on a remote cluster. This cluster is determined by the
mandatory <env-name> argument.
The manifests themselves correspond to the components of your app, and reside
in your app’s components/ directory. When applied, the manifests are fully
expanded using the parameters of the specified environment.
By default, all component manifests are applied. To apply a subset of components,
use the --component flag, as seen in the examples below.
Note that this command needs to be run within a ksonnet app directory.
ks diff — Compare manifests, based on environment or location (local or remote)ks delete — Remove component-specified Kubernetes resources from remote clustersks apply <env-name> [-c <component-name>] [--dry-run] [flags]
# Create or update all resources described in the ksonnet application, specifically
# the ones running in the 'dev' environment. This command works in any subdirectory
# of the app.
#
# This essentially deploys all components in the 'components/' directory.
ks apply dev
# Similar to the previous command, but does not immediately execute. Use this to
# see a preview of the cluster-changing actions.
ks apply dev --dry-run
# Create or update the single 'guestbook-ui' component of a ksonnet app, specifically
# the instance running in the 'dev' environment.
#
# This essentially deploys 'components/guestbook-ui.jsonnet'.
ks apply dev -c guestbook-ui
# Create or update multiple components in a ksonnet application (e.g. 'guestbook-ui'
# and 'nginx-depl') for the 'dev' environment. Does not create resources that are
# not already present on the cluster.
#
# This essentially deploys 'components/guestbook-ui.jsonnet' and
# 'components/nginx-depl.jsonnet'.
ks apply dev -c guestbook-ui -c nginx-depl --create false
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
-c, --component stringSlice Name of a specific component (multiple -c flags accepted, allows YAML, JSON, and Jsonnet)
--context string The name of the kubeconfig context to use
--create Option to create resources if they do not already exist on the cluster (default true)
--dry-run Option to preview the list of operations without changing the cluster state
-V, --ext-str stringSlice Values of external variables
--ext-str-file stringSlice Read external variable from a file
--gc-tag string A tag that's (1) added to all updated objects (2) used to garbage collect existing objects that are no longer in the manifest
-h, --help help for apply
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-J, --jpath stringSlice Additional jsonnet library search path
--kubeconfig string Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
-n, --namespace string If present, the namespace scope for this CLI request
--password string Password for basic authentication to the API server
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--server string The address and port of the Kubernetes API server
--skip-gc Option to skip garbage collection, even with --gc-tag specified
-A, --tla-str stringSlice Values of top level arguments
--tla-str-file stringSlice Read top level argument from a file
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use
--username string Username for basic authentication to the API server
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List known components
The list command displays all known components.
ks component list [flags]
# List all components
ks component list
-h, --help help for list
--module string Component module
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Delete a component from the ksonnet application
Delete a component from the ksonnet application. This is equivalent to deleting the component file in the components directory and cleaning up all component references throughout the project.
ks component rm <component-name> [flags]
# List all components
ks component list
-h, --help help for rm
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Remove component-specified Kubernetes resources from remote clusters
The delete command removes Kubernetes resources (described in local
component manifests) from a cluster. This cluster is determined by the mandatory
<env-name>argument.
An entire ksonnet application can be removed from a cluster, or just its specific components.
This command can be considered the inverse of the ks apply command.
ks diff — Compare manifests, based on environment or location (local or remote)ks apply — Apply local Kubernetes manifests (components) to remote clustersks delete [env-name] [-c <component-name>] [flags]
# Delete resources from the 'dev' environment, based on ALL of the manifests in your
# ksonnet app's 'components/' directory. This command works in any subdirectory
# of the app.
ks delete dev
# Delete resources described by the 'nginx' component. $KUBECONFIG is overridden by
# the CLI-specified './kubeconfig', so these changes are deployed to the current
# context's cluster (not the 'default' environment)
ks delete --kubeconfig=./kubeconfig -c nginx
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
-c, --component stringSlice Name of a specific component (multiple -c flags accepted, allows YAML, JSON, and Jsonnet)
--context string The name of the kubeconfig context to use
-V, --ext-str stringSlice Values of external variables
--ext-str-file stringSlice Read external variable from a file
--grace-period int Number of seconds given to resources to terminate gracefully. A negative value is ignored (default -1)
-h, --help help for delete
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-J, --jpath stringSlice Additional jsonnet library search path
--kubeconfig string Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
-n, --namespace string If present, the namespace scope for this CLI request
--password string Password for basic authentication to the API server
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--server string The address and port of the Kubernetes API server
-A, --tla-str stringSlice Values of top level arguments
--tla-str-file stringSlice Read top level argument from a file
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use
--username string Username for basic authentication to the API server
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Compare manifests, based on environment or location (local or remote)
The diff command displays standard file diffs, and can be used to compare manifests
based on environment or location (‘local’ ksonnet app manifests or what’s running
on a ‘remote’ server).
Using this command, you can compare:
To see the official syntax, see the examples below. Make sure that your $KUBECONFIG matches what you’ve defined in environments.
When NO component is specified (no -c flag), this command diffs all of
the files in the components/ directory.
When a component IS specified via the -c flag, this command only checks
the manifest for that particular component.
ks param diff — Display differences between the component parameters of two environmentsks diff <location1:env1> [location2:env2] [flags]
# Show diff between remote and local manifests for a single 'dev' environment.
# This command diffs *all* components in the ksonnet app, and can be used in any
# of that app's subdirectories.
ks diff remote:dev local:dev
# Shorthand for the previous command (remote 'dev' and local 'dev')
ks diff dev
# Show diff between the remote resources running in two different ksonnet environments
# 'us-west/dev' and 'us-west/prod'. This command diffs all resources defined in
# the ksonnet app.
ks diff remote:us-west/dev remote:us-west/prod
# Show diff between local manifests in the 'us-west/dev' environment and remote
# resources in the 'us-west/prod' environment, for an entire ksonnet app
ks diff local:us-west/dev remote:us-west/prod
# Show diff between what's in the local manifest and what's actually running in the
# 'dev' environment, but for the Redis component ONLY
ks diff dev -c redis
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
-c, --component stringSlice Name of a specific component
--context string The name of the kubeconfig context to use
-V, --ext-str stringSlice Values of external variables
--ext-str-file stringSlice Read external variable from a file
-h, --help help for diff
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-J, --jpath stringSlice Additional jsonnet library search path
--kubeconfig string Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
-n, --namespace string If present, the namespace scope for this CLI request
--password string Password for basic authentication to the API server
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--server string The address and port of the Kubernetes API server
-A, --tla-str stringSlice Values of top level arguments
--tla-str-file stringSlice Read top level argument from a file
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use
--username string Username for basic authentication to the API server
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Add a new environment to a ksonnet application
The add command creates a new environment (specifically for the ksonnet app
whose directory it’s executed in). This environment is cached with the following
info:
(1) is mandatory. (2) and (3) can be inferred from $KUBECONFIG, or from the
--kubeconfig or --context flags. Otherwise, (2), (3), and (4) can all be
specified by individual flags. Unless otherwise specified, (4) defaults to the
latest Kubernetes version that ksonnet supports.
Note that an environment DOES NOT contain user-specific data such as private keys.
ks env list — List all environments in a ksonnet applicationks env rm — Delete an environment from a ksonnet applicationks env set — Set environment-specific fields (name, namespace, server)ks param set — Set environment-specific fields (name, namespace, server)ks apply — Apply local Kubernetes manifests (components) to remote clustersks env add <env-name> [flags]
# Initialize a new environment, called "staging". No flags are set, so 'server'
# and 'namespace' info are pulled from the file specified by $KUBECONFIG.
# 'version' defaults to the latest that ksonnet supports.
ks env add us-west/staging
# Initialize a new environment called "us-west/staging" with the pre-existing
# namespace 'staging'. 'version' is specified, so the OpenAPI spec from the
# Kubernetes v1.7.1 build is used to generate the helper library 'ksonnet-lib'.
#
# NOTE: "us-west/staging" indicates a hierarchical structure, so the env-specific
# files here are saved in "<ksonnet-app-root>/environments/us-west/staging".
ks env add us-west/staging --api-spec=version:v1.7.1 --namespace=staging
# Initialize a new environment "my-env" using the "dev" context in your current
# kubeconfig file ($KUBECONFIG).
ks env add my-env --context=dev
# Initialize a new environment "prod" using the address of a cluster's Kubernetes
# API server.
ks env add prod --server=https://ksonnet-1.us-west.elb.amazonaws.com
--api-spec string Manually specify API version from OpenAPI schema, cluster, or Kubernetes version
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
--context string The name of the kubeconfig context to use
-h, --help help for add
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
--kubeconfig string Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
-n, --namespace string If present, the namespace scope for this CLI request
-o, --override Add environment as override
--password string Password for basic authentication to the API server
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--server string The address and port of the Kubernetes API server
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use
--username string Username for basic authentication to the API server
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Sets the current environment
The current command lets you set the current ksonnet environment.
ks env list — List all environments in a ksonnet applicationks env current [--set <name> | --unset] [flags]
#Update the current environment to 'us-west/staging'
ks env current --set us-west/staging
#Retrieve the current environment
ks env current
#Unset the current environment
ks env current --unset
-h, --help help for current
--set string Environment to set as current
--unset Unset current environment
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Describe an environment
describe
ks env describe <env> [flags]
-h, --help help for describe
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List all environments in a ksonnet application
The list command lists all of the available environments for the
current ksonnet app. Specifically, this will display the (1) name,
(2) server, and (3) namespace of each environment.
ks env add — Add a new environment to a ksonnet applicationks env set — Set environment-specific fields (name, namespace, server)ks env rm — Delete an environment from a ksonnet applicationks env list [flags]
-h, --help help for list
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Delete an environment from a ksonnet application
The rm command deletes an environment from a ksonnet application. This is
the same as removing the <env-name> environment directory and all files
contained. All empty parent directories are also subsequently deleted.
NOTE: This does NOT delete the components running in <env-name>. To do that, you
need to use the ks delete command.
ks env list — List all environments in a ksonnet applicationks env add — Add a new environment to a ksonnet applicationks env set — Set environment-specific fields (name, namespace, server)ks delete — Delete all the app components running in an environment (cluster)ks env rm <env-name> [flags]
# Remove the directory 'environments/us-west/staging' and all of its contents.
# This will also remove the parent directory 'us-west' if it is empty.
ks env rm us-west/staging
-h, --help help for rm
-o, --override Remove the overridden environment
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Set environment-specific fields (name, namespace, server)
The set command lets you change the fields of an existing environment.
You can currently only update your environment’s name.
Note that changing the name of an environment will also update the corresponding
directory structure in environments/.
ks env list — List all environments in a ksonnet applicationks env set <env-name> [flags]
# Update the name of the environment 'us-west/staging'.
# Updating the name will update the directory structure in 'environments/'.
ks env set us-west/staging --name=us-east/staging
# Setting k8s API version for an environment
ks env set us-west/staging --api-spec=version:v1.8.0
# Updating the server
ks env set us-west/staging --server=https://192.168.99.100:8443
--api-spec string Kubernetes version for environment
-h, --help help for set
--name string Name used to uniquely identify the environment. Must not already exist within the ksonnet app
--namespace string Namespace for environment
--server string Cluster server for environment
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Set module targets for an environment
targets
ks env targets [flags]
-h, --help help for targets
--module stringSlice Component modules to include
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Updates the libs for an environment
The update command updates libraries for an environment.
ks env list — List all environments in a ksonnet applicationks env add — Add a new environment to a ksonnet applicationks env set — Set environment-specific fields (name, namespace, server)ks delete — Delete all the app components running in an environment (cluster)ks env update <env-name> [flags]
# Update the environment 'us-west/staging' libs.
ks env update us-west/staging
-h, --help help for update
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Use the specified prototype to generate a component manifest
The generate command (aliased from prototype use) generates Kubernetes-
compatible, Jsonnet manifests for components in your ksonnet app. Each component
corresponds to a single manifest in the components/ directory. This manifest
can define one or more Kubernetes resources, and is generated from a ksonnet
prototype (a customizable, reusable Kubernetes configuration snippet).
The first argument, the prototype name, can either be fully qualified
(e.g. io.ksonnet.pkg.single-port-service) or a partial match (e.g. service).
If using a partial match, note that any ambiguity in resolving the name will
result in an error.
The second argument, the component name, determines the filename for the
generated component manifest. For example, the following command will expand
template io.ksonnet.pkg.single-port-deployment and place it in the
file components/nginx-depl.jsonnet . Note that by default ksonnet will
expand prototypes into Jsonnet files.
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl
–image=nginx
If the optional --name tag is not specified, all Kubernetes API resources
declared by this prototype use this argument as their own metadata.name
--image in the example above. Note that
different prototypes support their own unique flags.ks show — Show expanded manifests for a specific environment.ks apply — Apply local Kubernetes manifests (components) to remote clustersks param set Change component or environment parameters (e.g. replica count, name)ks generate <prototype-name> <component-name> [type] [parameter-flags] [flags]
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'.
# The associated Deployment has metadata.name 'nginx-depl'.
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# suffix, 'deployment'. (This works unless there is an ambiguity, e.g. another
# prototype with 'deployment' in its name.) The expanded prototype is again
# placed in 'components/nginx-depl.jsonnet'.
# The associated Deployment has metadata.name 'nginx' instead of 'nginx-depl'
# (due to --name).
ks prototype use deployment nginx-depl \
--name=nginx \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# 'nginx' image with values from 'ks-value'.
ks prototype use single-port-deployment nginx-depl \
--values-file=ks-value
-h, --help help for generate
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Import manifest
Import manifest
ks import [flags]
-f, --filename string Filename, directory, or URL for component to import
-h, --help help for import
--module string Component module
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Initialize a ksonnet application
The init command initializes a ksonnet application in a new directory, app-name.
This command generates all the project scaffolding required to begin creating and deploying components to Kubernetes clusters.
ksonnet applications are initialized based on your current cluster configurations,
as defined in your $KUBECONFIG environment variable. The Examples section
below demonstrates how to customize these configurations.
Creating a ksonnet application results in the following directory tree.
app-name/
.ksonnet/ Metadata for ksonnet
app.yaml Application specifications (e.g. name, API version)
components/ Top-level Kubernetes objects defining the application
environments/ Kubernetes cluster definitions
default/ Default environment, initialized from the current kubeconfig
.metadata/ Contains a versioned ksonnet-lib, see [1] for details
lib/ User-written .libsonnet files
vendor/ Libraries that define prototypes and their constituent parts
To begin populating your ksonnet application, see the docs for ks generate .
[1] ksonnet-lib is a Jsonnet helper library that wraps Kubernetes-API-compatible
types. A specific version of ksonnet-lib is automatically provided for each
environment. Users can set flags to generate the library based on a variety of data,
including server configuration and an OpenAPI specification of a specific Kubernetes
build. By default, this is generated using cluster information specified by the
current context, in the file pointed to by $KUBECONFIG.
ks generate — Use the specified prototype to generate a component manifestks init <app-name> [flags]
# Initialize a ksonnet application, based on cluster information from the
# active kubeconfig file (as specified by the environment variable $KUBECONFIG).
# More specifically, the current context is used.
ks init app-name
# Initialize a ksonnet application, using the context 'dev' from the current
# kubeconfig file ($KUBECONFIG). The default environment is created using the
# server address and default namespace located at the context 'dev'.
ks init app-name --context=dev
# Initialize a ksonnet application, using the context 'dev' and the namespace
# 'dc-west' from the current kubeconfig file ($KUBECONFIG). The default environment
# is created using the server address from the 'dev' context, and the specified
# 'dc-west' namespace.
ks init app-name --context=dev --namespace=dc-west
# Initialize a ksonnet application, using v1.7.1 of the Kubernetes OpenAPI spec
# to generate 'ksonnet-lib'.
ks init app-name --api-spec=version:v1.7.1
# Initialize a ksonnet application, using the OpenAPI spec generated by a
# specific build of Kubernetes to generate 'ksonnet-lib'.
ks init app-name --api-spec=file:swagger.json
# Initialize a ksonnet application, outputting the application directory into
# the specified 'custom-location'.
ks init app-name --dir=custom-location
--api-spec string Manually specified Kubernetes API version. The corresponding OpenAPI spec is used to generate ksonnet's Kubernetes libraries
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
--context string The name of the kubeconfig context to use
--dir string Ksonnet application directory
--env string Name of initial environment to create
-h, --help help for init
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
--kubeconfig string Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
-n, --namespace string If present, the namespace scope for this CLI request
--password string Password for basic authentication to the API server
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--server string The address and port of the Kubernetes API server
--skip-default-registries Skip configuration of default registries
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use
--username string Username for basic authentication to the API server
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Create a module
Create a module
ks module create <name> [flags]
-h, --help help for create
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List modules
List modules
ks module list [flags]
--env string Environment to list modules for
-h, --help help for list
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Delete component or environment parameters
The delete command deletes component or environment parameters.
ks param set — Change component or environment parameters (e.g. replica count, name)ks param diff — Display differences between the component parameters of two environmentsks apply — Apply local Kubernetes manifests (components) to remote clustersks param delete [component-name] <param-key> [flags]
# Delete 'guestbook' component replica parameter
ks param delete guestbook replicas
# Delete 'guestbook' component replicate in 'dev' environment
ks param delete guestbook replicas --env=dev
--env string Specify environment to delete parameter from
-h, --help help for delete
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Display differences between the component parameters of two environments
The diff command pretty prints differences between the component parameters
of two environments.
By default, the diff is performed for all components. Diff-ing for a single component is supported via a component flag.
ks param set — Change component or environment parameters (e.g. replica count, name)ks apply — Apply local Kubernetes manifests (components) to remote clustersks param diff <env1> <env2> [--component <component-name>] [flags]
# Diff between all component parameters for environments 'dev' and 'prod'
ks param diff dev prod
# Diff only between the parameters for the 'guestbook' component for environments
# 'dev' and 'prod'
ks param diff dev prod --component=guestbook
--component string Specify the component to diff against
-h, --help help for diff
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List known component parameters
The list command displays all known component parameters or environment parameters.
If a component is specified, this command displays all of its specific parameters. If a component is NOT specified, parameters for all components are listed. Furthermore, parameters can be listed on a per-environment basis.
ks param set — Change component or environment parameters (e.g. replica count, name)ks param list [<component-name>] [--env <env-name>] [flags]
# List all component parameters
ks param list
# List all parameters for the component "guestbook"
ks param list guestbook
# List all parameters for the environment "dev"
ks param list --env=dev
# List all parameters for the component "guestbook" in the environment "dev"
ks param list guestbook --env=dev
--env string Specify environment to list parameters for
-h, --help help for list
--module string Specify module to list parameters for
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Change component or environment parameters (e.g. replica count, name)
The set command sets component or environment parameters such as replica count
or name. Parameters are set individually, one at a time. All of these changes are
reflected in the params.libsonnet files.
For more details on how parameters are organized, see ks param --help.
(If you need to customize multiple parameters at once, we suggest that you modify
your ksonnet application’s components/params.libsonnet file directly. Likewise,
for greater customization of environment parameters, we suggest modifying the
environments/:name/params.libsonnet file.)
ks param diff — Display differences between the component parameters of two environmentsks apply — Apply local Kubernetes manifests (components) to remote clustersks param set <component-name> <param-key> <param-value> [flags]
# Update the replica count of the 'guestbook' component to 4.
ks param set guestbook replicas 4
# Update the replica count of the 'guestbook' component to 2, but only for the
# 'dev' environment
ks param set guestbook replicas 2 --env=dev
--as-string Force value to be interpreted as string
--env string Specify environment to set parameters for
-h, --help help for set
--resolve-image Resolve Docker image tag to reference
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Describe a ksonnet package and its contents
The describe command outputs documentation for a package that is available
(e.g. downloaded) in the current ksonnet application. (This must belong to an already
known <registry-name> like incubator). The output includes:
ks pkg list — List all packages known (downloaded or not) for the current ksonnet appks prototype describe — See more info about a prototype’s output and usageks generate — Use the specified prototype to generate a component manifestks pkg describe [<registry-name>/]<package-name> [flags]
-h, --help help for describe
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Install a package (e.g. extra prototypes) for the current ksonnet app
The install command caches a ksonnet library locally, and makes it available
for use in the current ksonnet application. Enough info and metadata is recorded in
app.yaml that new users can retrieve the dependency after a fresh clone of this app.
The library itself needs to be located in a registry (e.g. Github repo). By default, ksonnet knows about two registries: incubator and stable, which are the release channels for official ksonnet libraries.
ks pkg list — List all packages known (downloaded or not) for the current ksonnet appks prototype list — List all locally available ksonnet prototypesks registry describe — Describe a ksonnet registry and the packages it containsks pkg install <registry>/<library>@<version> [flags]
# Install an nginx dependency, based on the tip defined by the registry URI.
# In a ksonnet source file, this can be referenced as:
# local nginx = import "incubator/nginx/nginx.libsonnet";
ks pkg install incubator/nginx
# Install an nginx dependency, based on the 'master' branch.
# In a ksonnet source file, this can be referenced as:
# local nginx = import "incubator/nginx/nginx.libsonnet";
ks pkg install incubator/nginx@master
# Install a specific nginx version into the stage environment.
# In a ksonnet source file, this can be referenced as:
# local nginx = import "incubator/nginx/nginx.libsonnet";
ks pkg install --env stage incubator/nginx@40285d8a14f1ac5787e405e1023cf0c07f6aa28c
--env string Environment to install package into (optional)
--force Force installation
-h, --help help for install
--name string Name to give the dependency, to use within the ksonnet app
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List all packages known (downloaded or not) for the current ksonnet app
The list command outputs a table that describes all known packages (not
necessarily downloaded, but available from existing registries). This includes
the following info:
ks pkg install — Install a package (e.g. extra prototypes) for the current ksonnet appks pkg describe — Describe a ksonnet package and its contentsks registry describe — Describe a ksonnet registry and the packages it containsks pkg list [flags]
-h, --help help for list
--installed Only list installed packages
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
See more info about a prototype’s output and usage
This command outputs documentation, examples, and other information for the specified prototype (identified by name). Specifically, this describes:
ks prototype preview — Preview a prototype’s output without creating a component (stdout)ks prototype use — Use the specified prototype to generate a component manifestks prototype describe <prototype-name> [flags]
# Display documentation about the prototype 'io.ksonnet.pkg.single-port-deployment'
ks prototype describe deployment
-h, --help help for describe
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List all locally available ksonnet prototypes
The list command displays all prototypes that are available locally, as
well as brief descriptions of what they generate.
ksonnet comes with a set of system prototypes that you can use out-of-the-box
(e.g. io.ksonnet.pkg.configMap). However, you can use more advanced
prototypes like io.ksonnet.pkg.redis-stateless by downloading extra packages
from the incubator registry.
ks prototype describe — See more info about a prototype’s output and usageks prototype preview — Preview a prototype’s output without creating a component (stdout)ks prototype use — Use the specified prototype to generate a component manifestks pkg install Install a package (e.g. extra prototypes) for the current ksonnet appks prototype list [flags]
-h, --help help for list
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Preview a prototype’s output without creating a component (stdout)
This preview command expands a prototype with CLI flag parameters, and
emits the resulting manifest to stdout. This allows you to see the potential
output of a ks generate command without actually creating a new component file.
The output is formatted in Jsonnet. To see YAML or JSON equivalents, first create
a component with ks generate and then use ks show.
ks generate — Use the specified prototype to generate a component manifestks prototype preview <prototype-name> [parameter-flags] [flags]
# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image, and port 80 exposed.
ks prototype preview single-port-deployment \
--name=nginx \
--image=nginx \
--port=80
# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image, and port 80 exposed with a values file.
ks prototype preview simple-port-deployment \
--name=nginx \
--values-file=ks-values
Where 'ks-values' is a jsonnet file with the contents:
{
image: "nginx",
port: 80,
}
-h, --help help for preview
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Search for a prototype
The prototype search command allows you to search for specific prototypes by name.
Specifically, it matches any prototypes with names that contain the string
ks prototype describe — See more info about a prototype’s output and usageks prototype list — List all locally available ksonnet prototypesks prototype search <name-substring> [flags]
# Search for prototypes with names that contain the string 'service'.
ks prototype search service
-h, --help help for search
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Use the specified prototype to generate a component manifest
The generate command (aliased from prototype use) generates Kubernetes-
compatible, Jsonnet manifests for components in your ksonnet app. Each component
corresponds to a single manifest in the components/ directory. This manifest
can define one or more Kubernetes resources, and is generated from a ksonnet
prototype (a customizable, reusable Kubernetes configuration snippet).
The first argument, the prototype name, can either be fully qualified
(e.g. io.ksonnet.pkg.single-port-service) or a partial match (e.g. service).
If using a partial match, note that any ambiguity in resolving the name will
result in an error.
The second argument, the component name, determines the filename for the
generated component manifest. For example, the following command will expand
template io.ksonnet.pkg.single-port-deployment and place it in the
file components/nginx-depl.jsonnet . Note that by default ksonnet will
expand prototypes into Jsonnet files.
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl
–image=nginx
If the optional --name tag is not specified, all Kubernetes API resources
declared by this prototype use this argument as their own metadata.name
--image in the example above. Note that
different prototypes support their own unique flags.ks show — Show expanded manifests for a specific environment.ks apply — Apply local Kubernetes manifests (components) to remote clustersks param set Change component or environment parameters (e.g. replica count, name)ks prototype use <prototype-name> <componentName> [type] [parameter-flags] [flags]
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'.
# The associated Deployment has metadata.name 'nginx-depl'.
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# suffix, 'deployment'. (This works unless there is an ambiguity, e.g. another
# prototype with 'deployment' in its name.) The expanded prototype is again
# placed in 'components/nginx-depl.jsonnet'.
# The associated Deployment has metadata.name 'nginx' instead of 'nginx-depl'
# (due to --name).
ks prototype use deployment nginx-depl \
--name=nginx \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# 'nginx' image with values from 'ks-value'.
ks prototype use single-port-deployment nginx-depl \
--values-file=ks-value
-h, --help help for use
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Add a registry to the current ksonnet app
The add command allows custom registries to be added to your ksonnet app,
provided that their file structures follow the appropriate schema. You can look
at the incubator repo (https://github.com/ksonnet/parts/tree/master/incubator)
as an example.
A registry is given a string identifier, which must be unique within a ksonnet application.
There are three supported registry protocols: github, fs, and Helm.
GitHub registries expect a path in a GitHub repository, and filesystem based registries expect a path on the local filesystem.
During creation, all registries must specify a unique name and URI where the registry lives. GitHub registries can specify a commit, tag, or branch to follow as part of the URI.
Registries can be overridden with --override. Overridden registries
are stored in app.override.yaml and can be safely ignored using your
SCM configuration.
ks registry list — List all registries known to the current ksonnet appks registry add <registry-name> <registry-uri> [flags]
# Add a registry with the name 'databases' at the uri 'github.com/example'
ks registry add databases github.com/example
# Add a registry with the name 'databases' at the uri
# 'github.com/org/example/tree/0.0.1/registry' (0.0.1 is the branch name)
ks registry add databases github.com/org/example/tree/0.0.1/registry
# Add a registry with a Helm Charts Repository uri
ks registry add helm-stable https://kubernetes-charts.storage.googleapis.com
-h, --help help for add
-o, --override Store in override configuration
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Describe a ksonnet registry and the packages it contains
The describe command outputs documentation for the ksonnet registry identified
by <registry-name>. Specifically, it displays the following:
github)ks pkg install — Install a package (e.g. extra prototypes) for the current ksonnet appks registry describe <registry-name> [flags]
-h, --help help for describe
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
List all registries known to the current ksonnet app
The list command displays all known ksonnet registries in a table. This
table includes the following info:
github)ks registry describe — Describe a ksonnet registry and the packages it containsks registry list [flags]
-h, --help help for list
-o, --output string Output format. Valid options: table|json
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Set configuration options for registry
The set command sets configuration parameters on a configured registry.
The following parameters can be set:
ks registry set [registry-name] [flags]
# Set the incubator registry to the experimental branch:
ks registry set incubator --uri https://github.com/ksonnet/parts/tree/experimental/incubator
-h, --help help for set
--uri string URI to configure the registry
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Show expanded manifests for a specific environment.
Show expanded manifests (resource definitions) for a specific environment. Jsonnet manifests, each defining a ksonnet component, are expanded into their JSON or YAML equivalents (YAML is the default). Any parameters in these Jsonnet manifests are resolved based on environment-specific values.
When NO component is specified (no -c flag), this command expands all of
the files in the components/ directory into a list of resource definitions.
This is the YAML version of what gets deployed to your cluster with
ks apply <env-name>.
When a component IS specified via the -c flag, this command only expands the
manifest for that particular component.
ks validate — Check generated component manifests against the server’s APIks apply — Apply local Kubernetes manifests (components) to remote clustersks show <env> [-c <component-filename>] [flags]
# Show all of the components for the 'dev' environment, in YAML
# (In other words, expands all manifests in the components/ directory)
ks show dev
# Show a single component from the 'prod' environment, in JSON
ks show prod -c redis -o json
# Show multiple components from the 'dev' environment, in YAML
ks show dev -c redis -c nginx-server
-c, --component stringSlice Name of a specific component (multiple -c flags accepted, allows YAML, JSON, and Jsonnet)
-V, --ext-str stringSlice Values of external variables
--ext-str-file stringSlice Read external variable from a file
-o, --format string Output format. Supported values are: json, yaml (default "yaml")
-h, --help help for show
-J, --jpath stringSlice Additional jsonnet library search path
-A, --tla-str stringSlice Values of top level arguments
--tla-str-file stringSlice Read top level argument from a file
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Upgrade ks configuration
The upgrade command upgrades a ksonnet application to the latest version.
ks upgrade [--dry-run] [flags]
# Upgrade ksonnet application in dry-run mode to see the changes to be performed by the
# upgrade process.
ks upgrade --dry-run
# Upgrade ksonnet application. This will update app.yaml to apiVersion 0.1.0
# and migrate environment spec.json files to `app.yaml`.
ks upgrade
--dry-run Dry-run upgrade process. Prints out changes.
-h, --help help for upgrade
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Check generated component manifests against the server’s API
The validate command checks that an application or file is compliant with the
server APIs Kubernetes specification. Note that this command actually communicates
with the server for the specified <env-name>, so it only works if your
$KUBECONFIG specifies a valid kubeconfig file.
When NO component is specified (no -c flag), this command checks all of
the files in the components/ directory. This is the same as what would
get deployed to your cluster with ks apply <env-name>.
When a component IS specified via the -c flag, this command only checks
the manifest for that particular component.
ks show — Show expanded manifests for a specific environment.ks apply — Apply local Kubernetes manifests (components) to remote clustersks validate <env-name> [-c <component-name>] [flags]
# Validate all resources described in the ksonnet app, against the server
# specified by the 'dev' environment.
# NOTE: Make sure your current $KUBECONFIG matches the 'dev' cluster info
ksonnet validate dev
# Validate resources from the 'redis' component only, against the server specified
# by the 'prod' environment
# NOTE: Make sure your current $KUBECONFIG matches the 'prod' cluster info
ksonnet validate prod -c redis
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
-c, --component stringSlice Name of a specific component (multiple -c flags accepted, allows YAML, JSON, and Jsonnet)
--context string The name of the kubeconfig context to use
-V, --ext-str stringSlice Values of external variables
--ext-str-file stringSlice Read external variable from a file
-h, --help help for validate
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-J, --jpath stringSlice Additional jsonnet library search path
--kubeconfig string Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
-n, --namespace string If present, the namespace scope for this CLI request
--password string Password for basic authentication to the API server
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--server string The address and port of the Kubernetes API server
-A, --tla-str stringSlice Values of top level arguments
--tla-str-file stringSlice Read top level argument from a file
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use
--username string Username for basic authentication to the API server
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
Print version information for this ksonnet binary
The version command prints out version info about the current ksonnet CLI,
as well as for any of its helper libraries (e.g. client-go).
ks version [flags]
-h, --help help for version
-v, --verbose count[=-1] Increase verbosity. May be given multiple times.
