edit apply and add delete

Signed-off-by: Jessica Yao <jessica@heptio.com>

cmd/apply.go

@@ -47,21 +47,23 @@ const (
 	GcStrategyIgnore = "ignore"
 )
 
+var applyShortDesc = `Apply local Kubernetes manifests (components) to remote clusters`
+
 func init() {
 	RootCmd.AddCommand(applyCmd)
 
 	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` " + `— Compare manifests, based on environment or location (local or remote)
+* ` + "`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
 `,
 }

cmd/delete.go

@@ -37,9 +37,11 @@ func init() {
 	deleteCmd.PersistentFlags().Int64(flagGracePeriod, -1, "Number of seconds given to resources to terminate gracefully. A negative value is ignored")
 }
 
+var deleteShortDesc = `Remove component-specified Kubernetes resources from remote clusters`
+
 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 +86,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 from a cluster, as described
+in local *component* manifests. 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`,
 }

cmd/env.go

@@ -165,7 +165,7 @@ Note that an environment *DOES NOT* contain user-specific data such as private k
 
 * ` + "`ks env list` " + `— ` + protoShortDesc["list"] + `
 * ` + "`ks param set` " + `— ` + `Change the values of an existing component` + `
-* ` + "`ks apply` " + `— ` + `Apply your component manifests to a cluster` + `
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
 
 ### Syntax
 `,

cmd/prototype.go

@@ -454,7 +454,7 @@ different prototypes support their own unique flags.
 
 ### Related Commands
 
-* ` + "`ks apply` " + `— Apply your component manifests to a cluster
+* ` + "`ks apply` " + `— ` + applyShortDesc + `
 * ` + "`ks param set` " + `— Change the values of an existing component
 
 ### Syntax

docs/cli-reference/ks.md

@@ -14,8 +14,8 @@ 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 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)	 - Display differences between server and local config, or server and server config
 * [ks env](ks_env.md)	 - Manage ksonnet environments
 * [ks generate](ks_generate.md)	 - Use the specified prototype to generate a component manifest

docs/cli-reference/ks_apply.md

 ## 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,11 +72,11 @@ 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
@@ -81,7 +86,7 @@ ks apply dev -c guestbook-ui -c nginx-depl
       --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

docs/cli-reference/ks_delete.md

 ## 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 from a cluster, as described
+in local *component* manifests. 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

docs/cli-reference/ks_env_add.md

@@ -25,7 +25,7 @@ Note that an environment *DOES NOT* contain user-specific data such as private k
 
 * `ks env list` — List all locally available ksonnet prototypes
 * `ks param set` — Change the values of an existing component
-* `ks apply` — Apply your component manifests to a cluster
+* `ks apply` — Apply local Kubernetes manifests (components) to remote clusters
 
 ### Syntax
 

docs/cli-reference/ks_generate.md

@@ -32,7 +32,7 @@ different prototypes support their own unique flags.
 
 ### Related Commands
 
-* `ks apply` — Apply your component manifests to a cluster
+* `ks apply` — Apply local Kubernetes manifests (components) to remote clusters
 * `ks param set` — Change the values of an existing component
 
 ### Syntax

docs/cli-reference/ks_prototype_use.md

@@ -32,7 +32,7 @@ different prototypes support their own unique flags.
 
 ### Related Commands
 
-* `ks apply` — Apply your component manifests to a cluster
+* `ks apply` — Apply local Kubernetes manifests (components) to remote clusters
 * `ks param set` — Change the values of an existing component
 
 ### Syntax