CLI reference

How to use the `ks` command

Overview

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:

Getting started

Fancier components

Environments

Miscellaneous

  • View expanded manifests
  • Validate manifests against the Kubernetes API
  • View metadata about the ksonnet binary

ks apply

Apply local Kubernetes manifests (components) to remote clusters

Synopsis

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.

Related Commands

  • ks diff — Compare manifests, based on environment or location (local or remote)
  • ks delete — Remove component-specified Kubernetes resources from remote clusters

Syntax

ks apply <env-name> [-c <component-name>] [--dry-run]

Examples


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

Options

      --as string                      Username to impersonate for the operation
      --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 stringArray          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
      --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")
      --resolve-images string          Change implementation of resolveImage native function. One of: noop, registry (default "noop")
      --resolve-images-error string    Action when resolveImage fails. One of ignore,warn,error (default "warn")
      --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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks delete

Remove component-specified Kubernetes resources from remote clusters

Synopsis

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.

Related Commands

  • ks diff — Compare manifests, based on environment or location (local or remote)
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters

Syntax

ks delete [env-name] [-c <component-name>]

Examples

# 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

Options

      --as string                      Username to impersonate for the operation
      --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 stringArray          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)
      --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")
      --resolve-images string          Change implementation of resolveImage native function. One of: noop, registry (default "noop")
      --resolve-images-error string    Action when resolveImage fails. One of ignore,warn,error (default "warn")
      --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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks diff

Compare manifests, based on environment or location (local or remote)

Synopsis

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:

  1. Remote and local manifests for a single environment
  2. Remote manifests for two separate environments
  3. Local manifests for two separate environments
  4. A remote manifest in one environment and a local manifest in another environment

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.

Related Commands

  • ks param diff — Display differences between the component parameters of two environments

Syntax

ks diff <location1:env1> [location2:env2] [-c <component-name>]

Examples


# 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

Options

  -c, --component stringArray         Name of a specific component (multiple -c flags accepted, allows YAML, JSON, and Jsonnet)
      --diff-strategy string          Diff strategy, all or subset. (default "all")
  -V, --ext-str stringSlice           Values of external variables
      --ext-str-file stringSlice      Read external variable from a file
  -J, --jpath stringSlice             Additional jsonnet library search path
      --resolve-images string         Change implementation of resolveImage native function. One of: noop, registry (default "noop")
      --resolve-images-error string   Action when resolveImage fails. One of ignore,warn,error (default "warn")
  -A, --tla-str stringSlice           Values of top level arguments
      --tla-str-file stringSlice      Read top level argument from a file

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks env

ks env add

Add a new environment to a ksonnet application

Synopsis

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. Name — A string used to uniquely identify the environment.
  2. Server — The address and port of a Kubernetes API server (i.e. cluster).
  3. Namespace — A Kubernetes namespace. Must already exist on the cluster.
  4. Kubernetes API Version — Used to generate a library with compatible type defs.

(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.

Related Commands

  • ks env list — List all locally available ksonnet prototypes
  • ks env rm
  • ks env set
  • ks param set — Change component or environment parameters (e.g. replica count, name)
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters

Syntax

ks env add <env-name>

Examples


# 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

Options

      --api-spec string   Manually specify API version from OpenAPI schema, cluster, or Kubernetes version (default "version:v1.7.0")

Options inherited from parent commands

      --as string                      Username to impersonate for the operation
      --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
      --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
      --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.

SEE ALSO

  • ks env - Manage ksonnet environments

ks env list

List all environments in a ksonnet application

Synopsis

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.

Related Commands

  • ks env add — Add a new environment to a ksonnet application
  • ks env set — Set environment-specific fields (name, namespace, server)
  • ks env rm — Delete an environment from a ksonnet application

Syntax

ks env list

Options inherited from parent commands

      --as string                      Username to impersonate for the operation
      --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
      --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
      --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.

SEE ALSO

  • ks env - Manage ksonnet environments

ks env rm

Delete an environment from a ksonnet application

Synopsis

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.

Related Commands

  • ks env list — List all locally available ksonnet prototypes
  • ks env add
  • ks env set
  • ks delete — Delete all the app components running in an environment (cluster)

Syntax

ks env rm <env-name>

Examples


# 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

Options inherited from parent commands

      --as string                      Username to impersonate for the operation
      --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
      --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
      --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.

SEE ALSO

  • ks env - Manage ksonnet environments

ks env set

Set environment-specific fields (name, namespace, server)

Synopsis

The set command lets you change the fields of an existing environment. You can update any of your environment’s (1) name (2) namespace and (3) server (cluster URI).

Note that changing the name of an environment will also update the corresponding directory structure in environments/.

Related Commands

  • ks env list — List all environments in a ksonnet application

Syntax

ks env set <env-name>

Examples

# Update the API server address of the environment 'us-west/staging'.
ks env set us-west/staging --server=http://example.com

# Update the namespace of the environment 'us-west/staging'.
ks env set us-west/staging --namespace=staging

# Update both the name and the server of the environment 'us-west/staging'.
# Updating the name will update the directory structure in 'environments/'.
ks env set us-west/staging --server=http://example.com --name=us-east/staging

# Update the API server address of the environment 'us-west/staging' based on the
# server in the 'staging-west' context of your kubeconfig file.
ks env set us-west/staging --context=staging-west

Options

      --name string   Name used to uniquely identify the environment. Must not already exist within the ksonnet app

Options inherited from parent commands

      --as string                      Username to impersonate for the operation
      --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
      --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
      --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.

SEE ALSO

  • ks env - Manage ksonnet environments

ks generate

Use the specified prototype to generate a component manifest

Synopsis

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).

  1. 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.

  2. 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

  1. Prototypes can be further customized by passing in parameters via additional command line flags, such as --image in the example above. Note that different prototypes support their own unique flags.

