From 76a43a72e134a80809c8eb1060727e2093f86278 Mon Sep 17 00:00:00 2001
From: Jessica Yao <jessica@heptio.com>
Date: Wed, 29 Nov 2017 22:18:59 -0800
Subject: [PATCH] edit apply and add delete
Signed-off-by: Jessica Yao <jessica@heptio.com>
---
cmd/apply.go | 67 ++++++++++++++------------
cmd/delete.go | 44 ++++++++++-------
cmd/env.go | 2 +-
cmd/prototype.go | 2 +-
docs/cli-reference/ks.md | 4 +-
docs/cli-reference/ks_apply.md | 65 +++++++++++++------------
docs/cli-reference/ks_delete.md | 44 +++++++++--------
docs/cli-reference/ks_env_add.md | 2 +-
docs/cli-reference/ks_generate.md | 2 +-
docs/cli-reference/ks_prototype_use.md | 2 +-
10 files changed, 130 insertions(+), 104 deletions(-)
diff --git a/cmd/apply.go b/cmd/apply.go
index 9d9405bd..b51f8d89 100644
--- a/cmd/apply.go
+++ b/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
`,
}
diff --git a/cmd/delete.go b/cmd/delete.go
index 59eef3fc..62d12641 100644
--- a/cmd/delete.go
+++ b/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`,
}
diff --git a/cmd/env.go b/cmd/env.go
index 566b7367..163f9ce1 100644
--- a/cmd/env.go
+++ b/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
`,
diff --git a/cmd/prototype.go b/cmd/prototype.go
index 169218cf..e54159a5 100644
--- a/cmd/prototype.go
+++ b/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
diff --git a/docs/cli-reference/ks.md b/docs/cli-reference/ks.md
index ac08cbdc..44d108cf 100644
--- a/docs/cli-reference/ks.md
+++ b/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
diff --git a/docs/cli-reference/ks_apply.md b/docs/cli-reference/ks_apply.md
index f777ebc7..f168444c 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,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
diff --git a/docs/cli-reference/ks_delete.md b/docs/cli-reference/ks_delete.md
index 33c09135..117c9b26 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 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
diff --git a/docs/cli-reference/ks_env_add.md b/docs/cli-reference/ks_env_add.md
index 2bb38657..bc2351e4 100644
--- a/docs/cli-reference/ks_env_add.md
+++ b/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
diff --git a/docs/cli-reference/ks_generate.md b/docs/cli-reference/ks_generate.md
index 681eba5d..5437bf34 100644
--- a/docs/cli-reference/ks_generate.md
+++ b/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
diff --git a/docs/cli-reference/ks_prototype_use.md b/docs/cli-reference/ks_prototype_use.md
index 32365e74..32c00958 100644
--- a/docs/cli-reference/ks_prototype_use.md
+++ b/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
--
GitLab