Skip to content
Snippets Groups Projects
Unverified Commit f808801c authored by Jessica Yao's avatar Jessica Yao Committed by GitHub
Browse files

Merge pull request #105 from jessicayuen/format-commands 

First pass at CLI documentation formatting fixes
parents 7223254e d90b362b
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 461 additions and 470 deletions
cmd/apply.go
+ 16
− 16
View file @ f808801c
......@@ -121,28 +121,28 @@ var applyCmd = &cobra.Command{
return c.Run(objs, wd)
},
Long: `Update (or optionally create) Kubernetes resources on the cluster using the
local configuration. Use the '--create' flag to control whether we create them
local configuration. Use the` + " `--create` " + `flag to control whether we create them
if they do not exist (default: true).
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`,
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.
ks apply dev
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.
ks apply dev
# Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'.
ks appy -f ./pod.yaml
# Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'.
ks appy -f ./pod.yaml
# Create or update resources described in the JSON file. Changes are deployed
# to the cluster pointed at the 'dev' environment.
ks apply dev -f ./pod.json
# Create or update resources described in the JSON file. Changes are deployed
# to the cluster pointed at the 'dev' environment.
ks apply dev -f ./pod.json
# Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'.
ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
# Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'.
ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
# Display set of actions we will execute when we run 'apply'.
ks apply dev --dry-run`,
# Display set of actions we will execute when we run 'apply'.
ks apply dev --dry-run`,
}
cmd/delete.go
+ 12
− 12
View file @ f808801c
......@@ -88,19 +88,19 @@ configuration.
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
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
# 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 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 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 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`,
}
cmd/diff.go
+ 29
− 29
View file @ f808801c
......@@ -88,35 +88,35 @@ 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`,
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`,
}
func initDiffCmd(cmd *cobra.Command, wd metadata.AbsPath, envFq1, envFq2 *string, files []string, diffStrategy string) (kubecfg.DiffCmd, error) {
......
cmd/env.go
+ 73
− 74
View file @ f808801c
......@@ -56,7 +56,7 @@ 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".
` + " `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
......@@ -68,25 +68,27 @@ 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
` + " `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
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`,
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`,
RunE: func(cmd *cobra.Command, args []string) error {
return fmt.Errorf("Command 'env' requires a subcommand\n\n%s", cmd.UsageString())
},
......@@ -157,48 +159,49 @@ var envAddCmd = &cobra.Command{
},
Long: `Add a new environment to a ksonnet project. Names are restricted to not
include punctuation, so names like '../foo' are not allowed.
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 'help
env'.
` + " `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 'env add' will add to this directory structure.
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'. '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
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`,
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.
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'.
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.
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`,
'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.
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'.
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.
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`,
}
var envRmCmd = &cobra.Command{
......@@ -230,15 +233,11 @@ 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. 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.
ks env rm us-west/staging`,
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.
ks env rm us-west/staging`,
}
var envListCmd = &cobra.Command{
......@@ -324,19 +323,19 @@ var envSetCmd = &cobra.Command{
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'.
ks env set us-west/staging --server=http://example.com
Example: `# Updates 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'.
ks env set us-west/staging --namespace=staging
# Updates 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'.
ks env set us-west/staging --server=http://example.com --name=us-east/staging
# Updates 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.
ks env set us-west/staging --context=staging-west`,
# Updates API server address of the environment 'us-west/staging' based on the
# server in the context 'staging-west' in your kubeconfig file.
ks env set us-west/staging --context=staging-west`,
}
func commonEnvFlags(flags *pflag.FlagSet) (server, namespace, context string, err error) {
......
cmd/init.go
+ 26
− 30
View file @ f808801c
......@@ -77,43 +77,39 @@ var initCmd = &cobra.Command{
return c.Run()
},
Long: `Initialize a ksonnet project in a new directory, 'app-name'. This process
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.
specified in` + " `$KUBECONFIG`" + `.
2. Generating the following tree in the current directory.
app-name/
.gitignore Default .gitignore; can customize VCS
.ksonnet/ Metadata for ksonnet
envs/
default/ Default generated environment]
k.libsonnet
k8s.libsonnet
swagger.json
spec.json
components/ Top-level Kubernetes objects defining application
lib/ user-written .libsonnet files
vendor/ mixin libraries, prototypes
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
`,
Example: ` # Initialize ksonnet application, using the capabilities of live cluster
# specified in the $KUBECONFIG environment variable (specifically: the
# current context) to generate 'ksonnet-lib'.
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 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 ksonnet application, using the context 'dev' from the kubeconfig
# file.
ks init app-name --context=dev`,
Example: `# Initialize ksonnet application, using the capabilities of live cluster
# specified in the $KUBECONFIG environment variable (specifically: the
# current context) to generate 'ksonnet-lib'.
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 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 ksonnet application, using the context 'dev' from the kubeconfig
# file.
ks init app-name --context=dev`,
}
cmd/param.go
+ 24
− 23
View file @ f808801c
......@@ -54,7 +54,8 @@ demands.
Environments are ksonnet "named clusters". For more information on environments,
run:
ks env --help
ks env --help
`,
RunE: func(cmd *cobra.Command, args []string) error {
return fmt.Errorf("Command 'param' requires a subcommand\n\n%s", cmd.UsageString())
......@@ -83,20 +84,20 @@ var paramSetCmd = &cobra.Command{
return c.Run()
},
Long: `"Set component or environment parameters such as replica count or name.
Long: `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
` + " `components/params.libsonnet` " + `file directly. Likewise, for greater customization
of environment parameters, we suggest modifying the
'environments/:name/params.libsonnet' file.
` + " `environments/:name/params.libsonnet` " + `file.
`,
Example: ` # Updates the replica count of the 'guestbook' component to 4.
ks param set guestbook replicas 4
Example: `# Updates 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'
ks param set guestbook replicas 2 --env=dev`,
# Updates the replica count of the 'guestbook' component to 2 for the environment
# 'dev'
ks param set guestbook replicas 2 --env=dev`,
}
var paramListCmd = &cobra.Command{
......@@ -122,24 +123,24 @@ var paramListCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout())
},
Long: `"List all component parameters or environment parameters.
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.
Furthermore, parameters can be listed on a per-environment basis.
`,
Example: ` # List all component parameters
ks param list
Example: `# List all component parameters
ks param list
# List all parameters for the component "guestbook"
ks param list guestbook
# List all parameters for the component "guestbook"
ks param list guestbook
# List all parameters for the environment "dev"
ks param list --env=dev
# List all parameters for the environment "dev"
ks param list --env=dev
# List all parameters for the component "guestbook" in the environment "dev"
ks param list guestbook --env=dev`,
# List all parameters for the component "guestbook" in the environment "dev"
ks param list guestbook --env=dev`,
}
var paramDiffCmd = &cobra.Command{
......@@ -163,14 +164,14 @@ var paramDiffCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout())
},
Long: `"Pretty prints differences between the component parameters of two environments.
Long: `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.
`,
Example: ` # Diff between the component parameters on environments 'dev' and 'prod'
ks param diff dev prod
Example: `# Diff between the component parameters on environments 'dev' and 'prod'
ks param diff dev prod
# Diff between the component 'guestbook' on environments 'dev' and 'prod'
ks param diff dev prod --component=guestbook`,
# Diff between the component 'guestbook' on environments 'dev' and 'prod'
ks param diff dev prod --component=guestbook`,
}
cmd/pkg.go
+ 10
− 10
View file @ f808801c
......@@ -81,29 +81,29 @@ var pkgInstallCmd = &cobra.Command{
},
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.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
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";
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.
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:
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 incubator/nginx@v0.1 --name nginxv1
ks pkg install incubator/nginx@v0.2 --name nginxv2
With these commands, a user can 'import "kspkg://nginx1"', and
'import "kspkg://nginx2"' with no conflict.`,
With these commands, a user can` + " `import \"kspkg://nginxv1\"` " + `, and
` + " `import \"kspkg://nginxv2\"` " + `with no conflict.`,
}
var pkgDescribeCmd = &cobra.Command{
......@@ -162,7 +162,7 @@ var pkgDescribeCmd = &cobra.Command{
},
Long: `Output documentation for some ksonnet registry prototype uniquely identified in
the current ksonnet project by some 'registry-name'.`,
the current ksonnet project by some 'registry-name'.`,
}
var pkgListCmd = &cobra.Command{
......
cmd/prototype.go
+ 84
− 84
View file @ f808801c
......@@ -50,40 +50,40 @@ var prototypeCmd = &cobra.Command{
Prototypes are Kubernetes app configuration templates with "holes" that can be
filled in by (e.g.) the ksonnet CLI tool or a language server. For example, a
prototype for a 'apps.v1beta1.Deployment' might require a name and image, and
prototype for a` + " `apps.v1beta1.Deployment` " + `might require a name and image, and
the ksonnet CLI could expand this to a fully-formed 'Deployment' object.
Commands:
use Instantiate prototype, filling in parameters from flags, and
emitting the generated code to stdout.
describe Display documentation and details about a prototype
search Search for a prototype`,
Example: ` # Display documentation about prototype
# 'io.ksonnet.pkg.prototype.simple-deployment', including:
#
# (1) a description of what gets generated during instantiation
# (2) a list of parameters that are required to be passed in with CLI flags
#
# NOTE: Many subcommands only require the user to specify enough of the
# identifier to disambiguate it among other known prototypes, which is why
# 'simple-deployment' is given as argument instead of the fully-qualified
# name.
ks prototype describe simple-deployment
# Instantiate prototype 'io.ksonnet.pkg.prototype.simple-deployment', using
# the 'nginx' image, and port 80 exposed.
#
# SEE ALSO: Note above for a description of why this subcommand can take
# 'simple-deployment' instead of the fully-qualified prototype name.
ks prototype use simple-deployment \
--name=nginx \
--image=nginx \
--port=80 \
--portName=http
# Search known prototype metadata for the string 'deployment'.
ks prototype search deployment`,
use Instantiate prototype, filling in parameters from flags, and
emitting the generated code to stdout.
describe Display documentation and details about a prototype
search Search for a prototype`,
Example: `# Display documentation about prototype
# 'io.ksonnet.pkg.prototype.simple-deployment', including:
#
# (1) a description of what gets generated during instantiation
# (2) a list of parameters that are required to be passed in with CLI flags
#
# NOTE: Many subcommands only require the user to specify enough of the
# identifier to disambiguate it among other known prototypes, which is why
# 'simple-deployment' is given as argument instead of the fully-qualified
# name.
ks prototype describe simple-deployment
# Instantiate prototype 'io.ksonnet.pkg.prototype.simple-deployment', using
# the 'nginx' image, and port 80 exposed.
#
# SEE ALSO: Note above for a description of why this subcommand can take
# 'simple-deployment' instead of the fully-qualified prototype name.
ks prototype use simple-deployment \
--name=nginx \
--image=nginx \
--port=80 \
--portName=http
# Search known prototype metadata for the string 'deployment'.
ks prototype search deployment`,
}
var prototypeListCmd = &cobra.Command{
......@@ -173,27 +173,27 @@ var prototypeDescribeCmd = &cobra.Command{
return nil
},
Long: `Output documentation, examples, and other information for some ksonnet
prototype uniquely identified by some (possibly partial) 'prototype-name'. This
prototype uniquely identified by some (possibly partial)` + " `prototype-name`" + `. This
includes:
(1) a description of what gets generated during instantiation
(2) a list of parameters that are required to be passed in with CLI flags
1. a description of what gets generated during instantiation
2. a list of parameters that are required to be passed in with CLI flags
'prototype-name' need only contain enough of the suffix of a name to uniquely
` + "`prototype-name` " + `need only contain enough of the suffix of a name to uniquely
disambiguate it among known names. For example, 'deployment' may resolve
ambiguously, in which case 'use' will fail, while 'simple-deployment' might be
unique enough to resolve to 'io.ksonnet.pkg.prototype.simple-deployment'.`,
Example: ` # Display documentation about prototype, including:
ks prototype describe io.ksonnet.pkg.prototype.simple-deployment
Example: `# Display documentation about prototype, including:
ks prototype describe io.ksonnet.pkg.prototype.simple-deployment
# Display documentation about prototype using a unique suffix of an
# identifier. That is, this command only requires a long enough suffix to
# uniquely identify a ksonnet prototype. In this example, the suffix
# 'simple-deployment' is enough to uniquely identify
# 'io.ksonnet.pkg.prototype.simple-deployment', but 'deployment' might not
# be, as several names end with that suffix.
ks prototype describe simple-deployment`,
# Display documentation about prototype using a unique suffix of an
# identifier. That is, this command only requires a long enough suffix to
# uniquely identify a ksonnet prototype. In this example, the suffix
# 'simple-deployment' is enough to uniquely identify
# 'io.ksonnet.pkg.prototype.simple-deployment', but 'deployment' might not
# be, as several names end with that suffix.
ks prototype describe simple-deployment`,
}
var prototypeSearchCmd = &cobra.Command{
......@@ -218,9 +218,9 @@ var prototypeSearchCmd = &cobra.Command{
return nil
},
Long: `Search ksonnet for prototypes whose names contain 'name-substring'.`,
Example: ` # Search known prototype metadata for the string 'deployment'.
ks prototype search deployment`,
Long: `Search ksonnet for prototypes whose names contain` + " `name-substring` " + `.`,
Example: `# Search known prototype metadata for the string 'deployment'.
ks prototype search deployment`,
}
var prototypePreviewCmd = &cobra.Command{
......@@ -292,25 +292,25 @@ var prototypePreviewCmd = &cobra.Command{
return nil
},
Long: `Expand prototype uniquely identified by (possibly partial)
'prototype-name', filling in parameters from flags, and emitting the generated
` + " `prototype-name` " + `, filling in parameters from flags, and emitting the generated
code to stdout.
Note also that 'prototype-name' need only contain enough of the suffix of a name
Note also that` + " `prototype-name` " + `need only contain enough of the suffix of a name
to uniquely disambiguate it among known names. For example, 'deployment' may
resolve ambiguously, in which case 'use' will fail, while 'deployment' might be
resolve ambiguously, in which case` + " `use` " + `will fail, while 'deployment' might be
unique enough to resolve to 'io.ksonnet.pkg.single-port-deployment'.`,
Example: ` # Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image, and port 80 exposed.
ks prototype preview io.ksonnet.pkg.prototype.simple-deployment \
--name=nginx \
--image=nginx
# Preview prototype using a unique suffix of an identifier. See
# introduction of help message for more information on how this works.
ks prototype preview simple-deployment \
--name=nginx \
--image=nginx`,
Example: `# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image, and port 80 exposed.
ks prototype preview io.ksonnet.pkg.prototype.simple-deployment \
--name=nginx \
--image=nginx
# Preview prototype using a unique suffix of an identifier. See
# introduction of help message for more information on how this works.
ks prototype preview simple-deployment \
--name=nginx \
--image=nginx`,
}
// generateCmd acts as an alias for `prototype use`
......@@ -397,37 +397,37 @@ var prototypeUseCmd = &cobra.Command{
return manager.CreateComponent(componentName, text, params, templateType)
},
Long: `Expand prototype uniquely identified by (possibly partial) 'prototype-name',
Long: `Expand prototype uniquely identified by (possibly partial)` + " `prototype-name` " + `,
filling in parameters from flags, and placing it into the file
'components/componentName', with the appropriate extension set. For example, the
` + " `components/componentName` " + `, with the appropriate extension set. For example, the
following command will expand template 'io.ksonnet.pkg.single-port-deployment'
and place it in the file 'components/nginx-depl.jsonnet' (since by default
and place it in the file` + " `components/nginx-depl.jsonnet` " + `(since by default
ksonnet will expand templates as Jsonnet).
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--name=nginx \
--image=nginx
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--name=nginx \
--image=nginx
Note also that 'prototype-name' need only contain enough of the suffix of a name
Note also that` + " `prototype-name` " + `need only contain enough of the suffix of a name
to uniquely disambiguate it among known names. For example, 'deployment' may
resolve ambiguously, in which case 'use' will fail, while 'deployment' might be
resolve ambiguously, in which case` + " `use` " + `will fail, while 'deployment' might be
unique enough to resolve to 'io.ksonnet.pkg.single-port-deployment'.`,
Example: ` # Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'.
ks prototype use io.ksonnet.pkg.prototype.simple-deployment nginx-depl \
--name=nginx \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# unique suffix, 'deployment'. The expanded prototype is again placed in
# 'components/nginx-depl.jsonnet'. See introduction of help message for more
# information on how this works. Note that if you have imported another
# prototype with this suffix, this may resolve ambiguously for you.
ks prototype use deployment nginx-depl \
--name=nginx \
--image=nginx`,
Example: `# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'.
ks prototype use io.ksonnet.pkg.prototype.simple-deployment nginx-depl \
--name=nginx \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# unique suffix, 'deployment'. The expanded prototype is again placed in
# 'components/nginx-depl.jsonnet'. See introduction of help message for more
# information on how this works. Note that if you have imported another
# prototype with this suffix, this may resolve ambiguously for you.
ks prototype use deployment nginx-depl \
--name=nginx \
--image=nginx`,
}
func bindPrototypeFlags(cmd *cobra.Command, proto *prototype.SpecificationSchema) {
......
cmd/registry.go
+ 2
− 2
View file @ f808801c
......@@ -39,7 +39,7 @@ manage in a ksonnet project using the CLI. A typical library contains:
var registryListCmd = &cobra.Command{
Use: "list",
Short: `List all registries known to current ksonnet app`,
Short: `List all registries known to the current ksonnet app.`,
RunE: func(cmd *cobra.Command, args []string) error {
const (
nameHeader = "NAME"
......@@ -142,5 +142,5 @@ var registryDescribeCmd = &cobra.Command{
},
Long: `Output documentation for some ksonnet registry prototype uniquely identified in
the current ksonnet project by some 'registry-name'.`,
the current ksonnet project by some` + " `registry-name`" + `.`,
}
cmd/update.go
+ 12
− 12
View file @ f808801c
......@@ -109,19 +109,19 @@ if they do not exist (default: true).
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`,
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.
ks update dev
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.
ks update dev
# Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'.
ks update -f ./pod.yaml
# Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'.
ks update -f ./pod.yaml
# Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'.
ks update --kubeconfig=./kubeconfig -f ./pod.yaml
# Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'.
ks update --kubeconfig=./kubeconfig -f ./pod.yaml
# Display set of actions we will execute when we run 'update'.
ks update dev --dry-run`,
# Display set of actions we will execute when we run 'update'.
ks update dev --dry-run`,
}
cmd/validate.go
+ 12
− 12
View file @ f808801c
......@@ -72,19 +72,19 @@ 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).
ksonnet validate dev
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).
ksonnet validate dev
# Validate resources described in a YAML file.
ksonnet validate -f ./pod.yaml
# 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 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 described in a Jsonnet file. Does not expand using
# environment bindings.
ksonnet validate -f ./pod.jsonnet`,
}
docs/cli-reference/ks_apply.md
+ 16
− 16
View file @ f808801c
......@@ -6,7 +6,7 @@ Apply local configuration to remote cluster
Update (or optionally create) Kubernetes resources on the cluster using the
local configuration. Use the '--create' flag to control whether we create them
local configuration. Use the `--create` flag to control whether we create them
if they do not exist (default: true).
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
......@@ -19,25 +19,25 @@ ks apply [env-name] [-f <file-or-dir>]
### 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.
ks apply dev
# 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.
ks apply dev
# Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'.
ks appy -f ./pod.yaml
# Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'.
ks appy -f ./pod.yaml
# Create or update resources described in the JSON file. Changes are deployed
# to the cluster pointed at the 'dev' environment.
ks apply dev -f ./pod.json
# Create or update resources described in the JSON file. Changes are deployed
# to the cluster pointed at the 'dev' environment.
ks apply dev -f ./pod.json
# Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'.
ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
# Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'.
ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
# Display set of actions we will execute when we run 'apply'.
ks apply dev --dry-run
# Display set of actions we will execute when we run 'apply'.
ks apply dev --dry-run
```
### Options
......
docs/cli-reference/ks_delete.md
+ 12
− 12
View file @ f808801c
......@@ -18,21 +18,21 @@ ks delete [env-name] [-f <file-or-dir>]
### Examples
```
# Delete all resources described in a ksonnet application, from the 'dev'
# environment. Can be used in any subdirectory of the application.
ks delete dev
# Delete all resources described in a ksonnet application, from the 'dev'
# environment. Can be used in any subdirectory of the application.
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 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 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 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
```
### Options
......
docs/cli-reference/ks_diff.md
+ 29
− 29
View file @ f808801c
......@@ -18,35 +18,35 @@ ks diff [<env1> [<env2>]] [-f <file-or-dir>]
### 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 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
```
### Options
......
docs/cli-reference/ks_env.md
+ 20
− 18
View file @ f808801c
......@@ -6,7 +6,7 @@ Manage ksonnet environments
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".
`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
......@@ -18,25 +18,27 @@ 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
`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
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
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
```
ks env
......
docs/cli-reference/ks_env_add.md
+ 35
− 34
View file @ f808801c
......@@ -6,34 +6,35 @@ Add a new environment to a ksonnet project
Add a new environment to a ksonnet project. Names are restricted to not
include punctuation, so names like '../foo' are not allowed.
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 'help
env'.
`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 'env add' will add to this directory structure.
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'. '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
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
'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
```
ks env add <env-name>
......@@ -42,20 +43,20 @@ 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.
ks env add us-west/staging
# 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.
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'.
ks env add us-west/staging --api-spec=version:v1.7.1 --namespace=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'.
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.
ks env add my-env --context=dev
# Initialize a new environment using the 'dev' context in your kubeconfig file.
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 using a server address.
ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com
```
### Options
......
docs/cli-reference/ks_env_rm.md
+ 5
− 9
View file @ f808801c
......@@ -6,11 +6,8 @@ Delete an environment from a ksonnet project
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.
as removing the <env-name> environment directory and all files contained. All empty
parent directories are also subsequently deleted.
```
ks env rm <env-name>
......@@ -19,10 +16,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.
ks env rm us-west/staging
# 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.
ks env rm us-west/staging
```
### Options inherited from parent commands
......
docs/cli-reference/ks_env_set.md
+ 10
− 10
View file @ f808801c
......@@ -16,19 +16,19 @@ ks env set <env-name>
### Examples
```
# Updates the API server address of the environment 'us-west/staging'.
ks env set us-west/staging --server=http://example.com
# Updates 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'.
ks env set us-west/staging --namespace=staging
# Updates 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'.
ks env set us-west/staging --server=http://example.com --name=us-east/staging
# Updates 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.
ks env set us-west/staging --context=staging-west
# Updates API server address of the environment 'us-west/staging' based on the
# server in the context 'staging-west' in your kubeconfig file.
ks env set us-west/staging --context=staging-west
```
### Options
......
docs/cli-reference/ks_generate.md
+ 8
− 8
View file @ f808801c
......@@ -5,20 +5,20 @@ Expand prototype, place in components/ directory of ksonnet app
### Synopsis
Expand prototype uniquely identified by (possibly partial) 'prototype-name',
Expand prototype uniquely identified by (possibly partial) `prototype-name` ,
filling in parameters from flags, and placing it into the file
'components/componentName', with the appropriate extension set. For example, the
`components/componentName` , with the appropriate extension set. For example, the
following command will expand template 'io.ksonnet.pkg.single-port-deployment'
and place it in the file 'components/nginx-depl.jsonnet' (since by default
and place it in the file `components/nginx-depl.jsonnet` (since by default
ksonnet will expand templates as Jsonnet).
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--name=nginx \
--image=nginx
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--name=nginx \
--image=nginx
Note also that 'prototype-name' need only contain enough of the suffix of a name
Note also that `prototype-name` need only contain enough of the suffix of a name
to uniquely disambiguate it among known names. For example, 'deployment' may
resolve ambiguously, in which case 'use' will fail, while 'deployment' might be
resolve ambiguously, in which case `use` will fail, while 'deployment' might be
unique enough to resolve to 'io.ksonnet.pkg.single-port-deployment'.
```
......
docs/cli-reference/ks_init.md
+ 26
− 30
View file @ f808801c
......@@ -5,28 +5,24 @@ Initialize a ksonnet project
### Synopsis
Initialize a ksonnet project in a new directory, 'app-name'. This process
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.
specified in `$KUBECONFIG`.
2. Generating the following tree in the current directory.
app-name/
.gitignore Default .gitignore; can customize VCS
.ksonnet/ Metadata for ksonnet
envs/
default/ Default generated environment]
k.libsonnet
k8s.libsonnet
swagger.json
spec.json
components/ Top-level Kubernetes objects defining application
lib/ user-written .libsonnet files
vendor/ mixin libraries, prototypes
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
```
......@@ -36,22 +32,22 @@ 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'.
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 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 ksonnet application, using the context 'dev' from the kubeconfig
# file.
ks init app-name --context=dev
# Initialize ksonnet application, using the capabilities of live cluster
# specified in the $KUBECONFIG environment variable (specifically: the
# current context) to generate 'ksonnet-lib'.
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 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 ksonnet application, using the context 'dev' from the kubeconfig
# file.
ks init app-name --context=dev
```
### Options
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment