From 9e9ba8739560f9b92b2946eb0e173d1d75c79323 Mon Sep 17 00:00:00 2001
From: Alex Clemmer <clemmer.alexander@gmail.com>
Date: Mon, 18 Sep 2017 17:53:49 -0700
Subject: [PATCH] Add to 'env' command documentation
Fixes #139.
---
cmd/env.go | 102 +++++++++++++++++++++++++++++++++++------------------
1 file changed, 67 insertions(+), 35 deletions(-)
diff --git a/cmd/env.go b/cmd/env.go
index 04b6ac65..adeec29b 100644
--- a/cmd/env.go
+++ b/cmd/env.go
@@ -49,7 +49,35 @@ func init() {
var envCmd = &cobra.Command{
Use: "env",
- Short: `Create, remove, modify, and list ksonnet environments`,
+ Short: `Manage ksonnet environments`,
+ Long: `An environment acts as a sort of "named cluster", allowing for commands like
+'ksonnet 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 URI and server cert that
+uniquely identifies the cluster.
+
+environments/
+ default/ [Default generated environment]
+ k.libsonnet
+ k8s.libsonnet
+ swagger.json
+ spec.json
+ us-west/
+ staging/ [Example of user-generated env]
+ k.libsonnet
+ k8s.libsonnet
+ swagger.json
+ spec.json [This will contain the uri of the environment]`,
RunE: func(cmd *cobra.Command, args []string) error {
return fmt.Errorf("Command 'env' requires a subcommand\n\n%s", cmd.UsageString())
},
@@ -57,7 +85,7 @@ var envCmd = &cobra.Command{
var envAddCmd = &cobra.Command{
Use: "add <env-name> <env-uri>",
- Short: "Add a new environment within a ksonnet project",
+ Short: "Add a new environment to a ksonnet project",
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 2 {
@@ -85,28 +113,32 @@ var envAddCmd = &cobra.Command{
return c.Run()
},
- Long: `Create a new environment within a ksonnet project. This will
-generate a new directory, 'env-name', within the 'environmentss' directory,
-containing the environment-specific files. 'env-uri' is the URI which the
-Kubernete's cluster is located for the added environment.
-
-Below is an example directory structure:
-
- app-name/
- .gitignore Default .gitignore; can customize VCS
- .ksonnet/ Metadata for ksonnet
- environments/ Env specs (defaults: dev, test, prod)
- default/ [Default generated environment]
- us-west/ [Example of user-generated env]
- staging/
- k.libsonnet
- k8s.libsonnet
- swagger.json
- spec.json [This will contain the uri of the environment]
- components/ Top-level Kubernetes objects defining application
- lib/ user-written .libsonnet files
- vendor/ mixin libraries, prototypes
-`,
+
+ 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
+'ksonnet apply dev', which applies the ksonnet application to the "dev cluster".
+For more information on what an environment is and how they work, run 'help
+env'.
+
+Environments are represented as a hierarchy in the 'environments' directory of a
+ksonnet application, and hence 'env add' will add to this directory structure.
+For example, in the example below, there are two environments: 'default' and
+'us-west/staging'. 'env add' will add a similar directory to this environment.
+
+environments/
+ default/ [Default generated environment]
+ k.libsonnet
+ k8s.libsonnet
+ swagger.json
+ spec.json
+ us-west/
+ staging/ [Example of user-generated env]
+ k.libsonnet
+ k8s.libsonnet
+ swagger.json
+ spec.json [This will contain the uri of the environment]`,
Example: ` # Initialize a new staging environment at us-west. The directory
# structure rooted at 'us-west' in the documentation above will be generated.
ksonnet env add us-west/staging https://kubecfg-1.us-west.elb.amazonaws.com
@@ -122,7 +154,7 @@ Below is an example directory structure:
var envRmCmd = &cobra.Command{
Use: "rm <env-name>",
- Short: "Delete an environment within a ksonnet project",
+ Short: "Delete an environment from a ksonnet project",
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")
@@ -143,11 +175,13 @@ var envRmCmd = &cobra.Command{
return c.Run()
},
- Long: `Delete an environment within a ksonnet project. This is the same
-as removing the <env-name> environment directory and all files contained.
-Empty parent directories will also be removed.
-`,
- Example: ` # Remove the directory 'us-west/staging' and all contents
+ Long: `Delete an environment from a ksonnet project. This is the same
+as removing the <env-name> environment directory and all files contained. If the
+project exists in a hierarchy (e.g., 'us-east/staging') and deleting the
+environment results in an empty environments directory (e.g., if deleting
+'us-east/staging' resulted in an empty 'us-east/' directory), then all empty
+parent directories are 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.
ksonnet env rm us-west/staging`,
@@ -155,7 +189,7 @@ Empty parent directories will also be removed.
var envListCmd = &cobra.Command{
Use: "list",
- Short: "List all environments within a ksonnet project",
+ Short: "List all environments in a ksonnet project",
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
return fmt.Errorf("'env list' takes zero arguments")
@@ -173,8 +207,7 @@ var envListCmd = &cobra.Command{
}
return c.Run(cmd.OutOrStdout())
- },
- Long: `List all environments within a ksonnet project. This will
+ }, Long: `List all environments in a ksonnet project. This will
display the name and the URI of each environment within the ksonnet project.`,
}
@@ -214,8 +247,7 @@ var envSetCmd = &cobra.Command{
},
Long: `Set environment fields such as the name, and cluster URI. Changing
the name of an environment will also update the directory structure in
-'environments'.
-`,
+'environments'.`,
Example: ` # Updates the URI of the environment 'us-west/staging'.
ksonnet env set us-west/staging --uri=http://example.com
--
GitLab