Related Commands

  • ks show — Show expanded manifests for a specific environment.
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters
  • ks param set Change component or environment parameters (e.g. replica count, name)

Syntax

ks generate <prototype-name> <component-name> [type] [parameter-flags]

Examples


# 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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks init

Initialize a ksonnet application

Synopsis

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.

Related Commands

  • ks generate — Use the specified prototype to generate a component manifest

Syntax

ks init <app-name> [flags]

Examples

# 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

Options

      --api-spec string                Manually specified Kubernetes API version. The corresponding OpenAPI spec is used to generate ksonnet's Kubernetes libraries (default "version:v1.7.0")
      --as string                      Username to impersonate for the operation
      --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
      --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
      --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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks param

ks param diff

Display differences between the component parameters of two environments

Synopsis

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.

Related Commands

  • ks param set — Change component or environment parameters (e.g. replica count, name)
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters

Syntax

ks param diff <env1> <env2> [--component <component-name>]

Examples


# 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

Options

      --component string   Specify the component to diff against

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks param - Manage ksonnet parameters for components and environments

ks param list

List known component parameters

Synopsis

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.

Related Commands

  • ks param set — Change component or environment parameters (e.g. replica count, name)

Syntax

ks param list [<component-name>] [--env <env-name>]

Examples


# 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

Options

      --env string   Specify environment to list parameters for

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks param - Manage ksonnet parameters for components and environments

ks param set

Change component or environment parameters (e.g. replica count, name)

Synopsis

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.)

Related Commands

  • ks param diff — Display differences between the component parameters of two environments
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters

Syntax

ks param set <component-name> <param-key> <param-value>

Examples


# 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

Options

      --env string   Specify environment to set parameters for

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks param - Manage ksonnet parameters for components and environments

ks pkg

ks pkg describe

Describe a ksonnet package and its contents

Synopsis

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:

  1. The library name
  2. A brief description provided by the library authors
  3. A list of available prototypes provided by the library

Related Commands

  • ks pkg list — List all packages known (downloaded or not) for the current ksonnet app
  • ks prototype describe — See more info about a prototype’s output and usage
  • ks generate — Use the specified prototype to generate a component manifest

Syntax

ks pkg describe [<registry-name>/]<package-name>

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks pkg - Manage packages and dependencies for the current ksonnet application

ks pkg install

Install a package (e.g. extra prototypes) for the current ksonnet app

Synopsis

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.

Related Commands

  • ks pkg list — List all packages known (downloaded or not) for the current ksonnet app
  • ks prototype list — List all locally available ksonnet prototypes
  • ks registry describe — Describe a ksonnet registry and the packages it contains

Syntax

ks pkg install <registry>/<library>@<version>

Examples


# Install an nginx dependency, based on the latest branch.
# 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

Options

      --name string   Name to give the dependency, to use within the ksonnet app

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks pkg - Manage packages and dependencies for the current ksonnet application

ks pkg list

List all packages known (downloaded or not) for the current ksonnet app

Synopsis

The list command outputs a table that describes all known packages (not necessarily downloaded, but available from existing registries). This includes the following info:

  1. Library name
  2. Registry name
  3. Installed status — an asterisk indicates ‘installed’

Related Commands

  • ks pkg install — Install a package (e.g. extra prototypes) for the current ksonnet app
  • ks pkg describe — Describe a ksonnet package and its contents
  • ks registry describe — Describe a ksonnet registry and the packages it contains

Syntax

ks pkg list

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks pkg - Manage packages and dependencies for the current ksonnet application

ks prototype

ks prototype describe

See more info about a prototype’s output and usage

Synopsis

