diff --git a/cmd/apply.go b/cmd/apply.go
index 9d9405bd72d6a39cf507a1531d4fc678e628164e..e5ad691ab4b9580753a09aa98ca0d6c5fae04207 100644
--- a/cmd/apply.go
+++ b/cmd/apply.go
@@ -45,6 +45,8 @@ const (
GcStrategyAuto = "auto"
// GcStrategyIgnore means this object should be ignored by garbage collection
GcStrategyIgnore = "ignore"
+
+ applyShortDesc = "Apply local Kubernetes manifests (components) to remote clusters"
)
func init() {
@@ -53,15 +55,15 @@ func init() {
addEnvCmdFlags(applyCmd)
bindClientGoFlags(applyCmd)
bindJsonnetFlags(applyCmd)
- applyCmd.PersistentFlags().Bool(flagCreate, true, "Create missing resources")
- applyCmd.PersistentFlags().Bool(flagSkipGc, false, "Don't perform garbage collection, even with --"+flagGcTag)
- applyCmd.PersistentFlags().String(flagGcTag, "", "Add this tag to updated objects, and garbage collect existing objects with this tag and not in config")
- applyCmd.PersistentFlags().Bool(flagDryRun, false, "Perform only read-only operations")
+ applyCmd.PersistentFlags().Bool(flagCreate, true, "Option to create resources if they do not already exist on the cluster")
+ applyCmd.PersistentFlags().Bool(flagSkipGc, false, "Option to skip garbage collection, even with --"+flagGcTag+" specified")
+ applyCmd.PersistentFlags().String(flagGcTag, "", "A tag that's (1) added to all updated objects (2) used to garbage collect existing objects that are no longer in the manifest")
+ applyCmd.PersistentFlags().Bool(flagDryRun, false, "Option to preview the list of operations without changing the cluster state")
}
var applyCmd = &cobra.Command{
- Use: "apply <env-name>",
- Short: `Apply local Kubernetes manifests to remote clusters`,
+ Use: "apply <env-name> [-c <component-name>] [--dry-run]",
+ Short: applyShortDesc,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("'apply' requires an environment name; use `env list` to see available environments\n\n%s", cmd.UsageString())
@@ -122,45 +124,50 @@ var applyCmd = &cobra.Command{
return c.Run(objs, wd)
},
Long: `
-Update (or optionally create) Kubernetes resources on the cluster using your
-local Kubernetes manifests. Use the` + " `--create` " + `flag to control whether
-they are created if they do not exist (default: true).
+The ` + "`apply`" + `command 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.
-The local Kubernetes manifests that are applied reside in your ` + "`components/`" + `
-directory. When applied, the manifests are fully expanded using the paremeters
-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.
-By default, all manifests are applied. To apply a subset of manifests, 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 delete` " + `— Delete the component manifests on your cluster
+* ` + "`ks diff` " + `— ` + diffShortDesc + `
+* ` + "`ks delete` " + `— ` + deleteShortDesc + `
### Syntax
`,
Example: `
-# Create or update all resources described in a ksonnet application, and
-# running in the 'dev' environment. Can be used in any subdirectory of the
-# application.
+# 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 is equivalent to applying all components in the 'components/' directory.
+# This essentially deploys all components in the 'components/' directory.
ks apply dev
-# Create or update the single resource 'guestbook-ui' described in a ksonnet
-# application, and running in the 'dev' environment. Can be used in any
-# subdirectory of the application.
+# 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 is equivalent to applying the component with the same file name (excluding
-# the extension) 'guestbook-ui' in the 'components/' directory.
+# This essentially deploys 'components/guestbook-ui.jsonnet'.
ks apply dev -c guestbook-ui
-# Create or update the multiple resources, 'guestbook-ui' and 'nginx-depl'
-# described in a ksonnet application, and running in the 'dev' environment. Can
-# be used in any subdirectory of the application.
+# 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 is equivalent to applying the component with the same file name (excluding
-# the extension) 'guestbook-ui' and 'nginx-depl' in the 'components/' directory.
-ks apply dev -c guestbook-ui -c nginx-depl
+# This essentially deploys 'components/guestbook-ui.jsonnet' and
+# 'components/nginx-depl.jsonnet'.
+ks apply dev -c guestbook-ui -c nginx-depl --create false
`,
}
diff --git a/cmd/delete.go b/cmd/delete.go
index 59eef3fcb435f730f0cfc09d79a6534295ca2a38..a94827298a4429886a3db3758e5cbcb945d3ee08 100644
--- a/cmd/delete.go
+++ b/cmd/delete.go
@@ -27,6 +27,7 @@ import (
const (
flagGracePeriod = "grace-period"
+ deleteShortDesc = "Remove component-specified Kubernetes resources from remote clusters"
)
func init() {
@@ -38,8 +39,8 @@ func init() {
}
var deleteCmd = &cobra.Command{
- Use: "delete [env-name] [-f <file-or-dir>]",
- Short: "Delete Kubernetes resources described in local config",
+ Use: "delete [env-name] [-c <component-name>]",
+ Short: deleteShortDesc,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("'delete' requires an environment name; use `env list` to see available environments\n\n%s", cmd.UsageString())
@@ -84,24 +85,30 @@ var deleteCmd = &cobra.Command{
return c.Run(objs)
},
- Long: `Delete Kubernetes resources from a cluster, as described in the local
-configuration.
+ Long: `
+The ` + "`delete`" + ` command removes Kubernetes resources (described in local
+*component* manifests) from a cluster. This cluster is determined by the mandatory
+` + "`<env-name>`" + `argument.
-ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
-files.`,
- Example: `# Delete all resources described in a ksonnet application, from the 'dev'
-# environment. Can be used in any subdirectory of the application.
-ks delete dev
+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.**
-# Delete resources described in a YAML file. Automatically picks up the
-# cluster's location from '$KUBECONFIG'.
-ks delete -f ./pod.yaml
+### Related Commands
-# Delete resources described in the JSON file from the 'dev' environment. Can
-# be used in any subdirectory of the application.
-ks delete dev -f ./pod.json
+* ` + "`ks diff` " + `— Compare manifests, based on environment or location (local or remote)
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
+
+### Syntax
+`,
+ Example: `# 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 in a YAML file, and running in the cluster
-# specified by the current context in specified kubeconfig file.
-ks delete --kubeconfig=./kubeconfig -f ./pod.yaml`,
+# 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`,
}
diff --git a/cmd/diff.go b/cmd/diff.go
index 7aaf80cc9dfdffffe78335574e9787a0fc2baac9..def0ff548ef28b993fcd0f49fcc887143f46293d 100644
--- a/cmd/diff.go
+++ b/cmd/diff.go
@@ -31,7 +31,10 @@ import (
"github.com/ksonnet/ksonnet/pkg/kubecfg"
)
-const flagDiffStrategy = "diff-strategy"
+const (
+ flagDiffStrategy = "diff-strategy"
+ diffShortDesc = "Compare manifests, based on environment or location (local or remote)"
+)
func init() {
addEnvCmdFlags(diffCmd)
@@ -41,8 +44,8 @@ func init() {
}
var diffCmd = &cobra.Command{
- Use: "diff [<env1> [<env2>]] [-f <file-or-dir>]",
- Short: "Display differences between server and local config, or server and server config",
+ Use: "diff <location1:env1> [location2:env2] [-c <component-name>]",
+ Short: diffShortDesc,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) == 0 {
return fmt.Errorf("'diff' requires at least one argument, that is the name of the environment\n\n%s", cmd.UsageString())
@@ -86,40 +89,55 @@ var diffCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout())
},
- Long: `Display differences between server and local configuration, or server and server
-configurations.
-
-ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
-files.`,
- Example: `# Show diff between resources described in a the local 'dev' environment
-# specified by the ksonnet application and the remote cluster referenced by
-# the same 'dev' environment. Can be used in any subdirectory of the application.
-ksonnet diff dev
-
-# Show diff between resources at remote clusters. This requires ksonnet
-# application defined environments. Diff between the cluster defined at the
-# 'us-west/dev' environment, and the cluster defined at the 'us-west/prod'
-# environment. Can be used in any subdirectory of the application.
-ksonnet diff remote:us-west/dev remote:us-west/prod
-
-# Show diff between resources at a remote and a local cluster. This requires
-# ksonnet application defined environments. Diff between the cluster defined
-# at the 'us-west/dev' environment, and the cluster defined at the
-# 'us-west/prod' environment. Can be used in any subdirectory of the
-# application.
-ksonnet diff local:us-west/dev remote:us-west/prod
-
-# Show diff between resources described in a YAML file and the cluster
-# referenced in '$KUBECONFIG'.
-ks diff -f ./pod.yaml
-
-# Show diff between resources described in a JSON file and the cluster
-# referenced by the environment 'dev'.
-ks diff dev -f ./pod.json
-
-# Show diff between resources described in a YAML file and the cluster
-# referred to by './kubeconfig'.
-ks diff --kubeconfig=./kubeconfig -f ./pod.yaml`,
+ Long: `
+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` " + `— ` + paramShortDesc["diff"] + `
+
+### Syntax
+`,
+ Example: `
+# 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
+`,
}
func initDiffCmd(cmd *cobra.Command, wd metadata.AbsPath, envFq1, envFq2 *string, files []string, diffStrategy string) (kubecfg.DiffCmd, error) {
diff --git a/cmd/env.go b/cmd/env.go
index 98dab6b645f137a972f77c545c50c3624d1c073d..8be4cf466b1379894ed8e499ba28900d45d3bc47 100644
--- a/cmd/env.go
+++ b/cmd/env.go
@@ -34,6 +34,13 @@ const (
flagEnvContext = "context"
)
+var envShortDesc = map[string]string{
+ "add": "Add a new environment to a ksonnet application",
+ "list": "List all environments in a ksonnet application",
+ "rm": "Delete an environment from a ksonnet application",
+ "set": "Set environment-specific fields (name, namespace, server)",
+}
+
func init() {
RootCmd.AddCommand(envCmd)
bindClientGoFlags(envCmd)
@@ -48,46 +55,48 @@ func init() {
"Manually specify API version from OpenAPI schema, cluster, or Kubernetes version")
envSetCmd.PersistentFlags().String(flagEnvName, "",
- "Specify name to rename environment to. Name must not already exist")
+ "Name used to uniquely identify the environment. Must not already exist within the ksonnet app")
}
var envCmd = &cobra.Command{
Use: "env",
Short: `Manage ksonnet environments`,
- Long: `An environment acts as a sort of "named cluster", allowing for commands like
-` + " `ks apply dev` " + `, which applies the ksonnet application to the 'dev cluster'.
-Additionally, environments allow users to cache data about the cluster it points
-to, including data needed to run 'verify', and a version of ksonnet-lib that is
-generated based on the flags the API server was started with (e.g., RBAC enabled
-or not).
-
-An environment contains no user-specific data (such as the private key
-often contained in a kubeconfig file), and
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application. For example, in the example below, there are two
-environments: 'default' and 'us-west/staging'. Each contains a cached version of
-` + " `ksonnet-lib` " + `, and a` + " `spec.json` " + `that contains the server and server cert that
-uniquely identifies the cluster.
-
- environments/
- default/ [Default generated environment]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json
- default.jsonnet
- params.libsonnet
- us-west/
- staging/ [Example of user-generated env]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json [This will contain the API server address of the environment and other environment metadata]
- staging.jsonnet
- params.libsonnet`,
+ Long: `
+An environment is a deployment target for your ksonnet app and its constituent
+components. You can use ksonnet to deploy a given app to *multiple* environments,
+such as ` + "`dev`" + ` and ` + "`prod`" + `.
+
+Intuitively, an environment acts as a sort of "named cluster", similar to a
+Kubernetes context. (Running ` + "`ks env add --help`" + ` provides more detail
+about the fields that you need to create an environment).
+
+**All of this environment info is cached in local files**. Environments are
+represented as a hierarchy in the ` + "`environments/`" + ` directory of a ksonnet app, like
+'default' and 'us-west/staging' in the example below.
+
+` + "```" + `
+├── environments
+│ ├── base.libsonnet
+│ ├── default // Default generated environment ('ks init')
+│ │ ├── .metadata
+│ │ │ ├── k.libsonnet
+│ │ │ ├── k8s.libsonnet
+│ │ │ └── swagger.json
+│ │ ├── main.jsonnet
+│ │ ├── params.libsonnet
+│ │ └── spec.json
+│ └── us-west
+│ └── staging // Example of user-generated env ('ks env add')
+│ ├── .metadata
+│ │ ├── k.libsonnet // Jsonnet library with Kubernetes-compatible types and definitions
+│ │ ├── k8s.libsonnet
+│ │ └── swagger.json
+│ ├── main.libsonnet // Main file that imports all components (expanded on apply, delete, etc). Add environment-specific logic here.
+│ ├── params.libsonnet // Customize components *per-environment* here.
+│ └── spec.json // Contains the environment's API server address and namespace
+` + "```" + `
+----
+`,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
return fmt.Errorf("%s is not a valid subcommand\n\n%s", strings.Join(args, " "), cmd.UsageString())
@@ -98,7 +107,7 @@ uniquely identifies the cluster.
var envAddCmd = &cobra.Command{
Use: "add <env-name>",
- Short: "Add a new environment to a ksonnet project",
+ Short: envShortDesc["add"],
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 1 {
@@ -136,55 +145,59 @@ var envAddCmd = &cobra.Command{
return c.Run()
},
- Long: `Add a new environment to a ksonnet project. Names are restricted to not
-include punctuation, so names like` + " `../foo` " + `are not allowed.
-
-An environment acts as a sort of "named cluster", allowing for commands like
-` + " `ks apply dev` " + `, which applies the ksonnet application to the "dev cluster".
-For more information on what an environment is and how they work, run` + " `ks help env` " + `.
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application, and hence` + " `ks env add` " + `will add to this directory structure.
-For example, in the example below, there are two environments: 'default' and
-'us-west/staging'.` + " `ks env add` " + `will add a similar directory to this environment.
-
- environments/
- default/ [Default generated environment]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json
- default.jsonnet
- params.libsonnet
- us-west/
- staging/ [Example of user-generated env]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json [This will contain the API server address of the environment and other environment metadata],
- staging.jsonnet
- params.libsonnet`,
- Example: `# Initialize a new staging environment at 'us-west'.
-# The environment will be setup using the current context in your kubecfg file. The directory
-# structure rooted at 'us-west' in the documentation above will be generated.
+ Long: `
+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` " + `— ` + protoShortDesc["list"] + `
+* ` + "`ks env rm` " + `— ` + protoShortDesc["rm"] + `
+* ` + "`ks env set` " + `— ` + protoShortDesc["set"] + `
+* ` + "`ks param set` " + `— ` + paramShortDesc["set"] + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
+
+### Syntax
+`,
+ Example: `
+# 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 staging environment at 'us-west' with the namespace 'staging', using
-# the OpenAPI specification generated in the Kubernetes v1.7.1 build to generate 'ksonnet-lib'.
+# 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 using the 'dev' context in your kubeconfig file.
+# 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 using a server address.
-ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com`,
+# 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`,
}
var envRmCmd = &cobra.Command{
Use: "rm <env-name>",
- Short: "Delete an environment from a ksonnet project",
+ Short: envShortDesc["rm"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("'env rm' takes a single argument, that is the name of the environment")
@@ -210,17 +223,32 @@ var envRmCmd = &cobra.Command{
return c.Run()
},
- Long: `Delete an environment from a ksonnet project. This is the same
-as removing the <env-name> environment directory and all files contained. All empty
-parent directories are also subsequently deleted.`,
- Example: `# Remove the directory 'us-west/staging' and all contents in the 'environments'
-# directory. This will also remove the parent directory 'us-west' if it is empty.
+ Long: `
+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` " + `— ` + protoShortDesc["list"] + `
+* ` + "`ks env add` " + `— ` + protoShortDesc["add"] + `
+* ` + "`ks env set` " + `— ` + protoShortDesc["set"] + `
+* ` + "`ks delete` " + `— ` + `Delete all the app components running in an environment (cluster)` + `
+
+### Syntax
+`,
+ Example: `
+# 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`,
}
var envListCmd = &cobra.Command{
Use: "list",
- Short: "List all environments in a ksonnet project",
+ Short: envShortDesc["list"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
return fmt.Errorf("'env list' takes zero arguments")
@@ -243,13 +271,24 @@ var envListCmd = &cobra.Command{
}
return c.Run(cmd.OutOrStdout())
- }, Long: `List all environments in a ksonnet project. This will
-display the name, server, and namespace of each environment within the ksonnet project.`,
+ }, Long: `
+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` " + `— ` + envShortDesc["add"] + `
+* ` + "`ks env set` " + `— ` + envShortDesc["set"] + `
+* ` + "`ks env rm` " + `— ` + envShortDesc["rm"] + `
+
+### Syntax
+`,
}
var envSetCmd = &cobra.Command{
Use: "set <env-name>",
- Short: "Set environment fields such as the name, server, and namespace.",
+ Short: envShortDesc["set"],
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 1 {
@@ -283,21 +322,32 @@ var envSetCmd = &cobra.Command{
return c.Run()
},
- Long: `Set environment fields such as the name, and server. Changing
-the name of an environment will also update the directory structure in
-'environments'.`,
- Example: `# Updates the API server address of the environment 'us-west/staging'.
+ Long: `
+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` " + `— ` + envShortDesc["list"] + `
+
+### Syntax
+`,
+ Example: `# Update the API server address of the environment 'us-west/staging'.
ks env set us-west/staging --server=http://example.com
-# Updates the namespace of the environment 'us-west/staging'.
+# Update the namespace of the environment 'us-west/staging'.
ks env set us-west/staging --namespace=staging
-# Updates both the name and the server of the environment 'us-west/staging'.
-# Updating the name will update the directory structure in 'environments'.
+# 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
-
-# Updates API server address of the environment 'us-west/staging' based on the
-# server in the context 'staging-west' in your kubeconfig file.
+
+# 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`,
}
diff --git a/cmd/init.go b/cmd/init.go
index 3320522c6636ba88914ba30c653d51708a9c6182..2b44b57ca2ba652d44aad865d5ba29b9b990e113 100644
--- a/cmd/init.go
+++ b/cmd/init.go
@@ -28,14 +28,15 @@ import (
)
const (
- flagInitDir = "dir"
+ flagInitDir = "dir"
+ initShortDesc = "Initialize a ksonnet application"
)
func init() {
RootCmd.AddCommand(initCmd)
// TODO: We need to make this default to checking the `kubeconfig` file.
initCmd.PersistentFlags().String(flagAPISpec, "version:v1.7.0",
- "Manually specify API version from OpenAPI schema, cluster, or Kubernetes version")
+ "Manually specified Kubernetes API version. The corresponding OpenAPI spec is used to generate ksonnet's Kubernetes libraries")
bindClientGoFlags(initCmd)
initCmd.Flags().String(flagInitDir, "", "Ksonnet application directory")
@@ -43,7 +44,7 @@ func init() {
var initCmd = &cobra.Command{
Use: "init <app-name>",
- Short: "Initialize a ksonnet application",
+ Short: initShortDesc,
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 1 {
@@ -86,49 +87,57 @@ var initCmd = &cobra.Command{
return c.Run()
},
- Long: `Initialize a ksonnet application in a new directory,` + " `app-name`" + `.
+ Long: `
+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 your 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, ex: name, api version
+ 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/ part libraries, prototypes
+ 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] Each environment uses a specific version of ksonnet-lib. Users can set flags
-to generate the library based on a variety of data, including server
-configuration and an OpenAPI specification of a Kubernetes build. By default,
-this is generated from the capabilities of the cluster specified in the cluster
-of the current context specified in` + " `$KUBECONFIG`" + `.
+[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` " + `— ` + protoShortDesc["use"] + `
+
+### Syntax
`,
Example: `# Initialize a ksonnet application, based on cluster information from the
-# active kubeconfig file (specified by the environment variable $KUBECONFIG).
+# 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). This initializes the default environment
-# using the server address and default namespace located at the context 'dev'.
+# 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). This initializes
-# the default environment using the server address at the context 'dev' for
-# the namespace 'dc-west'.
+# '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
@@ -139,8 +148,8 @@ ks init app-name --api-spec=version:v1.7.1
# specific build of Kubernetes to generate 'ksonnet-lib'.
ks init app-name --api-spec=file:swagger.json
-# Initialize a ksonnet application, using a custom location for the application
-# directory.
+# Initialize a ksonnet application, outputting the application directory into
+# the specified 'custom-location'.
ks init app-name --dir=custom-location`,
}
diff --git a/cmd/param.go b/cmd/param.go
index 7b9b91208452c8607fbfec8b9d0a380bf2184c48..40b4fc046fc4909b9b5648c829e25cca17775ac5 100644
--- a/cmd/param.go
+++ b/cmd/param.go
@@ -29,6 +29,12 @@ const (
flagParamComponent = "component"
)
+var paramShortDesc = map[string]string{
+ "set": "Change component or environment parameters (e.g. replica count, name)",
+ "list": "List known component parameters",
+ "diff": "Display differences between the component parameters of two environments",
+}
+
func init() {
RootCmd.AddCommand(paramCmd)
@@ -43,20 +49,35 @@ func init() {
var paramCmd = &cobra.Command{
Use: "param",
- Short: `Manage ksonnet component parameters`,
- Long: `Parameters are the customizable fields defining ksonnet components. For
-example, replica count, component name, or deployment image.
-
-Parameters are also able to be defined separately across environments. Meaning,
-this supports features to allow a "development" environment to only run a
-single replication instance for it's components, whereas allowing a "production"
-environment to run more replication instances to meet heavier production load
-demands.
-
-Environments are ksonnet "named clusters". For more information on environments,
-run:
-
- ks env --help
+ Short: `Manage ksonnet parameters for components and environments`,
+ Long: `
+Parameters are customizable fields that are used inside ksonnet *component*
+manifests. Examples might include a deployment's 'name' or 'image'. Parameters
+can also be defined on a *per-environment* basis. (Environments are ksonnet
+deployment targets, e.g. specific clusters. For more info, run ` + "`ks env --help`" + `.)
+
+For example, this allows a ` + "`dev`" + ` and ` + "`prod`" + ` environment to use the same component
+manifest for an nginx deployment, but customize ` + "`prod`" + ` to use more replicas to meet
+heavier load demands.
+
+Params are structured as follows:
+
+* App params (stored in ` + "`components/params.libsonnet`" + `)
+ * Component-specific params
+ * Originally populated from ` + "`ks generate`" + `
+ * e.g. 80 for ` + "`deployment-example.port`" + `
+ * Global params
+ * Out of scope for CLI (requires Jsonnet editing)
+ * Use to make a variable accessible to multiple components (e.g. service name)
+
+* Per-environment params (stored in + ` + "`environments/<env-name>/params.libsonnet`" + `)
+ * Component-specific params ONLY
+ * Override app params (~inheritance)
+
+Note that all of these params are tracked **locally** in version-controllable
+Jsonnet files.
+
+----
`,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
@@ -68,11 +89,11 @@ run:
var paramSetCmd = &cobra.Command{
Use: "set <component-name> <param-key> <param-value>",
- Short: "Set component or environment parameters such as replica count or name",
+ Short: paramShortDesc["set"],
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 3 {
- return fmt.Errorf("'param set' takes exactly three arguments, the name of the component, and the key and value of the parameter, respectively")
+ return fmt.Errorf("'param set' takes exactly three arguments, (1) the name of the component, in addition to (2) the key and (3) value of the parameter")
}
component := args[0]
@@ -88,25 +109,37 @@ var paramSetCmd = &cobra.Command{
return c.Run()
},
- Long: `Set component or environment parameters such as replica count or name.
+ Long: `
+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
-Parameters are set individually, one at a time. If you require customization of
-more fields, we suggest that you modify your ksonnet project'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` " + `— ` + paramShortDesc["diff"] + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
+
+### Syntax
`,
- Example: `# Updates the replica count of the 'guestbook' component to 4.
+ Example: `
+# Update the replica count of the 'guestbook' component to 4.
ks param set guestbook replicas 4
-# Updates the replica count of the 'guestbook' component to 2 for the environment
-# 'dev'
+# Update the replica count of the 'guestbook' component to 2, but only for the
+# 'dev' environment
ks param set guestbook replicas 2 --env=dev`,
}
var paramListCmd = &cobra.Command{
- Use: "list <component-name>",
- Short: "List all parameters for a component(s)",
+ Use: "list [<component-name>] [--env <env-name>]",
+ Short: paramShortDesc["list"],
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) > 1 {
@@ -127,14 +160,21 @@ var paramListCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout())
},
- Long: `List all component parameters or environment parameters.
-
-This command will display all parameters for the component specified. If a
-component is not specified, parameters for all components will be listed.
+ Long: `
+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` " + `— ` + paramShortDesc["set"] + `
+
+### Syntax
`,
- Example: `# List all component parameters
+ Example: `
+# List all component parameters
ks param list
# List all parameters for the component "guestbook"
@@ -148,12 +188,12 @@ ks param list guestbook --env=dev`,
}
var paramDiffCmd = &cobra.Command{
- Use: "diff <env1> <env2>",
- Short: "Display differences between the component parameters of two environments",
+ Use: "diff <env1> <env2> [--component <component-name>]",
+ Short: paramShortDesc["diff"],
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 2 {
- return fmt.Errorf("'param diff' takes exactly two arguments, that is the name of the environments to diff against")
+ return fmt.Errorf("'param diff' takes exactly two arguments: the respective names of the environments being diffed")
}
env1 := args[0]
@@ -168,14 +208,25 @@ var paramDiffCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout())
},
- Long: `Pretty prints differences between the component parameters of two environments.
+ Long: `
+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` " + `— ` + paramShortDesc["set"] + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
-A component flag is accepted to diff against a single component. By default, the
-diff is performed against all components.
+### Syntax
`,
- Example: `# Diff between the component parameters on environments 'dev' and 'prod'
+ Example: `
+# Diff between all component parameters for environments 'dev' and 'prod'
ks param diff dev prod
-# Diff between the component 'guestbook' on environments 'dev' and 'prod'
+# Diff only between the parameters for the 'guestbook' component for environments
+# 'dev' and 'prod'
ks param diff dev prod --component=guestbook`,
}
diff --git a/cmd/pkg.go b/cmd/pkg.go
index adc4c7d3b1ab3b0f4a4efd891d5f0981c8add6d4..ac47f048df2a47fe6e59b0cf6fcfce3f11da42b5 100644
--- a/cmd/pkg.go
+++ b/cmd/pkg.go
@@ -30,6 +30,12 @@ const (
flagName = "name"
)
+var pkgShortDesc = map[string]string{
+ "install": "Install a package (e.g. extra prototypes) for the current ksonnet app",
+ "describe": "Describe a ksonnet package and its contents",
+ "list": "List all packages known (downloaded or not) for the current ksonnet app",
+}
+
var errInvalidSpec = fmt.Errorf("Command 'pkg install' requires a single argument of the form <registry>/<library>@<version>")
func init() {
@@ -37,12 +43,38 @@ func init() {
pkgCmd.AddCommand(pkgInstallCmd)
pkgCmd.AddCommand(pkgListCmd)
pkgCmd.AddCommand(pkgDescribeCmd)
- pkgInstallCmd.PersistentFlags().String(flagName, "", "Name to give the dependency")
+ pkgInstallCmd.PersistentFlags().String(flagName, "", "Name to give the dependency, to use within the ksonnet app")
}
var pkgCmd = &cobra.Command{
Use: "pkg",
- Short: `Manage packages and dependencies for the current ksonnet project`,
+ Short: `Manage packages and dependencies for the current ksonnet application`,
+ Long: `
+A ksonnet package contains:
+
+* A set of prototypes (see ` + "`ks prototype --help`" + ` for more info on prototypes), which
+generate similar types of components (e.g. ` + "`redis-stateless`" + `, ` + "`redis-persistent`" + `)
+* Associated helper libraries that define the prototype parts (e.g. ` + "`redis.libsonnet`" + `)
+
+Packages allow you to easily distribute and reuse code in any ksonnet application.
+Packages come from registries, such as Github repositories. (For more info, see
+` + "`ks registry --help`" + `).
+
+To be recognized and imported by ksonnet, packages need to follow a specific schema.
+See the annotated file tree below, as an example:
+
+` + "```" + `
+.
+├── README.md // Human-readable description of the package
+├── parts.yaml // Provides metadata about the package
+├── prototypes // Can be imported and used to generate components
+│ ├── redis-all-features.jsonnet
+│ ├── redis-persistent.jsonnet
+│ └── redis-stateless.jsonnet
+└── redis.libsonnet // Helper library, includes prototype parts
+` + "```" + `
+---
+`,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
return fmt.Errorf("%s is not a valid subcommand\n\n%s", strings.Join(args, " "), cmd.UsageString())
@@ -53,7 +85,7 @@ var pkgCmd = &cobra.Command{
var pkgInstallCmd = &cobra.Command{
Use: "install <registry>/<library>@<version>",
- Short: `Install a package as a dependency in the current ksonnet application`,
+ Short: pkgShortDesc["install"],
Aliases: []string{"get"},
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
@@ -83,36 +115,34 @@ var pkgInstallCmd = &cobra.Command{
return nil
},
- Long: `Cache a ksonnet library locally, and make it available for use in the current
-ksonnet project. This particularly means that we record enough information in
-` + " `app.yaml` " + `for new users to retrieve the dependency after a fresh clone of the
-app repository.
-
-For example, inside a ksonnet application directory, run:
-
- ks pkg install incubator/nginx@v0.1
-
-This can then be referenced in a source file in the ksonnet project:
-
- local nginx = import "kspkg://nginx";
-
-By default, ksonnet knows about two registries: incubator and stable, which are
-the release channels for official ksonnet libraries. Additional registries can
-be added with the` + " `ks registry` " + `command.
-
-Note that multiple versions of the same ksonnet library can be cached and used
-in the same project, by explicitly passing in the` + " `--name` " + `flag. For example:
-
- ks pkg install incubator/nginx@v0.1 --name nginxv1
- ks pkg install incubator/nginx@v0.2 --name nginxv2
-
-With these commands, a user can` + " `import \"kspkg://nginxv1\"` " + `, and
-` + " `import \"kspkg://nginxv2\"` " + `with no conflict.`,
+ Long: `
+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` " + `— ` + pkgShortDesc["list"] + `
+* ` + "`ks prototype list` " + `— ` + protoShortDesc["list"] + `
+* ` + "`ks registry describe` " + `— ` + regShortDesc["describe"] + `
+
+### Syntax
+`,
+ Example: `
+# 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
+`,
}
var pkgDescribeCmd = &cobra.Command{
Use: "describe [<registry-name>/]<package-name>",
- Short: `Describe a ksonnet package`,
+ Short: pkgShortDesc["describe"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("Command 'pkg describe' requires a package name\n\n%s", cmd.UsageString())
@@ -165,13 +195,28 @@ var pkgDescribeCmd = &cobra.Command{
return nil
},
- Long: `Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some 'registry-name'.`,
+ Long: `
+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` " + `— ` + pkgShortDesc["list"] + `
+* ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
+* ` + "`ks generate` " + `— ` + protoShortDesc["use"] + `
+
+### Syntax
+`,
}
var pkgListCmd = &cobra.Command{
Use: "list",
- Short: `Lists information about all dependencies known to the current ksonnet app`,
+ Short: pkgShortDesc["list"],
RunE: func(cmd *cobra.Command, args []string) error {
const (
nameHeader = "NAME"
@@ -230,6 +275,23 @@ var pkgListCmd = &cobra.Command{
fmt.Print(formatted)
return nil
},
+ Long: `
+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` " + `— ` + pkgShortDesc["install"] + `
+* ` + "`ks pkg describe` " + `— ` + pkgShortDesc["describe"] + `
+* ` + "`ks registry describe` " + `— ` + regShortDesc["describe"] + `
+
+### Syntax
+`,
}
func parsePkgSpec(spec string) (registry, libID string, err error) {
diff --git a/cmd/prototype.go b/cmd/prototype.go
index 9ab227ef14bf98fd2e840be93a51b80477310129..735391a8bc44435c85a3d2770faee70ec3a4a173 100644
--- a/cmd/prototype.go
+++ b/cmd/prototype.go
@@ -30,6 +30,14 @@ import (
"github.com/spf13/cobra"
)
+var protoShortDesc = map[string]string{
+ "list": "List all locally available ksonnet prototypes",
+ "describe": "See more info about a prototype's output and usage",
+ "preview": "Preview a prototype's output without creating a component (stdout)",
+ "search": "Search for a prototype",
+ "use": "Use the specified prototype to generate a component manifest",
+}
+
func init() {
RootCmd.AddCommand(prototypeCmd)
RootCmd.AddCommand(generateCmd)
@@ -40,14 +48,6 @@ func init() {
prototypeCmd.AddCommand(prototypePreviewCmd)
}
-var cmdShortDesc = map[string]string{
- "list": `List all locally available ksonnet prototypes`,
- "describe": `See more info about a prototype's output and usage`,
- "preview": `Preview a prototype's output without creating a component (stdout)`,
- "search": `Search for a prototype`,
- "use": `Use the specified prototype to generate a component manifest`,
-}
-
var prototypeCmd = &cobra.Command{
Use: "prototype",
Short: `Instantiate, inspect, and get examples for ksonnet prototypes`,
@@ -70,12 +70,14 @@ These complete manifests are output into your ` + "`components/`" + ` directory.
words, prototypes provide the basis for the **components** of your app. You can
use prototypes to autogenerate boilerplate code and focus on customizing them
for your use case.
+
+----
`,
}
var prototypeListCmd = &cobra.Command{
Use: "list",
- Short: cmdShortDesc["list"],
+ Short: protoShortDesc["list"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
return fmt.Errorf("Command 'prototype list' does not take any arguments")
@@ -120,10 +122,10 @@ from the *incubator* registry.
### Related Commands
-* ` + "`ks prototype describe` " + `— ` + cmdShortDesc["describe"] + `
-* ` + "`ks prototype preview` " + `— ` + cmdShortDesc["preview"] + `
-* ` + "`ks prototype use` " + `— ` + cmdShortDesc["use"] + `
-* ` + "`ks pkg install` " + `— Install more prototypes (from external packages)
+* ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
+* ` + "`ks prototype preview` " + `— ` + protoShortDesc["preview"] + `
+* ` + "`ks prototype use` " + `— ` + protoShortDesc["use"] + `
+* ` + "`ks pkg install` " + pkgShortDesc["install"] + `
### Syntax
`,
@@ -131,7 +133,7 @@ from the *incubator* registry.
var prototypeDescribeCmd = &cobra.Command{
Use: "describe <prototype-name>",
- Short: cmdShortDesc["describe"],
+ Short: protoShortDesc["describe"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("Command 'prototype describe' requires a prototype name\n\n%s", cmd.UsageString())
@@ -187,8 +189,8 @@ the specified prototype (identified by name). Specifically, this describes:
### Related Commands
-* ` + "`ks prototype preview` " + `— ` + cmdShortDesc["preview"] + `
-* ` + "`ks prototype use` " + `— ` + cmdShortDesc["use"] + `
+* ` + "`ks prototype preview` " + `— ` + protoShortDesc["preview"] + `
+* ` + "`ks prototype use` " + `— ` + protoShortDesc["use"] + `
### Syntax
`,
@@ -200,7 +202,7 @@ ks prototype describe deployment`,
var prototypeSearchCmd = &cobra.Command{
Use: "search <name-substring>",
- Short: cmdShortDesc["search"],
+ Short: protoShortDesc["search"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("Command 'prototype search' requires a prototype name\n\n%s", cmd.UsageString())
@@ -226,8 +228,8 @@ Specifically, it matches any prototypes with names that contain the string <name
### Related Commands
-* ` + "`ks prototype describe` " + `— ` + cmdShortDesc["describe"] + `
-* ` + "`ks prototype list` " + `— ` + cmdShortDesc["list"] + `
+* ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
+* ` + "`ks prototype list` " + `— ` + protoShortDesc["list"] + `
### Syntax
`,
@@ -238,7 +240,7 @@ ks prototype search service`,
var prototypePreviewCmd = &cobra.Command{
Use: "preview <prototype-name> [parameter-flags]",
- Short: cmdShortDesc["preview"],
+ Short: protoShortDesc["preview"],
DisableFlagParsing: true,
RunE: func(cmd *cobra.Command, rawArgs []string) error {
if len(rawArgs) == 1 && (rawArgs[0] == "--help" || rawArgs[0] == "-h") {
@@ -318,7 +320,7 @@ a component with ` + "`ks generate`" + ` and then use ` + "`ks show`" + `.
### Related Commands
-* ` + "`ks generate` " + `— ` + cmdShortDesc["use"] + `
+* ` + "`ks generate` " + `— ` + protoShortDesc["use"] + `
### Syntax
`,
@@ -342,7 +344,7 @@ var generateCmd = &cobra.Command{
var prototypeUseCmd = &cobra.Command{
Use: "use <prototype-name> <componentName> [type] [parameter-flags]",
- Short: cmdShortDesc["use"],
+ Short: protoShortDesc["use"],
DisableFlagParsing: true,
RunE: func(cmd *cobra.Command, rawArgs []string) error {
if len(rawArgs) == 1 && (rawArgs[0] == "--help" || rawArgs[0] == "-h") {
@@ -452,8 +454,9 @@ different prototypes support their own unique flags.
### Related Commands
-* ` + "`ks apply` " + `— Apply your component manifests to a cluster
-* ` + "`ks param set` " + `— Change the values you specified when generating the component
+* ` + "`ks show` " + `— ` + showShortDesc + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
+* ` + "`ks param set` " + paramShortDesc["set"] + `
### Syntax
`,
diff --git a/cmd/registry.go b/cmd/registry.go
index 87339173eace8fe9cc4509d85c9b3348e10e60dc..6f6b85003e48355de3b4c6ff42cd98069740dbd5 100644
--- a/cmd/registry.go
+++ b/cmd/registry.go
@@ -10,6 +10,11 @@ import (
"github.com/spf13/cobra"
)
+var regShortDesc = map[string]string{
+ "list": "List all registries known to the current ksonnet app.",
+ "describe": "Describe a ksonnet registry and the packages it contains",
+}
+
func init() {
RootCmd.AddCommand(registryCmd)
registryCmd.AddCommand(registryListCmd)
@@ -25,24 +30,28 @@ var registryCmd = &cobra.Command{
}
return fmt.Errorf("Command 'registry' requires a subcommand\n\n%s", cmd.UsageString())
},
- Long: `Manage and inspect ksonnet registries.
-
-Registries contain a set of versioned libraries that the user can install and
-manage in a ksonnet project using the CLI. A typical library contains:
-
- 1. A set of "parts", pre-fabricated API objects which can be combined together
- to configure a Kubernetes application for some task. For example, the Redis
- library may contain a Deployment, a Service, a Secret, and a
- PersistentVolumeClaim, but if the user is operating it as a cache, they may
- only need the first three of these.
- 2. A set of "prototypes", which are pre-fabricated combinations of these
- parts, made to make it easier to get started using a library. See the
- documentation for 'ks prototype' for more information.`,
+ Long: `
+A ksonnet registry is basically a repository for *packages*. (Registry here is
+used in the same sense as a container image registry). Registries are identified
+by a ` + "`registry.yaml`" + ` in their root that declares which packages they contain.
+
+Specifically, registries contain a set of versioned packages that the user can
+install and manage in a given ksonnet app, using the CLI. A typical package contains:
+
+1. **A library definining a set of "parts"**. These are pre-fabricated API objects
+which can be combined together to configure a Kubernetes application for some task.
+(e.g. a Deployment, a Service, and a Secret, specifically tailored for Redis).
+
+2. **A set of "prototypes"**, which are pre-fabricated combinations of parts, as
+described above. (See ` + "`ks prototype --help`" + ` for more information.)
+
+----
+`,
}
var registryListCmd = &cobra.Command{
Use: "list",
- Short: `List all registries known to the current ksonnet app.`,
+ Short: regShortDesc["list"],
RunE: func(cmd *cobra.Command, args []string) error {
const (
nameHeader = "NAME"
@@ -89,11 +98,25 @@ var registryListCmd = &cobra.Command{
fmt.Print(formatted)
return nil
},
+ Long: `
+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` " + `— ` + regShortDesc["describe"] + `
+
+### Syntax
+`,
}
var registryDescribeCmd = &cobra.Command{
Use: "describe <registry-name>",
- Short: `Describe a ksonnet registry`,
+ Short: regShortDesc["describe"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("Command 'registry describe' takes one argument, which is the name of the registry to describe")
@@ -135,7 +158,7 @@ var registryDescribeCmd = &cobra.Command{
fmt.Println(`PROTOCOL:`)
fmt.Println(regRef.Protocol)
fmt.Println()
- fmt.Println(`LIBRARIES:`)
+ fmt.Println(`PACKAGES:`)
for _, lib := range reg.Libraries {
fmt.Printf(" %s\n", lib.Path)
@@ -144,6 +167,18 @@ var registryDescribeCmd = &cobra.Command{
return nil
},
- Long: `Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some` + " `registry-name`" + `.`,
+ Long: `
+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` " + `— ` + pkgShortDesc["install"] + `
+
+### Syntax
+`,
}
diff --git a/cmd/root.go b/cmd/root.go
index adeed59a417bd81bd893b4bc114afb6b4a062e6a..d4d06bd0e61e9509f5663c1776561b00d01a65a8 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -91,14 +91,20 @@ func bindJsonnetFlags(cmd *cobra.Command) {
func bindClientGoFlags(cmd *cobra.Command) {
kflags := clientcmd.RecommendedConfigOverrideFlags("")
ep := &loadingRules.ExplicitPath
- cmd.PersistentFlags().StringVar(ep, "kubeconfig", "", "Path to a kube config. Only required if out-of-cluster")
+ cmd.PersistentFlags().StringVar(ep, "kubeconfig", "", "Path to a kubeconfig file. Alternative to env var $KUBECONFIG.")
clientcmd.BindOverrideFlags(&overrides, cmd.PersistentFlags(), kflags)
}
// RootCmd is the root of cobra subcommand tree
var RootCmd = &cobra.Command{
- Use: "ks",
- Short: "Synchronise Kubernetes resources with config files",
+ Use: "ks",
+ Short: `Configure your application to deploy to a Kubernetes cluster`,
+ Long: `
+You can use the ` + "`ks`" + ` commands to write, share, and deploy your Kubernetes
+application configuration to remote clusters.
+
+----
+`,
SilenceErrors: true,
SilenceUsage: true,
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
diff --git a/cmd/show.go b/cmd/show.go
index 0d93209b16cf4975ef3bd08a3ac3f16870740f21..02ba75970fa366575c5f2f0493f5d6fecffe4186 100644
--- a/cmd/show.go
+++ b/cmd/show.go
@@ -26,7 +26,8 @@ import (
)
const (
- flagFormat = "format"
+ flagFormat = "format"
+ showShortDesc = "Show expanded manifests for a specific environment."
)
func init() {
@@ -38,18 +39,30 @@ func init() {
var showCmd = &cobra.Command{
Use: "show <env> [-c <component-filename>]",
- Short: "Show expanded manifests for a specific environment.",
- Long: `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>`" + `.
-
-When a component IS specified via the ` + "`-c`" + ` flag, this command only expands the manifest for that
-particular component.`,
- Example: `# Show all of the components for the 'dev' environment, in YAML
+ Short: showShortDesc,
+ Long: `
+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` " + `— ` + valShortDesc + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
+
+### Syntax
+`,
+ Example: `
+# Show all of the components for the 'dev' environment, in YAML
# (In other words, expands all manifests in the components/ directory)
ks show dev
diff --git a/cmd/validate.go b/cmd/validate.go
index 8c3074f4e7ac6dba7b157f5445cc4fd76f9909b8..3e629662928121ded981cb5589ac9c8691674b81 100644
--- a/cmd/validate.go
+++ b/cmd/validate.go
@@ -25,6 +25,10 @@ import (
"github.com/ksonnet/ksonnet/pkg/kubecfg"
)
+const (
+ valShortDesc = "Check generated component manifests against the server's API"
+)
+
func init() {
RootCmd.AddCommand(validateCmd)
addEnvCmdFlags(validateCmd)
@@ -33,8 +37,8 @@ func init() {
}
var validateCmd = &cobra.Command{
- Use: "validate [env-name] [-f <file-or-dir>]",
- Short: "Compare generated manifest against server OpenAPI spec",
+ Use: "validate <env-name> [-c <component-name>]",
+ Short: valShortDesc,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("'validate' requires an environment name; use `env list` to see available environments\n\n%s", cmd.UsageString())
@@ -69,24 +73,35 @@ var validateCmd = &cobra.Command{
return c.Run(objs, cmd.OutOrStdout())
},
- Long: `Validate that an application or file is compliant with the Kubernetes
-specification.
-
-ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
-files.`,
- Example: `# Validate all resources described in a ksonnet application, expanding
-# ksonnet code with 'dev' environment where necessary (i.e., not YAML, JSON,
-# or non-ksonnet Jsonnet code).
+ Long: `
+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` " + `— ` + showShortDesc + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
+
+### Syntax
+`,
+ Example: `
+# 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 described in a YAML file.
-ksonnet validate -f ./pod.yaml
-
-# Validate resources described in the JSON file against existing resources
-# in the cluster the 'dev' environment is pointing at.
-ksonnet validate dev -f ./pod.yaml
-
-# Validate resources described in a Jsonnet file. Does not expand using
-# environment bindings.
-ksonnet validate -f ./pod.jsonnet`,
+# 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
+`,
}
diff --git a/cmd/version.go b/cmd/version.go
index f7d88957e1953fbb43f76737071e2259198c4d34..190ba7234be9784c23e99e98864048533105c005 100644
--- a/cmd/version.go
+++ b/cmd/version.go
@@ -32,11 +32,17 @@ var Version = "(dev build)"
var versionCmd = &cobra.Command{
Use: "version",
- Short: "Print version information",
+ Short: "Print version information for this ksonnet binary",
Run: func(cmd *cobra.Command, args []string) {
out := cmd.OutOrStdout()
fmt.Fprintln(out, "ksonnet version:", Version)
fmt.Fprintln(out, "jsonnet version:", jsonnet.Version())
fmt.Fprintln(out, "client-go version:", version.Get())
},
+ Long: `
+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
+`,
}
diff --git a/docs/cli-reference/ks.md b/docs/cli-reference/ks.md
index ac08cbdc3491df4d5c7b8b33e2171158553324b6..043fd039b998372d8632c04efdc46614692c19d8 100644
--- a/docs/cli-reference/ks.md
+++ b/docs/cli-reference/ks.md
@@ -1,11 +1,16 @@
## ks
-Synchronise Kubernetes resources with config files
+Configure your application to deploy to a Kubernetes cluster
### Synopsis
-Synchronise Kubernetes resources with config files
+
+You can use the `ks` commands to write, share, and deploy your Kubernetes
+application configuration to remote clusters.
+
+----
+
### Options
@@ -14,17 +19,17 @@ Synchronise Kubernetes resources with config files
```
### SEE ALSO
-* [ks apply](ks_apply.md) - Apply local Kubernetes manifests to remote clusters
-* [ks delete](ks_delete.md) - Delete Kubernetes resources described in local config
-* [ks diff](ks_diff.md) - Display differences between server and local config, or server and server config
+* [ks apply](ks_apply.md) - Apply local Kubernetes manifests (components) to remote clusters
+* [ks delete](ks_delete.md) - Remove component-specified Kubernetes resources from remote clusters
+* [ks diff](ks_diff.md) - Compare manifests, based on environment or location (local or remote)
* [ks env](ks_env.md) - Manage ksonnet environments
* [ks generate](ks_generate.md) - Use the specified prototype to generate a component manifest
* [ks init](ks_init.md) - Initialize a ksonnet application
-* [ks param](ks_param.md) - Manage ksonnet component parameters
-* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet project
+* [ks param](ks_param.md) - Manage ksonnet parameters for components and environments
+* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet application
* [ks prototype](ks_prototype.md) - Instantiate, inspect, and get examples for ksonnet prototypes
* [ks registry](ks_registry.md) - Manage registries for current project
* [ks show](ks_show.md) - Show expanded manifests for a specific environment.
-* [ks validate](ks_validate.md) - Compare generated manifest against server OpenAPI spec
-* [ks version](ks_version.md) - Print version information
+* [ks validate](ks_validate.md) - Check generated component manifests against the server's API
+* [ks version](ks_version.md) - Print version information for this ksonnet binary
diff --git a/docs/cli-reference/ks_apply.md b/docs/cli-reference/ks_apply.md
index f777ebc7485974d9052b3e7ffcea1b1ab0ccf85b..a50c871cb02e11668df32745403e65e036d192ed 100644
--- a/docs/cli-reference/ks_apply.md
+++ b/docs/cli-reference/ks_apply.md
@@ -1,59 +1,64 @@
## ks apply
-Apply local Kubernetes manifests to remote clusters
+Apply local Kubernetes manifests (components) to remote clusters
### Synopsis
-Update (or optionally create) Kubernetes resources on the cluster using your
-local Kubernetes manifests. Use the `--create` flag to control whether
-they are created if they do not exist (default: true).
+The `apply`command 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 local Kubernetes manifests that are applied reside in your `components/`
-directory. When applied, the manifests are fully expanded using the paremeters
-of the specified environment.
+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 manifests are applied. To apply a subset of manifests, use the
-`--component` flag, as seen in the examples below.
+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 delete` — Delete the component manifests on your cluster
+* `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>
+ks apply <env-name> [-c <component-name>] [--dry-run]
```
### Examples
```
-# Create or update all resources described in a ksonnet application, and
-# running in the 'dev' environment. Can be used in any subdirectory of the
-# application.
+# 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 is equivalent to applying all components in the 'components/' directory.
+# This essentially deploys all components in the 'components/' directory.
ks apply dev
-# Create or update the single resource 'guestbook-ui' described in a ksonnet
-# application, and running in the 'dev' environment. Can be used in any
-# subdirectory of the application.
+# 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 is equivalent to applying the component with the same file name (excluding
-# the extension) 'guestbook-ui' in the 'components/' directory.
+# This essentially deploys 'components/guestbook-ui.jsonnet'.
ks apply dev -c guestbook-ui
-# Create or update the multiple resources, 'guestbook-ui' and 'nginx-depl'
-# described in a ksonnet application, and running in the 'dev' environment. Can
-# be used in any subdirectory of the application.
+# 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 is equivalent to applying the component with the same file name (excluding
-# the extension) 'guestbook-ui' and 'nginx-depl' in the 'components/' directory.
-ks apply dev -c guestbook-ui -c nginx-depl
+# This essentially deploys 'components/guestbook-ui.jsonnet' and
+# 'components/nginx-depl.jsonnet'.
+ks apply dev -c guestbook-ui -c nginx-depl --create false
```
@@ -67,21 +72,21 @@ ks apply dev -c guestbook-ui -c nginx-depl
--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 Create missing resources (default true)
- --dry-run Perform only read-only operations
+ --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 Add this tag to updated objects, and garbage collect existing objects with this tag and not in config
+ --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 kube config. Only required if out-of-cluster
+ --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 Don't perform garbage collection, even with --gc-tag
+ --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
@@ -96,5 +101,5 @@ ks apply dev -c guestbook-ui -c nginx-depl
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_delete.md b/docs/cli-reference/ks_delete.md
index 33c09135009c090a49a6a6e74aa98a2ea00a14be..577bd6e956a9c067f18a2f579bffd661655f6e70 100644
--- a/docs/cli-reference/ks_delete.md
+++ b/docs/cli-reference/ks_delete.md
@@ -1,38 +1,44 @@
## ks delete
-Delete Kubernetes resources described in local config
+Remove component-specified Kubernetes resources from remote clusters
### Synopsis
-Delete Kubernetes resources from a cluster, as described in the local
-configuration.
-ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
-files.
+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] [-f <file-or-dir>]
+ks delete [env-name] [-c <component-name>]
```
### Examples
```
-# Delete all resources described in a ksonnet application, from the 'dev'
-# environment. Can be used in any subdirectory of the application.
+# 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 in a YAML file. Automatically picks up the
-# cluster's location from '$KUBECONFIG'.
-ks delete -f ./pod.yaml
-
-# Delete resources described in the JSON file from the 'dev' environment. Can
-# be used in any subdirectory of the application.
-ks delete dev -f ./pod.json
-
-# Delete resources described in a YAML file, and running in the cluster
-# specified by the current context in specified kubeconfig file.
-ks delete --kubeconfig=./kubeconfig -f ./pod.yaml
+# 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
@@ -50,7 +56,7 @@ ks delete --kubeconfig=./kubeconfig -f ./pod.yaml
--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 kube config. Only required if out-of-cluster
+ --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")
@@ -71,5 +77,5 @@ ks delete --kubeconfig=./kubeconfig -f ./pod.yaml
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_diff.md b/docs/cli-reference/ks_diff.md
index c64fc0033e42b708351ac41b244ccaa1f9d6f302..70491f9989771c0aa157b8bad281121f4d0aba59 100644
--- a/docs/cli-reference/ks_diff.md
+++ b/docs/cli-reference/ks_diff.md
@@ -1,52 +1,67 @@
## ks diff
-Display differences between server and local config, or server and server config
+Compare manifests, based on environment or location (local or remote)
### Synopsis
-Display differences between server and local configuration, or server and server
-configurations.
-ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
-files.
+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 [<env1> [<env2>]] [-f <file-or-dir>]
+ks diff <location1:env1> [location2:env2] [-c <component-name>]
```
### Examples
```
-# Show diff between resources described in a the local 'dev' environment
-# specified by the ksonnet application and the remote cluster referenced by
-# the same 'dev' environment. Can be used in any subdirectory of the application.
-ksonnet diff dev
-
-# Show diff between resources at remote clusters. This requires ksonnet
-# application defined environments. Diff between the cluster defined at the
-# 'us-west/dev' environment, and the cluster defined at the 'us-west/prod'
-# environment. Can be used in any subdirectory of the application.
-ksonnet diff remote:us-west/dev remote:us-west/prod
-
-# Show diff between resources at a remote and a local cluster. This requires
-# ksonnet application defined environments. Diff between the cluster defined
-# at the 'us-west/dev' environment, and the cluster defined at the
-# 'us-west/prod' environment. Can be used in any subdirectory of the
-# application.
-ksonnet diff local:us-west/dev remote:us-west/prod
-
-# Show diff between resources described in a YAML file and the cluster
-# referenced in '$KUBECONFIG'.
-ks diff -f ./pod.yaml
-
-# Show diff between resources described in a JSON file and the cluster
-# referenced by the environment 'dev'.
-ks diff dev -f ./pod.json
-
-# Show diff between resources described in a YAML file and the cluster
-# referred to by './kubeconfig'.
-ks diff --kubeconfig=./kubeconfig -f ./pod.yaml
+
+# 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
@@ -70,5 +85,5 @@ ks diff --kubeconfig=./kubeconfig -f ./pod.yaml
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_env.md b/docs/cli-reference/ks_env.md
index 6d397b570323ebe245d05e952c5873f03d910919..77ee3628be2cfbe4acf85bb7ce5806561bd1f54a 100644
--- a/docs/cli-reference/ks_env.md
+++ b/docs/cli-reference/ks_env.md
@@ -5,40 +5,42 @@ Manage ksonnet environments
### Synopsis
-An environment acts as a sort of "named cluster", allowing for commands like
- `ks apply dev` , which applies the ksonnet application to the 'dev cluster'.
-Additionally, environments allow users to cache data about the cluster it points
-to, including data needed to run 'verify', and a version of ksonnet-lib that is
-generated based on the flags the API server was started with (e.g., RBAC enabled
-or not).
-
-An environment contains no user-specific data (such as the private key
-often contained in a kubeconfig file), and
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application. For example, in the example below, there are two
-environments: 'default' and 'us-west/staging'. Each contains a cached version of
- `ksonnet-lib` , and a `spec.json` that contains the server and server cert that
-uniquely identifies the cluster.
-
- environments/
- default/ [Default generated environment]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json
- default.jsonnet
- params.libsonnet
- us-west/
- staging/ [Example of user-generated env]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json [This will contain the API server address of the environment and other environment metadata]
- staging.jsonnet
- params.libsonnet
+
+An environment is a deployment target for your ksonnet app and its constituent
+components. You can use ksonnet to deploy a given app to *multiple* environments,
+such as `dev` and `prod`.
+
+Intuitively, an environment acts as a sort of "named cluster", similar to a
+Kubernetes context. (Running `ks env add --help` provides more detail
+about the fields that you need to create an environment).
+
+**All of this environment info is cached in local files**. Environments are
+represented as a hierarchy in the `environments/` directory of a ksonnet app, like
+'default' and 'us-west/staging' in the example below.
+
+```
+├── environments
+│ ├── base.libsonnet
+│ ├── default // Default generated environment ('ks init')
+│ │ ├── .metadata
+│ │ │ ├── k.libsonnet
+│ │ │ ├── k8s.libsonnet
+│ │ │ └── swagger.json
+│ │ ├── main.jsonnet
+│ │ ├── params.libsonnet
+│ │ └── spec.json
+│ └── us-west
+│ └── staging // Example of user-generated env ('ks env add')
+│ ├── .metadata
+│ │ ├── k.libsonnet // Jsonnet library with Kubernetes-compatible types and definitions
+│ │ ├── k8s.libsonnet
+│ │ └── swagger.json
+│ ├── main.libsonnet // Main file that imports all components (expanded on apply, delete, etc). Add environment-specific logic here.
+│ ├── params.libsonnet // Customize components *per-environment* here.
+│ └── spec.json // Contains the environment's API server address and namespace
+```
+----
+
```
ks env
@@ -54,7 +56,7 @@ ks env
--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 kube config. Only required if out-of-cluster
+ --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")
@@ -71,9 +73,9 @@ ks env
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
-* [ks env add](ks_env_add.md) - Add a new environment to a ksonnet project
-* [ks env list](ks_env_list.md) - List all environments in a ksonnet project
-* [ks env rm](ks_env_rm.md) - Delete an environment from a ksonnet project
-* [ks env set](ks_env_set.md) - Set environment fields such as the name, server, and namespace.
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
+* [ks env add](ks_env_add.md) - Add a new environment to a ksonnet application
+* [ks env list](ks_env_list.md) - List all environments in a ksonnet application
+* [ks env rm](ks_env_rm.md) - Delete an environment from a ksonnet application
+* [ks env set](ks_env_set.md) - Set environment-specific fields (name, namespace, server)
diff --git a/docs/cli-reference/ks_env_add.md b/docs/cli-reference/ks_env_add.md
index 5608089d1a7f8bb453df1b440fdf3961b158f527..d0d65d25ce946866bf7e8308b98778c1cef2b597 100644
--- a/docs/cli-reference/ks_env_add.md
+++ b/docs/cli-reference/ks_env_add.md
@@ -1,40 +1,37 @@
## ks env add
-Add a new environment to a ksonnet project
+Add a new environment to a ksonnet application
### Synopsis
-Add a new environment to a ksonnet project. Names are restricted to not
-include punctuation, so names like `../foo` are not allowed.
-
-An environment acts as a sort of "named cluster", allowing for commands like
- `ks apply dev` , which applies the ksonnet application to the "dev cluster".
-For more information on what an environment is and how they work, run `ks help env` .
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application, and hence `ks env add` will add to this directory structure.
-For example, in the example below, there are two environments: 'default' and
-'us-west/staging'. `ks env add` will add a similar directory to this environment.
-
- environments/
- default/ [Default generated environment]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json
- default.jsonnet
- params.libsonnet
- us-west/
- staging/ [Example of user-generated env]
- .metadata/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json [This will contain the API server address of the environment and other environment metadata],
- staging.jsonnet
- params.libsonnet
+
+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>
@@ -43,20 +40,27 @@ ks env add <env-name>
### Examples
```
-# Initialize a new staging environment at 'us-west'.
-# The environment will be setup using the current context in your kubecfg file. The directory
-# structure rooted at 'us-west' in the documentation above will be generated.
+
+# 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 staging environment at 'us-west' with the namespace 'staging', using
-# the OpenAPI specification generated in the Kubernetes v1.7.1 build to generate 'ksonnet-lib'.
+# 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 using the 'dev' context in your kubeconfig file.
+# 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 using a server address.
-ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com
+# 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
@@ -75,7 +79,7 @@ ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com
--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 kube config. Only required if out-of-cluster
+ --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")
diff --git a/docs/cli-reference/ks_env_list.md b/docs/cli-reference/ks_env_list.md
index 694c22b96585ae1c51f48acaa7dfc74c62264722..d06d0c7e0b9633b5d7764eaa4fefa871ea612526 100644
--- a/docs/cli-reference/ks_env_list.md
+++ b/docs/cli-reference/ks_env_list.md
@@ -1,12 +1,23 @@
## ks env list
-List all environments in a ksonnet project
+List all environments in a ksonnet application
### Synopsis
-List all environments in a ksonnet project. This will
-display the name, server, and namespace of each environment within the ksonnet project.
+
+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
@@ -22,7 +33,7 @@ ks env list
--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 kube config. Only required if out-of-cluster
+ --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")
diff --git a/docs/cli-reference/ks_env_rm.md b/docs/cli-reference/ks_env_rm.md
index 654a885814e986673036ed0d7065360835fb109a..1be73908b9877a479e0540217c9a53f8ff6d1c54 100644
--- a/docs/cli-reference/ks_env_rm.md
+++ b/docs/cli-reference/ks_env_rm.md
@@ -1,13 +1,27 @@
## ks env rm
-Delete an environment from a ksonnet project
+Delete an environment from a ksonnet application
### Synopsis
-Delete an environment from a ksonnet project. This is the same
-as removing the <env-name> environment directory and all files contained. All empty
-parent directories are also subsequently deleted.
+
+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>
@@ -16,8 +30,9 @@ ks env rm <env-name>
### Examples
```
-# Remove the directory 'us-west/staging' and all contents in the 'environments'
-# directory. This will also remove the parent directory 'us-west' if it is empty.
+
+# 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
```
@@ -31,7 +46,7 @@ ks env rm us-west/staging
--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 kube config. Only required if out-of-cluster
+ --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")
diff --git a/docs/cli-reference/ks_env_set.md b/docs/cli-reference/ks_env_set.md
index 3a4a4ff699b26e1ff734cd91fcdd16c274cc4b89..9999cc1a67e668a8528d37a4058918a71af410d1 100644
--- a/docs/cli-reference/ks_env_set.md
+++ b/docs/cli-reference/ks_env_set.md
@@ -1,13 +1,24 @@
## ks env set
-Set environment fields such as the name, server, and namespace.
+Set environment-specific fields (name, namespace, server)
### Synopsis
-Set environment fields such as the name, and server. Changing
-the name of an environment will also update the directory structure in
-'environments'.
+
+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>
@@ -16,25 +27,25 @@ ks env set <env-name>
### Examples
```
-# Updates the API server address of the environment 'us-west/staging'.
+# Update the API server address of the environment 'us-west/staging'.
ks env set us-west/staging --server=http://example.com
-# Updates the namespace of the environment 'us-west/staging'.
+# Update the namespace of the environment 'us-west/staging'.
ks env set us-west/staging --namespace=staging
-# Updates both the name and the server of the environment 'us-west/staging'.
-# Updating the name will update the directory structure in 'environments'.
+# 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
-
-# Updates API server address of the environment 'us-west/staging' based on the
-# server in the context 'staging-west' in your kubeconfig file.
+
+# 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 Specify name to rename environment to. Name must not already exist
+ --name string Name used to uniquely identify the environment. Must not already exist within the ksonnet app
```
### Options inherited from parent commands
@@ -47,7 +58,7 @@ ks env set us-west/staging --context=staging-west
--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 kube config. Only required if out-of-cluster
+ --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")
diff --git a/docs/cli-reference/ks_generate.md b/docs/cli-reference/ks_generate.md
index 993a18d446066400563e45378b817940a3ecbeb7..343622f35c5d3f447da37e95ba76071c5e736f9f 100644
--- a/docs/cli-reference/ks_generate.md
+++ b/docs/cli-reference/ks_generate.md
@@ -32,8 +32,9 @@ different prototypes support their own unique flags.
### Related Commands
-* `ks apply` — Apply your component manifests to a cluster
-* `ks param set` — Change the values you specified when generating the component
+* `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
@@ -49,5 +50,5 @@ ks generate <prototype-name> <component-name> [type] [parameter-flags]
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_init.md b/docs/cli-reference/ks_init.md
index 3f1a2597b6f7e9404dc8fdc72ba947300c354a81..e14fae007dfc6c0f6f429a3d501991e40bec147c 100644
--- a/docs/cli-reference/ks_init.md
+++ b/docs/cli-reference/ks_init.md
@@ -5,34 +5,42 @@ Initialize a ksonnet application
### Synopsis
-Initialize a ksonnet application in a new directory, `app-name`.
+
+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 your 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, ex: name, api version
+ 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/ part libraries, prototypes
+ 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] Each environment uses a specific version of ksonnet-lib. Users can set flags
-to generate the library based on a variety of data, including server
-configuration and an OpenAPI specification of a Kubernetes build. By default,
-this is generated from the capabilities of the cluster specified in the cluster
-of the current context specified in `$KUBECONFIG`.
+[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
```
@@ -43,19 +51,19 @@ ks init <app-name> [flags]
```
# Initialize a ksonnet application, based on cluster information from the
-# active kubeconfig file (specified by the environment variable $KUBECONFIG).
+# 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). This initializes the default environment
-# using the server address and default namespace located at the context 'dev'.
+# 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). This initializes
-# the default environment using the server address at the context 'dev' for
-# the namespace 'dc-west'.
+# '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
@@ -66,15 +74,15 @@ ks init app-name --api-spec=version:v1.7.1
# specific build of Kubernetes to generate 'ksonnet-lib'.
ks init app-name --api-spec=file:swagger.json
-# Initialize a ksonnet application, using a custom location for the application
-# directory.
+# 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 specify API version from OpenAPI schema, cluster, or Kubernetes version (default "version:v1.7.0")
+ --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
@@ -83,7 +91,7 @@ ks init app-name --dir=custom-location
--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 kube config. Only required if out-of-cluster
+ --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")
@@ -100,5 +108,5 @@ ks init app-name --dir=custom-location
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_param.md b/docs/cli-reference/ks_param.md
index 242a1108b081fd71bdda89b2e7f88983f95edaba..a7375e22270d9ea33231a5cd20c8dcacaacae99e 100644
--- a/docs/cli-reference/ks_param.md
+++ b/docs/cli-reference/ks_param.md
@@ -1,23 +1,38 @@
## ks param
-Manage ksonnet component parameters
+Manage ksonnet parameters for components and environments
### Synopsis
-Parameters are the customizable fields defining ksonnet components. For
-example, replica count, component name, or deployment image.
-Parameters are also able to be defined separately across environments. Meaning,
-this supports features to allow a "development" environment to only run a
-single replication instance for it's components, whereas allowing a "production"
-environment to run more replication instances to meet heavier production load
-demands.
+Parameters are customizable fields that are used inside ksonnet *component*
+manifests. Examples might include a deployment's 'name' or 'image'. Parameters
+can also be defined on a *per-environment* basis. (Environments are ksonnet
+deployment targets, e.g. specific clusters. For more info, run `ks env --help`.)
-Environments are ksonnet "named clusters". For more information on environments,
-run:
+For example, this allows a `dev` and `prod` environment to use the same component
+manifest for an nginx deployment, but customize `prod` to use more replicas to meet
+heavier load demands.
- ks env --help
+Params are structured as follows:
+
+* App params (stored in `components/params.libsonnet`)
+ * Component-specific params
+ * Originally populated from `ks generate`
+ * e.g. 80 for `deployment-example.port`
+ * Global params
+ * Out of scope for CLI (requires Jsonnet editing)
+ * Use to make a variable accessible to multiple components (e.g. service name)
+
+* Per-environment params (stored in + `environments/<env-name>/params.libsonnet`)
+ * Component-specific params ONLY
+ * Override app params (~inheritance)
+
+Note that all of these params are tracked **locally** in version-controllable
+Jsonnet files.
+
+----
```
@@ -31,8 +46,8 @@ ks param
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
* [ks param diff](ks_param_diff.md) - Display differences between the component parameters of two environments
-* [ks param list](ks_param_list.md) - List all parameters for a component(s)
-* [ks param set](ks_param_set.md) - Set component or environment parameters such as replica count or name
+* [ks param list](ks_param_list.md) - List known component parameters
+* [ks param set](ks_param_set.md) - Change component or environment parameters (e.g. replica count, name)
diff --git a/docs/cli-reference/ks_param_diff.md b/docs/cli-reference/ks_param_diff.md
index 541721c2541cec84cafbe7dad3f938a1cb2d71ec..d1e0355b3699785bef4389b4bc58f0dd5be0740d 100644
--- a/docs/cli-reference/ks_param_diff.md
+++ b/docs/cli-reference/ks_param_diff.md
@@ -5,23 +5,34 @@ Display differences between the component parameters of two environments
### Synopsis
-Pretty prints differences between the component parameters of two environments.
-A component flag is accepted to diff against a single component. By default, the
-diff is performed against all components.
+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>
+ks param diff <env1> <env2> [--component <component-name>]
```
### Examples
```
-# Diff between the component parameters on environments 'dev' and 'prod'
+
+# Diff between all component parameters for environments 'dev' and 'prod'
ks param diff dev prod
-# Diff between the component 'guestbook' on environments 'dev' and 'prod'
+# Diff only between the parameters for the 'guestbook' component for environments
+# 'dev' and 'prod'
ks param diff dev prod --component=guestbook
```
@@ -38,5 +49,5 @@ ks param diff dev prod --component=guestbook
```
### SEE ALSO
-* [ks param](ks_param.md) - Manage ksonnet component parameters
+* [ks param](ks_param.md) - Manage ksonnet parameters for components and environments
diff --git a/docs/cli-reference/ks_param_list.md b/docs/cli-reference/ks_param_list.md
index 59e88337d450aa015fbe3bc3473cac92c5d4a1e0..e72da2b95ba2d128fe2f24308f5c752bd402d9e1 100644
--- a/docs/cli-reference/ks_param_list.md
+++ b/docs/cli-reference/ks_param_list.md
@@ -1,25 +1,32 @@
## ks param list
-List all parameters for a component(s)
+List known component parameters
### Synopsis
-List all component parameters or environment parameters.
-This command will display all parameters for the component specified. If a
-component is not specified, parameters for all components will be listed.
+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>
+ks param list [<component-name>] [--env <env-name>]
```
### Examples
```
+
# List all component parameters
ks param list
@@ -46,5 +53,5 @@ ks param list guestbook --env=dev
```
### SEE ALSO
-* [ks param](ks_param.md) - Manage ksonnet component parameters
+* [ks param](ks_param.md) - Manage ksonnet parameters for components and environments
diff --git a/docs/cli-reference/ks_param_set.md b/docs/cli-reference/ks_param_set.md
index 4a187db0d0eada7354f9dab83a7ed40cb06d2800..04a3ba55dd581d46f9dd89d5d6dcb45bb3893eb5 100644
--- a/docs/cli-reference/ks_param_set.md
+++ b/docs/cli-reference/ks_param_set.md
@@ -1,17 +1,28 @@
## ks param set
-Set component or environment parameters such as replica count or name
+Change component or environment parameters (e.g. replica count, name)
### Synopsis
-Set component or environment parameters such as replica count or name.
-Parameters are set individually, one at a time. If you require customization of
-more fields, we suggest that you modify your ksonnet project's
- `components/params.libsonnet` file directly. Likewise, for greater customization
-of environment parameters, we suggest modifying the
- `environments/:name/params.libsonnet` file.
+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
```
@@ -21,11 +32,12 @@ ks param set <component-name> <param-key> <param-value>
### Examples
```
-# Updates the replica count of the 'guestbook' component to 4.
+
+# Update the replica count of the 'guestbook' component to 4.
ks param set guestbook replicas 4
-# Updates the replica count of the 'guestbook' component to 2 for the environment
-# 'dev'
+# Update the replica count of the 'guestbook' component to 2, but only for the
+# 'dev' environment
ks param set guestbook replicas 2 --env=dev
```
@@ -42,5 +54,5 @@ ks param set guestbook replicas 2 --env=dev
```
### SEE ALSO
-* [ks param](ks_param.md) - Manage ksonnet component parameters
+* [ks param](ks_param.md) - Manage ksonnet parameters for components and environments
diff --git a/docs/cli-reference/ks_pkg.md b/docs/cli-reference/ks_pkg.md
index c2831f488926baef29a229f910256c94f8384ffd..f32c03907bcb8e9698a8f25c9c3bd7cf4a7e38ab 100644
--- a/docs/cli-reference/ks_pkg.md
+++ b/docs/cli-reference/ks_pkg.md
@@ -1,11 +1,36 @@
## ks pkg
-Manage packages and dependencies for the current ksonnet project
+Manage packages and dependencies for the current ksonnet application
### Synopsis
-Manage packages and dependencies for the current ksonnet project
+
+A ksonnet package contains:
+
+* A set of prototypes (see `ks prototype --help` for more info on prototypes), which
+generate similar types of components (e.g. `redis-stateless`, `redis-persistent`)
+* Associated helper libraries that define the prototype parts (e.g. `redis.libsonnet`)
+
+Packages allow you to easily distribute and reuse code in any ksonnet application.
+Packages come from registries, such as Github repositories. (For more info, see
+`ks registry --help`).
+
+To be recognized and imported by ksonnet, packages need to follow a specific schema.
+See the annotated file tree below, as an example:
+
+```
+.
+├── README.md // Human-readable description of the package
+├── parts.yaml // Provides metadata about the package
+├── prototypes // Can be imported and used to generate components
+│ ├── redis-all-features.jsonnet
+│ ├── redis-persistent.jsonnet
+│ └── redis-stateless.jsonnet
+└── redis.libsonnet // Helper library, includes prototype parts
+```
+---
+
```
ks pkg
@@ -18,8 +43,8 @@ ks pkg
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
-* [ks pkg describe](ks_pkg_describe.md) - Describe a ksonnet package
-* [ks pkg install](ks_pkg_install.md) - Install a package as a dependency in the current ksonnet application
-* [ks pkg list](ks_pkg_list.md) - Lists information about all dependencies known to the current ksonnet app
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
+* [ks pkg describe](ks_pkg_describe.md) - Describe a ksonnet package and its contents
+* [ks pkg install](ks_pkg_install.md) - Install a package (e.g. extra prototypes) for the current ksonnet app
+* [ks pkg list](ks_pkg_list.md) - List all packages known (downloaded or not) for the current ksonnet app
diff --git a/docs/cli-reference/ks_pkg_describe.md b/docs/cli-reference/ks_pkg_describe.md
index 514d16a2a5552be97674f3f0b741f69090076521..72df9ce17dd8db9571550d7b1fc6a013be5c81be 100644
--- a/docs/cli-reference/ks_pkg_describe.md
+++ b/docs/cli-reference/ks_pkg_describe.md
@@ -1,12 +1,27 @@
## ks pkg describe
-Describe a ksonnet package
+Describe a ksonnet package and its contents
### Synopsis
-Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some 'registry-name'.
+
+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>
@@ -19,5 +34,5 @@ ks pkg describe [<registry-name>/]<package-name>
```
### SEE ALSO
-* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet application
diff --git a/docs/cli-reference/ks_pkg_install.md b/docs/cli-reference/ks_pkg_install.md
index 1eddae63e0facb1a1b8f37178dc54f858282f3f4..a674b4aa3575a7b27d027c6d49fc34dbc2af98f2 100644
--- a/docs/cli-reference/ks_pkg_install.md
+++ b/docs/cli-reference/ks_pkg_install.md
@@ -1,44 +1,47 @@
## ks pkg install
-Install a package as a dependency in the current ksonnet application
+Install a package (e.g. extra prototypes) for the current ksonnet app
### Synopsis
-Cache a ksonnet library locally, and make it available for use in the current
-ksonnet project. This particularly means that we record enough information in
- `app.yaml` for new users to retrieve the dependency after a fresh clone of the
-app repository.
-For example, inside a ksonnet application directory, run:
+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.
- ks pkg install incubator/nginx@v0.1
+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.
-This can then be referenced in a source file in the ksonnet project:
+### Related Commands
- local nginx = import "kspkg://nginx";
+* `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
-By default, ksonnet knows about two registries: incubator and stable, which are
-the release channels for official ksonnet libraries. Additional registries can
-be added with the `ks registry` command.
+### Syntax
-Note that multiple versions of the same ksonnet library can be cached and used
-in the same project, by explicitly passing in the `--name` flag. For example:
- ks pkg install incubator/nginx@v0.1 --name nginxv1
- ks pkg install incubator/nginx@v0.2 --name nginxv2
+```
+ks pkg install <registry>/<library>@<version>
+```
-With these commands, a user can `import "kspkg://nginxv1"` , and
- `import "kspkg://nginxv2"` with no conflict.
+### Examples
```
-ks pkg install <registry>/<library>@<version>
+
+# 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
+ --name string Name to give the dependency, to use within the ksonnet app
```
### Options inherited from parent commands
@@ -48,5 +51,5 @@ ks pkg install <registry>/<library>@<version>
```
### SEE ALSO
-* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet application
diff --git a/docs/cli-reference/ks_pkg_list.md b/docs/cli-reference/ks_pkg_list.md
index 351de4da75dfb3cb1f8a46d2e51a7cb603c0e4cf..3f490f57cceb10b7e2a105437d52b4e83b0498a2 100644
--- a/docs/cli-reference/ks_pkg_list.md
+++ b/docs/cli-reference/ks_pkg_list.md
@@ -1,11 +1,27 @@
## ks pkg list
-Lists information about all dependencies known to the current ksonnet app
+List all packages known (downloaded or not) for the current ksonnet app
### Synopsis
-Lists information about all dependencies known to 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:
+
+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
@@ -18,5 +34,5 @@ ks pkg list
```
### SEE ALSO
-* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet application
diff --git a/docs/cli-reference/ks_prototype.md b/docs/cli-reference/ks_prototype.md
index d9d53fca33a495184e878f644278e1c4898296be..ff42110e9c320a91bdcd4b4de6b63684f6dd6300 100644
--- a/docs/cli-reference/ks_prototype.md
+++ b/docs/cli-reference/ks_prototype.md
@@ -19,6 +19,8 @@ words, prototypes provide the basis for the **components** of your app. You can
use prototypes to autogenerate boilerplate code and focus on customizing them
for your use case.
+----
+
```
ks prototype
@@ -31,7 +33,7 @@ ks prototype
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
* [ks prototype describe](ks_prototype_describe.md) - See more info about a prototype's output and usage
* [ks prototype list](ks_prototype_list.md) - List all locally available ksonnet prototypes
* [ks prototype preview](ks_prototype_preview.md) - Preview a prototype's output without creating a component (stdout)
diff --git a/docs/cli-reference/ks_prototype_list.md b/docs/cli-reference/ks_prototype_list.md
index 5866b2370fe872adf9c2bf79de7f909408fc63d2..85b78a201993d2017c1fc74423b4d69162dc0bb2 100644
--- a/docs/cli-reference/ks_prototype_list.md
+++ b/docs/cli-reference/ks_prototype_list.md
@@ -19,7 +19,7 @@ from the *incubator* registry.
* `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 more prototypes (from external packages)
+* `ks pkg install` Install a package (e.g. extra prototypes) for the current ksonnet app
### Syntax
diff --git a/docs/cli-reference/ks_prototype_use.md b/docs/cli-reference/ks_prototype_use.md
index 49de3946d40b89fed7565b9862fa81c476574284..c255539e1930fafae59843cc4b74278dc0e31894 100644
--- a/docs/cli-reference/ks_prototype_use.md
+++ b/docs/cli-reference/ks_prototype_use.md
@@ -32,8 +32,9 @@ different prototypes support their own unique flags.
### Related Commands
-* `ks apply` — Apply your component manifests to a cluster
-* `ks param set` — Change the values you specified when generating the component
+* `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
diff --git a/docs/cli-reference/ks_registry.md b/docs/cli-reference/ks_registry.md
index 58a1a241a0badd4c89709adc0335bcf9dd2ef7cd..1cc2cba2c56383dd1c57eb2f809e247d7c7bf518 100644
--- a/docs/cli-reference/ks_registry.md
+++ b/docs/cli-reference/ks_registry.md
@@ -5,19 +5,23 @@ Manage registries for current project
### Synopsis
-Manage and inspect ksonnet registries.
-Registries contain a set of versioned libraries that the user can install and
-manage in a ksonnet project using the CLI. A typical library contains:
+A ksonnet registry is basically a repository for *packages*. (Registry here is
+used in the same sense as a container image registry). Registries are identified
+by a `registry.yaml` in their root that declares which packages they contain.
+
+Specifically, registries contain a set of versioned packages that the user can
+install and manage in a given ksonnet app, using the CLI. A typical package contains:
+
+1. **A library definining a set of "parts"**. These are pre-fabricated API objects
+which can be combined together to configure a Kubernetes application for some task.
+(e.g. a Deployment, a Service, and a Secret, specifically tailored for Redis).
+
+2. **A set of "prototypes"**, which are pre-fabricated combinations of parts, as
+described above. (See `ks prototype --help` for more information.)
+
+----
- 1. A set of "parts", pre-fabricated API objects which can be combined together
- to configure a Kubernetes application for some task. For example, the Redis
- library may contain a Deployment, a Service, a Secret, and a
- PersistentVolumeClaim, but if the user is operating it as a cache, they may
- only need the first three of these.
- 2. A set of "prototypes", which are pre-fabricated combinations of these
- parts, made to make it easier to get started using a library. See the
- documentation for 'ks prototype' for more information.
```
ks registry
@@ -30,7 +34,7 @@ ks registry
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
-* [ks registry describe](ks_registry_describe.md) - Describe a ksonnet registry
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
+* [ks registry describe](ks_registry_describe.md) - Describe a ksonnet registry and the packages it contains
* [ks registry list](ks_registry_list.md) - List all registries known to the current ksonnet app.
diff --git a/docs/cli-reference/ks_registry_describe.md b/docs/cli-reference/ks_registry_describe.md
index a822f6b7fa92f52189eefa3cf5a7812584db5fff..bc9c0e971b99696b8c20ae40d1ab57318e1b959f 100644
--- a/docs/cli-reference/ks_registry_describe.md
+++ b/docs/cli-reference/ks_registry_describe.md
@@ -1,12 +1,24 @@
## ks registry describe
-Describe a ksonnet registry
+Describe a ksonnet registry and the packages it contains
### Synopsis
-Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some `registry-name`.
+
+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>
diff --git a/docs/cli-reference/ks_registry_list.md b/docs/cli-reference/ks_registry_list.md
index 75e9e2d47393c230ddf3c3df6f933f8ececc59d6..85bf64df23c15d58c94fcbccefd13ee5caf6c4b3 100644
--- a/docs/cli-reference/ks_registry_list.md
+++ b/docs/cli-reference/ks_registry_list.md
@@ -5,7 +5,20 @@ List all registries known to the current ksonnet app.
### Synopsis
-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:
+
+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
diff --git a/docs/cli-reference/ks_show.md b/docs/cli-reference/ks_show.md
index 508b7efd4d6c1de23e9d706278661217d1db14f6..252de9a741e0434931c249520ea0b0bd4a569454 100644
--- a/docs/cli-reference/ks_show.md
+++ b/docs/cli-reference/ks_show.md
@@ -5,15 +5,27 @@ 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>`.
+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
-When a component IS specified via the `-c` flag, this command only expands the manifest for that
-particular component.
```
ks show <env> [-c <component-filename>]
@@ -22,6 +34,7 @@ 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
@@ -55,5 +68,5 @@ ks show dev -c redis -c nginx-server
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_validate.md b/docs/cli-reference/ks_validate.md
index bdc9cf63a02917b89c4b2906859a1b503ff4080e..cc71c47e1dca84c95c95c1c60d5dbb76039a5aeb 100644
--- a/docs/cli-reference/ks_validate.md
+++ b/docs/cli-reference/ks_validate.md
@@ -1,38 +1,49 @@
## ks validate
-Compare generated manifest against server OpenAPI spec
+Check generated component manifests against the server's API
### Synopsis
-Validate that an application or file is compliant with the Kubernetes
-specification.
-ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
-files.
+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] [-f <file-or-dir>]
+ks validate <env-name> [-c <component-name>]
```
### Examples
```
-# Validate all resources described in a ksonnet application, expanding
-# ksonnet code with 'dev' environment where necessary (i.e., not YAML, JSON,
-# or non-ksonnet Jsonnet code).
-ksonnet validate dev
-# Validate resources described in a YAML file.
-ksonnet validate -f ./pod.yaml
+# 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 described in the JSON file against existing resources
-# in the cluster the 'dev' environment is pointing at.
-ksonnet validate dev -f ./pod.yaml
+# 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
-# Validate resources described in a Jsonnet file. Does not expand using
-# environment bindings.
-ksonnet validate -f ./pod.jsonnet
```
### Options
@@ -49,7 +60,7 @@ ksonnet validate -f ./pod.jsonnet
--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 kube config. Only required if out-of-cluster
+ --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")
@@ -70,5 +81,5 @@ ksonnet validate -f ./pod.jsonnet
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster
diff --git a/docs/cli-reference/ks_version.md b/docs/cli-reference/ks_version.md
index c7dbb600dbed9df5a81891d5a942173addc3552d..ced07b4f6cb0c603cb459c03e6314045654098b7 100644
--- a/docs/cli-reference/ks_version.md
+++ b/docs/cli-reference/ks_version.md
@@ -1,11 +1,16 @@
## ks version
-Print version information
+Print version information for this ksonnet binary
### Synopsis
-Print version information
+
+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
@@ -18,5 +23,5 @@ ks version
```
### SEE ALSO
-* [ks](ks.md) - Synchronise Kubernetes resources with config files
+* [ks](ks.md) - Configure your application to deploy to a Kubernetes cluster