From 786a63b687103d44f14d8c29ca6c1d79f296071c Mon Sep 17 00:00:00 2001
From: Jessica Yuen <im.jessicayuen@gmail.com>
Date: Tue, 21 Nov 2017 13:46:49 -0800
Subject: [PATCH] Improve ks init help message
Specifically,
1. Place more emphasize on project initialization based on context
2. Place ksonnet-lib details into footer.
3. Order examples based on most common use cases.
4. Suggest to visit ks generate
---
cmd/init.go | 79 +++++++++++++++++++++--------------
docs/cli-reference/ks.md | 2 +-
docs/cli-reference/ks_init.md | 73 +++++++++++++++++++-------------
3 files changed, 94 insertions(+), 60 deletions(-)
diff --git a/cmd/init.go b/cmd/init.go
index 2921693a..5c6ff8c5 100644
--- a/cmd/init.go
+++ b/cmd/init.go
@@ -36,7 +36,7 @@ func init() {
var initCmd = &cobra.Command{
Use: "init <app-name>",
- Short: "Initialize a ksonnet project",
+ Short: "Initialize a ksonnet application",
RunE: func(cmd *cobra.Command, args []string) error {
flags := cmd.Flags()
if len(args) != 1 {
@@ -77,39 +77,56 @@ var initCmd = &cobra.Command{
return c.Run()
},
- Long: `Initialize a ksonnet project in a new directory,` + " `app-name`" + `. This process
-consists of two steps:
-
-1. Generating 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`" + `.
-2. Generating the following tree in the current directory.
-
- app-name/
- .gitignore Default .gitignore; can customize VCS
- .ksonnet/ Metadata for ksonnet
- environments/
- default/ [Default generated environment]
- components/ Top-level Kubernetes objects defining application
- lib/ user-written .libsonnet files
- vendor/ part libraries, prototypes
+ Long: `Initialize 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.
+
+Creating a ksonnet application results in the following directory tree.
+
+ app-name/
+ .ksonnet/ Metadata for ksonnet
+ app.yaml Application specifications, ex: 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
+
+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`" + `.
`,
- Example: `# Initialize ksonnet application, using the capabilities of live cluster
-# specified in the $KUBECONFIG environment variable (specifically: the
-# current context) to generate 'ksonnet-lib'.
+ Example: `# Initialize a ksonnet application, based on cluster information from the
+# active kubeconfig file (specified by the environment variable $KUBECONFIG).
+# More specifically, the current context is used.
ks init app-name
-# Initialize ksonnet application, using the OpenAPI specification generated
-# in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
-ks init app-name --api-spec=version:v1.7.1
+# 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'.
+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'.
+ks init app-name --context=dev --namespace=dc-west
-# Initialize ksonnet application, using an OpenAPI specification file
-# generated by a build of Kubernetes to generate 'ksonnet-lib'.
-ks init app-name --api-spec=file:swagger.json
+# Initialize a ksonnet application, using v1.7.1 of the Kubernetes OpenAPI spec
+# to generate 'ksonnet-lib'.
+ks init app-name --api-spec=version:v1.7.1
-# Initialize ksonnet application, using the context 'dev' from the kubeconfig
-# file.
-ks init app-name --context=dev`,
+# Initialize a ksonnet application, using the OpenAPI spec generated by a
+# specific build of Kubernetes to generate 'ksonnet-lib'.
+ks init app-name --api-spec=file:swagger.json`,
}
diff --git a/docs/cli-reference/ks.md b/docs/cli-reference/ks.md
index 952a27fa..1354316c 100644
--- a/docs/cli-reference/ks.md
+++ b/docs/cli-reference/ks.md
@@ -19,7 +19,7 @@ Synchronise Kubernetes resources with config files
* [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) - Expand prototype, place in components/ directory of ksonnet app
-* [ks init](ks_init.md) - Initialize a ksonnet project
+* [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 prototype](ks_prototype.md) - Instantiate, inspect, and get examples for ksonnet prototypes
diff --git a/docs/cli-reference/ks_init.md b/docs/cli-reference/ks_init.md
index 7613a73a..9be0796d 100644
--- a/docs/cli-reference/ks_init.md
+++ b/docs/cli-reference/ks_init.md
@@ -1,28 +1,38 @@
## ks init
-Initialize a ksonnet project
+Initialize a ksonnet application
### Synopsis
-Initialize a ksonnet project in a new directory, `app-name`. This process
-consists of two steps:
+Initialize a ksonnet application in a new directory, `app-name`.
-1. Generating 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`.
-2. Generating the following tree in the current directory.
+This command generates all the project scaffolding required to begin creating and
+deploying components to Kubernetes clusters.
- app-name/
- .gitignore Default .gitignore; can customize VCS
- .ksonnet/ Metadata for ksonnet
- environments/
- default/ [Default generated environment]
- components/ Top-level Kubernetes objects defining application
- lib/ user-written .libsonnet files
- vendor/ part libraries, prototypes
+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.
+
+Creating a ksonnet application results in the following directory tree.
+
+ app-name/
+ .ksonnet/ Metadata for ksonnet
+ app.yaml Application specifications, ex: 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
+
+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`.
```
@@ -32,22 +42,29 @@ ks init <app-name>
### Examples
```
-# Initialize ksonnet application, using the capabilities of live cluster
-# specified in the $KUBECONFIG environment variable (specifically: the
-# current context) to generate 'ksonnet-lib'.
+# Initialize a ksonnet application, based on cluster information from the
+# active kubeconfig file (specified by the environment variable $KUBECONFIG).
+# More specifically, the current context is used.
ks init app-name
-# Initialize ksonnet application, using the OpenAPI specification generated
-# in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
+# 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'.
+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'.
+ks init app-name --context=dev --namespace=dc-west
+
+# Initialize a ksonnet application, using v1.7.1 of the Kubernetes OpenAPI spec
+# to generate 'ksonnet-lib'.
ks init app-name --api-spec=version:v1.7.1
-# Initialize ksonnet application, using an OpenAPI specification file
-# generated by a build of Kubernetes to generate 'ksonnet-lib'.
+# Initialize a ksonnet application, using the OpenAPI spec generated by a
+# specific build of Kubernetes to generate 'ksonnet-lib'.
ks init app-name --api-spec=file:swagger.json
-
-# Initialize ksonnet application, using the context 'dev' from the kubeconfig
-# file.
-ks init app-name --context=dev
```
### Options
--
GitLab