This command outputs documentation, examples, and other information for the specified prototype (identified by name). Specifically, this describes:

  1. What sort of component is generated
  2. Which parameters (required and optional) can be passed in via CLI flags to customize the component
  3. The file format of the generated component manifest (currently, Jsonnet only)

Related Commands

  • ks prototype preview — Preview a prototype’s output without creating a component (stdout)
  • ks prototype use — Use the specified prototype to generate a component manifest

Syntax

ks prototype describe <prototype-name>

Examples


# Display documentation about the prototype 'io.ksonnet.pkg.single-port-deployment'
ks prototype describe deployment

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks prototype - Instantiate, inspect, and get examples for ksonnet prototypes

ks prototype list

List all locally available ksonnet prototypes

Synopsis

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.

Related Commands

  • ks prototype describe — See more info about a prototype’s output and usage
  • ks prototype preview — Preview a prototype’s output without creating a component (stdout)
  • ks prototype use — Use the specified prototype to generate a component manifest
  • ks pkg install Install a package (e.g. extra prototypes) for the current ksonnet app

Syntax

ks prototype list

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks prototype - Instantiate, inspect, and get examples for ksonnet prototypes

ks prototype preview

Preview a prototype’s output without creating a component (stdout)

Synopsis

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.

Related Commands

  • ks generate — Use the specified prototype to generate a component manifest

Syntax

ks prototype preview <prototype-name> [parameter-flags]

Examples


# 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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks prototype - Instantiate, inspect, and get examples for ksonnet prototypes

Search for a prototype

Synopsis

The prototype search command allows you to search for specific prototypes by name. Specifically, it matches any prototypes with names that contain the string .

Related Commands

  • ks prototype describe — See more info about a prototype’s output and usage
  • ks prototype list — List all locally available ksonnet prototypes

Syntax

ks prototype search <name-substring>

Examples


# Search for prototypes with names that contain the string 'service'.
ks prototype search service

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks prototype - Instantiate, inspect, and get examples for ksonnet prototypes

ks prototype use

Use the specified prototype to generate a component manifest

Synopsis

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).

  1. 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.

  2. 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

  1. Prototypes can be further customized by passing in parameters via additional command line flags, such as --image in the example above. Note that different prototypes support their own unique flags.

Related Commands

  • ks show — Show expanded manifests for a specific environment.
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters
  • ks param set Change component or environment parameters (e.g. replica count, name)

Syntax

ks prototype use <prototype-name> <componentName> [type] [parameter-flags]

Examples


# 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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks prototype - Instantiate, inspect, and get examples for ksonnet prototypes

ks registry

ks registry describe

Describe a ksonnet registry and the packages it contains

Synopsis

The describe command outputs documentation for the ksonnet registry identified by <registry-name>. Specifically, it displays the following:

  1. Registry URI
  2. Protocol (e.g. github)
  3. List of packages included in the registry

Related Commands

  • ks pkg install — Install a package (e.g. extra prototypes) for the current ksonnet app

Syntax

ks registry describe <registry-name>

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

ks registry list

List all registries known to the current ksonnet app.

Synopsis

The list command displays all known ksonnet registries in a table. This table includes the following info:

  1. Registry name
  2. Protocol (e.g. github)
  3. Registry URI

Related Commands

  • ks registry describe — Describe a ksonnet registry and the packages it contains

Syntax

ks registry list

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

ks show

Show expanded manifests for a specific environment.

Synopsis

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.

Related Commands

  • ks validate — Check generated component manifests against the server’s API
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters

Syntax

ks show <env> [-c <component-filename>]

Examples


# 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

Options

  -c, --component stringArray         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")
  -J, --jpath stringSlice             Additional jsonnet library search path
      --resolve-images string         Change implementation of resolveImage native function. One of: noop, registry (default "noop")
      --resolve-images-error string   Action when resolveImage fails. One of ignore,warn,error (default "warn")
  -A, --tla-str stringSlice           Values of top level arguments
      --tla-str-file stringSlice      Read top level argument from a file

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks validate

Check generated component manifests against the server’s API

Synopsis

The validate command checks that an application or file is compliant with the server API’s 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.

Related Commands

  • ks show — Show expanded manifests for a specific environment.
  • ks apply — Apply local Kubernetes manifests (components) to remote clusters

Syntax

ks validate <env-name> [-c <component-name>]

Examples


# 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

Options

      --as string                      Username to impersonate for the operation
      --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 stringArray          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
      --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")
      --resolve-images string          Change implementation of resolveImage native function. One of: noop, registry (default "noop")
      --resolve-images-error string    Action when resolveImage fails. One of ignore,warn,error (default "warn")
      --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

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster

ks version

Print version information for this ksonnet binary

Synopsis

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).

Syntax

ks version

Options inherited from parent commands

  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.

SEE ALSO

  • ks - Configure your application to deploy to a Kubernetes cluster