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{ ...@@ -121,28 +121,28 @@ var applyCmd = &cobra.Command{
return c.Run(objs, wd) return c.Run(objs, wd)
}, },
Long: `Update (or optionally create) Kubernetes resources on the cluster using the 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). if they do not exist (default: true).
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`, files.`,
Example: ` # Create or update all resources described in a ksonnet application, and 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 # running in the 'dev' environment. Can be used in any subdirectory of the
# application. # application.
ks apply dev ks apply dev
# Create or update resources described in a YAML file. Automatically picks up # Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'. # the cluster's location from '$KUBECONFIG'.
ks appy -f ./pod.yaml ks appy -f ./pod.yaml
# Create or update resources described in the JSON file. Changes are deployed # Create or update resources described in the JSON file. Changes are deployed
# to the cluster pointed at the 'dev' environment. # to the cluster pointed at the 'dev' environment.
ks apply dev -f ./pod.json ks apply dev -f ./pod.json
# Update resources described in a YAML file, and running in cluster referred # Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'. # to by './kubeconfig'.
ks apply --kubeconfig=./kubeconfig -f ./pod.yaml ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
# Display set of actions we will execute when we run 'apply'. # Display set of actions we will execute when we run 'apply'.
ks apply dev --dry-run`, ks apply dev --dry-run`,
} }
cmd/delete.go
+ 12
− 12
View file @ f808801c
...@@ -88,19 +88,19 @@ configuration. ...@@ -88,19 +88,19 @@ configuration.
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`, files.`,
Example: ` # Delete all resources described in a ksonnet application, from the 'dev' Example: `# Delete all resources described in a ksonnet application, from the 'dev'
# environment. Can be used in any subdirectory of the application. # environment. Can be used in any subdirectory of the application.
ks delete dev ks delete dev
# Delete resources described in a YAML file. Automatically picks up the # Delete resources described in a YAML file. Automatically picks up the
# cluster's location from '$KUBECONFIG'. # cluster's location from '$KUBECONFIG'.
ks delete -f ./pod.yaml ks delete -f ./pod.yaml
# Delete resources described in the JSON file from the 'dev' environment. Can # Delete resources described in the JSON file from the 'dev' environment. Can
# be used in any subdirectory of the application. # be used in any subdirectory of the application.
ks delete dev -f ./pod.json ks delete dev -f ./pod.json
# Delete resources described in a YAML file, and running in the cluster # Delete resources described in a YAML file, and running in the cluster
# specified by the current context in specified kubeconfig file. # specified by the current context in specified kubeconfig file.
ks delete --kubeconfig=./kubeconfig -f ./pod.yaml`, ks delete --kubeconfig=./kubeconfig -f ./pod.yaml`,
} }
cmd/diff.go
+ 29
− 29
View file @ f808801c
...@@ -88,35 +88,35 @@ configurations. ...@@ -88,35 +88,35 @@ configurations.
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`, files.`,
Example: ` # Show diff between resources described in a the local 'dev' environment Example: `# Show diff between resources described in a the local 'dev' environment
# specified by the ksonnet application and the remote cluster referenced by # specified by the ksonnet application and the remote cluster referenced by
# the same 'dev' environment. Can be used in any subdirectory of the application. # the same 'dev' environment. Can be used in any subdirectory of the application.
ksonnet diff dev ksonnet diff dev
# Show diff between resources at remote clusters. This requires ksonnet # Show diff between resources at remote clusters. This requires ksonnet
# application defined environments. Diff between the cluster defined at the # application defined environments. Diff between the cluster defined at the
# 'us-west/dev' environment, and the cluster defined at the 'us-west/prod' # 'us-west/dev' environment, and the cluster defined at the 'us-west/prod'
# environment. Can be used in any subdirectory of the application. # environment. Can be used in any subdirectory of the application.
ksonnet diff remote:us-west/dev remote:us-west/prod ksonnet diff remote:us-west/dev remote:us-west/prod
# Show diff between resources at a remote and a local cluster. This requires # Show diff between resources at a remote and a local cluster. This requires
# ksonnet application defined environments. Diff between the cluster defined # ksonnet application defined environments. Diff between the cluster defined
# at the 'us-west/dev' environment, and the cluster defined at the # at the 'us-west/dev' environment, and the cluster defined at the
# 'us-west/prod' environment. Can be used in any subdirectory of the # 'us-west/prod' environment. Can be used in any subdirectory of the
# application. # application.
ksonnet diff local:us-west/dev remote:us-west/prod ksonnet diff local:us-west/dev remote:us-west/prod
# Show diff between resources described in a YAML file and the cluster # Show diff between resources described in a YAML file and the cluster
# referenced in '$KUBECONFIG'. # referenced in '$KUBECONFIG'.
ks diff -f ./pod.yaml ks diff -f ./pod.yaml
# Show diff between resources described in a JSON file and the cluster # Show diff between resources described in a JSON file and the cluster
# referenced by the environment 'dev'. # referenced by the environment 'dev'.
ks diff dev -f ./pod.json ks diff dev -f ./pod.json
# Show diff between resources described in a YAML file and the cluster # Show diff between resources described in a YAML file and the cluster
# referred to by './kubeconfig'. # referred to by './kubeconfig'.
ks diff --kubeconfig=./kubeconfig -f ./pod.yaml`, 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) { 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{ ...@@ -56,7 +56,7 @@ var envCmd = &cobra.Command{
Use: "env", Use: "env",
Short: `Manage ksonnet environments`, Short: `Manage ksonnet environments`,
Long: `An environment acts as a sort of "named cluster", allowing for commands like 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 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 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 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 ...@@ -68,25 +68,27 @@ often contained in a kubeconfig file), and
Environments are represented as a hierarchy in the 'environments' directory of a Environments are represented as a hierarchy in the 'environments' directory of a
ksonnet application. For example, in the example below, there are two ksonnet application. For example, in the example below, there are two
environments: 'default' and 'us-west/staging'. Each contains a cached version of 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. uniquely identifies the cluster.
environments/ environments/
default/ [Default generated environment] default/ [Default generated environment]
.metadata/ .metadata/
k.libsonnet k.libsonnet
k8s.libsonnet k8s.libsonnet
swagger.json swagger.json
spec.json spec.json
default.jsonnet default.jsonnet
us-west/ params.libsonnet
staging/ [Example of user-generated env] us-west/
.metadata/ staging/ [Example of user-generated env]
k.libsonnet .metadata/
k8s.libsonnet k.libsonnet
swagger.json k8s.libsonnet
spec.json [This will contain the API server address of the environment and other environment metadata] swagger.json
staging.jsonnet`, 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 { RunE: func(cmd *cobra.Command, args []string) error {
return fmt.Errorf("Command 'env' requires a subcommand\n\n%s", cmd.UsageString()) return fmt.Errorf("Command 'env' requires a subcommand\n\n%s", cmd.UsageString())
}, },
...@@ -157,48 +159,49 @@ var envAddCmd = &cobra.Command{ ...@@ -157,48 +159,49 @@ var envAddCmd = &cobra.Command{
}, },
Long: `Add a new environment to a ksonnet project. Names are restricted to not 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 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".
For more information on what an environment is and how they work, run 'help For more information on what an environment is and how they work, run` + " `ks help env` " + `.
env'.
Environments are represented as a hierarchy in the 'environments' directory of a 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 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. 'us-west/staging'.` + " `ks env add` " + `will add a similar directory to this environment.
environments/ environments/
default/ [Default generated environment] default/ [Default generated environment]
.metadata/ .metadata/
k.libsonnet k.libsonnet
k8s.libsonnet k8s.libsonnet
swagger.json swagger.json
spec.json spec.json
default.jsonnet default.jsonnet
us-west/ params.libsonnet
staging/ [Example of user-generated env] us-west/
.metadata/ staging/ [Example of user-generated env]
k.libsonnet .metadata/
k8s.libsonnet k.libsonnet
swagger.json k8s.libsonnet
spec.json [This will contain the API server address of the environment and other environment metadata], swagger.json
staging.jsonnet`, spec.json [This will contain the API server address of the environment and other environment metadata],
Example: ` # Initialize a new staging environment at 'us-west'. staging.jsonnet
# The environment will be setup using the current context in your kubecfg file. The directory params.libsonnet`,
# structure rooted at 'us-west' in the documentation above will be generated. Example: `# Initialize a new staging environment at 'us-west'.
ks env add us-west/staging # 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.
# Initialize a new staging environment at 'us-west' with the namespace 'staging', using ks env add us-west/staging
# 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'.
# Initialize a new environment using the 'dev' context in your kubeconfig file. ks env add us-west/staging --api-spec=version:v1.7.1 --namespace=staging
ks env add my-env --context=dev
# Initialize a new environment using the 'dev' context in your kubeconfig file.
# Initialize a new environment using a server address. ks env add my-env --context=dev
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`,
} }
var envRmCmd = &cobra.Command{ var envRmCmd = &cobra.Command{
...@@ -230,15 +233,11 @@ var envRmCmd = &cobra.Command{ ...@@ -230,15 +233,11 @@ var envRmCmd = &cobra.Command{
return c.Run() return c.Run()
}, },
Long: `Delete an environment from a ksonnet project. This is the same 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 as removing the <env-name> environment directory and all files contained. All empty
project exists in a hierarchy (e.g., 'us-east/staging') and deleting the parent directories are also subsequently deleted.`,
environment results in an empty environments directory (e.g., if deleting Example: `# Remove the directory 'us-west/staging' and all contents in the 'environments'
'us-east/staging' resulted in an empty 'us-east/' directory), then all empty # directory. This will also remove the parent directory 'us-west' if it is empty.
parent directories are subsequently deleted.`, ks env rm us-west/staging`,
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{ var envListCmd = &cobra.Command{
...@@ -324,19 +323,19 @@ var envSetCmd = &cobra.Command{ ...@@ -324,19 +323,19 @@ var envSetCmd = &cobra.Command{
Long: `Set environment fields such as the name, and server. Changing Long: `Set environment fields such as the name, and server. Changing
the name of an environment will also update the directory structure in the name of an environment will also update the directory structure in
'environments'.`, 'environments'.`,
Example: ` # Updates the API server address of the environment 'us-west/staging'. Example: `# Updates the API server address of the environment 'us-west/staging'.
ks env set us-west/staging --server=http://example.com ks env set us-west/staging --server=http://example.com
# Updates the namespace of the environment 'us-west/staging'. # Updates the namespace of the environment 'us-west/staging'.
ks env set us-west/staging --namespace=staging ks env set us-west/staging --namespace=staging
# Updates both the name and the server of the environment 'us-west/staging'. # Updates both the name and the server of the environment 'us-west/staging'.
# Updating the name will update the directory structure in 'environments'. # Updating the name will update the directory structure in 'environments'.
ks env set us-west/staging --server=http://example.com --name=us-east/staging 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 # Updates API server address of the environment 'us-west/staging' based on the
# server in the context 'staging-west' in your kubeconfig file. # server in the context 'staging-west' in your kubeconfig file.
ks env set us-west/staging --context=staging-west`, ks env set us-west/staging --context=staging-west`,
} }
func commonEnvFlags(flags *pflag.FlagSet) (server, namespace, context string, err error) { 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{ ...@@ -77,43 +77,39 @@ var initCmd = &cobra.Command{
return c.Run() 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: consists of two steps:
1. Generating ksonnet-lib. Users can set flags to generate the library based on 1. Generating ksonnet-lib. Users can set flags to generate the library based on
a variety of data, including server configuration and an OpenAPI a variety of data, including server configuration and an OpenAPI
specification of a Kubernetes build. By default, this is generated from the specification of a Kubernetes build. By default, this is generated from the
capabilities of the cluster specified in the cluster of the current context 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. 2. Generating the following tree in the current directory.
app-name/ app-name/
.gitignore Default .gitignore; can customize VCS .gitignore Default .gitignore; can customize VCS
.ksonnet/ Metadata for ksonnet .ksonnet/ Metadata for ksonnet
envs/ environments/
default/ Default generated environment] default/ [Default generated environment]
k.libsonnet components/ Top-level Kubernetes objects defining application
k8s.libsonnet lib/ user-written .libsonnet files
swagger.json vendor/ part libraries, prototypes
spec.json
components/ Top-level Kubernetes objects defining application
lib/ user-written .libsonnet files
vendor/ mixin libraries, prototypes
`, `,
Example: ` # Initialize ksonnet application, using the capabilities of live cluster Example: `# Initialize ksonnet application, using the capabilities of live cluster
# specified in the $KUBECONFIG environment variable (specifically: the # specified in the $KUBECONFIG environment variable (specifically: the
# current context) to generate 'ksonnet-lib'. # current context) to generate 'ksonnet-lib'.
ks init app-name ks init app-name
# Initialize ksonnet application, using the OpenAPI specification generated # Initialize ksonnet application, using the OpenAPI specification generated
# in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'. # in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
ks init app-name --api-spec=version:v1.7.1 ks init app-name --api-spec=version:v1.7.1
# Initialize ksonnet application, using an OpenAPI specification file # Initialize ksonnet application, using an OpenAPI specification file
# generated by a build of Kubernetes to generate 'ksonnet-lib'. # generated by a build of Kubernetes to generate 'ksonnet-lib'.
ks init app-name --api-spec=file:swagger.json ks init app-name --api-spec=file:swagger.json
# Initialize ksonnet application, using the context 'dev' from the kubeconfig # Initialize ksonnet application, using the context 'dev' from the kubeconfig
# file. # file.
ks init app-name --context=dev`, ks init app-name --context=dev`,
} }
cmd/param.go
+ 24
− 23
View file @ f808801c
...@@ -54,7 +54,8 @@ demands. ...@@ -54,7 +54,8 @@ demands.
Environments are ksonnet "named clusters". For more information on environments, Environments are ksonnet "named clusters". For more information on environments,
run: run:
ks env --help
ks env --help
`, `,
RunE: func(cmd *cobra.Command, args []string) error { RunE: func(cmd *cobra.Command, args []string) error {
return fmt.Errorf("Command 'param' requires a subcommand\n\n%s", cmd.UsageString()) return fmt.Errorf("Command 'param' requires a subcommand\n\n%s", cmd.UsageString())
...@@ -83,20 +84,20 @@ var paramSetCmd = &cobra.Command{ ...@@ -83,20 +84,20 @@ var paramSetCmd = &cobra.Command{
return c.Run() 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 Parameters are set individually, one at a time. If you require customization of
more fields, we suggest that you modify your ksonnet project's 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 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. Example: `# Updates the replica count of the 'guestbook' component to 4.
ks param set guestbook replicas 4 ks param set guestbook replicas 4
# Updates the replica count of the 'guestbook' component to 2 for the environment # Updates the replica count of the 'guestbook' component to 2 for the environment
# 'dev' # 'dev'
ks param set guestbook replicas 2 --env=dev`, ks param set guestbook replicas 2 --env=dev`,
} }
var paramListCmd = &cobra.Command{ var paramListCmd = &cobra.Command{
...@@ -122,24 +123,24 @@ var paramListCmd = &cobra.Command{ ...@@ -122,24 +123,24 @@ var paramListCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout()) 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 This command will display all parameters for the component specified. If a
component is not specified, parameters for all components will be listed. component is not specified, parameters for all components will be listed.
Furthermore, parameters can be listed on a per-environment basis. Furthermore, parameters can be listed on a per-environment basis.
`, `,
Example: ` # List all component parameters Example: `# List all component parameters
ks param list ks param list
# List all parameters for the component "guestbook" # List all parameters for the component "guestbook"
ks param list guestbook ks param list guestbook
# List all parameters for the environment "dev" # List all parameters for the environment "dev"
ks param list --env=dev ks param list --env=dev
# List all parameters for the component "guestbook" in the environment "dev" # List all parameters for the component "guestbook" in the environment "dev"
ks param list guestbook --env=dev`, ks param list guestbook --env=dev`,
} }
var paramDiffCmd = &cobra.Command{ var paramDiffCmd = &cobra.Command{
...@@ -163,14 +164,14 @@ var paramDiffCmd = &cobra.Command{ ...@@ -163,14 +164,14 @@ var paramDiffCmd = &cobra.Command{
return c.Run(cmd.OutOrStdout()) 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 A component flag is accepted to diff against a single component. By default, the
diff is performed against all components. diff is performed against all components.
`, `,
Example: ` # Diff between the component parameters on environments 'dev' and 'prod' Example: `# Diff between the component parameters on environments 'dev' and 'prod'
ks param diff dev prod ks param diff dev prod
# Diff between the component 'guestbook' on environments 'dev' and 'prod' # Diff between the component 'guestbook' on environments 'dev' and 'prod'
ks param diff dev prod --component=guestbook`, ks param diff dev prod --component=guestbook`,
} }
cmd/pkg.go
+ 10
− 10
View file @ f808801c
...@@ -81,29 +81,29 @@ var pkgInstallCmd = &cobra.Command{ ...@@ -81,29 +81,29 @@ var pkgInstallCmd = &cobra.Command{
}, },
Long: `Cache a ksonnet library locally, and make it available for use in the current 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 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. app repository.
For example, inside a ksonnet application directory, run: 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: 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 By default, ksonnet knows about two registries: incubator and stable, which are
the release channels for official ksonnet libraries. Additional registries can 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 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.1 --name nginxv1
ks pkg install incubator/nginx@v0.2 --name nginxv2 ks pkg install incubator/nginx@v0.2 --name nginxv2
With these commands, a user can 'import "kspkg://nginx1"', and With these commands, a user can` + " `import \"kspkg://nginxv1\"` " + `, and
'import "kspkg://nginx2"' with no conflict.`, ` + " `import \"kspkg://nginxv2\"` " + `with no conflict.`,
} }
var pkgDescribeCmd = &cobra.Command{ var pkgDescribeCmd = &cobra.Command{
...@@ -162,7 +162,7 @@ var pkgDescribeCmd = &cobra.Command{ ...@@ -162,7 +162,7 @@ var pkgDescribeCmd = &cobra.Command{
}, },
Long: `Output documentation for some ksonnet registry prototype uniquely identified in 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{ var pkgListCmd = &cobra.Command{
......
cmd/prototype.go
+ 84
− 84
View file @ f808801c
...@@ -50,40 +50,40 @@ var prototypeCmd = &cobra.Command{ ...@@ -50,40 +50,40 @@ var prototypeCmd = &cobra.Command{
Prototypes are Kubernetes app configuration templates with "holes" that can be 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 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. the ksonnet CLI could expand this to a fully-formed 'Deployment' object.
Commands: Commands:
use Instantiate prototype, filling in parameters from flags, and use Instantiate prototype, filling in parameters from flags, and
emitting the generated code to stdout. emitting the generated code to stdout.
describe Display documentation and details about a prototype describe Display documentation and details about a prototype
search Search for a prototype`, search Search for a prototype`,
Example: ` # Display documentation about prototype Example: `# Display documentation about prototype
# 'io.ksonnet.pkg.prototype.simple-deployment', including: # 'io.ksonnet.pkg.prototype.simple-deployment', including:
# #
# (1) a description of what gets generated during instantiation # (1) a description of what gets generated during instantiation
# (2) a list of parameters that are required to be passed in with CLI flags # (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 # NOTE: Many subcommands only require the user to specify enough of the
# identifier to disambiguate it among other known prototypes, which is why # identifier to disambiguate it among other known prototypes, which is why
# 'simple-deployment' is given as argument instead of the fully-qualified # 'simple-deployment' is given as argument instead of the fully-qualified
# name. # name.
ks prototype describe simple-deployment ks prototype describe simple-deployment
# Instantiate prototype 'io.ksonnet.pkg.prototype.simple-deployment', using # Instantiate prototype 'io.ksonnet.pkg.prototype.simple-deployment', using
# the 'nginx' image, and port 80 exposed. # the 'nginx' image, and port 80 exposed.
# #
# SEE ALSO: Note above for a description of why this subcommand can take # SEE ALSO: Note above for a description of why this subcommand can take
# 'simple-deployment' instead of the fully-qualified prototype name. # 'simple-deployment' instead of the fully-qualified prototype name.
ks prototype use simple-deployment \ ks prototype use simple-deployment \
--name=nginx \ --name=nginx \
--image=nginx \ --image=nginx \
--port=80 \ --port=80 \
--portName=http --portName=http
# Search known prototype metadata for the string 'deployment'. # Search known prototype metadata for the string 'deployment'.
ks prototype search deployment`, ks prototype search deployment`,
} }
var prototypeListCmd = &cobra.Command{ var prototypeListCmd = &cobra.Command{
...@@ -173,27 +173,27 @@ var prototypeDescribeCmd = &cobra.Command{ ...@@ -173,27 +173,27 @@ var prototypeDescribeCmd = &cobra.Command{
return nil return nil
}, },
Long: `Output documentation, examples, and other information for some ksonnet 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: includes:
(1) a description of what gets generated during instantiation 1. a description of what gets generated during instantiation
(2) a list of parameters that are required to be passed in with CLI flags 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 disambiguate it among known names. For example, 'deployment' may resolve
ambiguously, in which case 'use' will fail, while 'simple-deployment' might be ambiguously, in which case 'use' will fail, while 'simple-deployment' might be
unique enough to resolve to 'io.ksonnet.pkg.prototype.simple-deployment'.`, unique enough to resolve to 'io.ksonnet.pkg.prototype.simple-deployment'.`,
Example: ` # Display documentation about prototype, including: Example: `# Display documentation about prototype, including:
ks prototype describe io.ksonnet.pkg.prototype.simple-deployment ks prototype describe io.ksonnet.pkg.prototype.simple-deployment
# Display documentation about prototype using a unique suffix of an # Display documentation about prototype using a unique suffix of an
# identifier. That is, this command only requires a long enough suffix to # identifier. That is, this command only requires a long enough suffix to
# uniquely identify a ksonnet prototype. In this example, the suffix # uniquely identify a ksonnet prototype. In this example, the suffix
# 'simple-deployment' is enough to uniquely identify # 'simple-deployment' is enough to uniquely identify
# 'io.ksonnet.pkg.prototype.simple-deployment', but 'deployment' might not # 'io.ksonnet.pkg.prototype.simple-deployment', but 'deployment' might not
# be, as several names end with that suffix. # be, as several names end with that suffix.
ks prototype describe simple-deployment`, ks prototype describe simple-deployment`,
} }
var prototypeSearchCmd = &cobra.Command{ var prototypeSearchCmd = &cobra.Command{
...@@ -218,9 +218,9 @@ var prototypeSearchCmd = &cobra.Command{ ...@@ -218,9 +218,9 @@ var prototypeSearchCmd = &cobra.Command{
return nil return nil
}, },
Long: `Search ksonnet for prototypes whose names contain 'name-substring'.`, Long: `Search ksonnet for prototypes whose names contain` + " `name-substring` " + `.`,
Example: ` # Search known prototype metadata for the string 'deployment'. Example: `# Search known prototype metadata for the string 'deployment'.
ks prototype search deployment`, ks prototype search deployment`,
} }
var prototypePreviewCmd = &cobra.Command{ var prototypePreviewCmd = &cobra.Command{
...@@ -292,25 +292,25 @@ var prototypePreviewCmd = &cobra.Command{ ...@@ -292,25 +292,25 @@ var prototypePreviewCmd = &cobra.Command{
return nil return nil
}, },
Long: `Expand prototype uniquely identified by (possibly partial) 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. 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 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'.`, unique enough to resolve to 'io.ksonnet.pkg.single-port-deployment'.`,
Example: ` # Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the Example: `# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image, and port 80 exposed. # 'nginx' image, and port 80 exposed.
ks prototype preview io.ksonnet.pkg.prototype.simple-deployment \ ks prototype preview io.ksonnet.pkg.prototype.simple-deployment \
--name=nginx \ --name=nginx \
--image=nginx --image=nginx
# Preview prototype using a unique suffix of an identifier. See # Preview prototype using a unique suffix of an identifier. See
# introduction of help message for more information on how this works. # introduction of help message for more information on how this works.
ks prototype preview simple-deployment \ ks prototype preview simple-deployment \
--name=nginx \ --name=nginx \
--image=nginx`, --image=nginx`,
} }
// generateCmd acts as an alias for `prototype use` // generateCmd acts as an alias for `prototype use`
...@@ -397,37 +397,37 @@ var prototypeUseCmd = &cobra.Command{ ...@@ -397,37 +397,37 @@ var prototypeUseCmd = &cobra.Command{
return manager.CreateComponent(componentName, text, params, templateType) 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 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' 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). ksonnet will expand templates as Jsonnet).
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \ ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--name=nginx \ --name=nginx \
--image=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 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'.`, unique enough to resolve to 'io.ksonnet.pkg.single-port-deployment'.`,
Example: ` # Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the Example: `# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in # 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'. # 'components/nginx-depl.jsonnet'.
ks prototype use io.ksonnet.pkg.prototype.simple-deployment nginx-depl \ ks prototype use io.ksonnet.pkg.prototype.simple-deployment nginx-depl \
--name=nginx \ --name=nginx \
--image=nginx --image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the # Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
# unique suffix, 'deployment'. The expanded prototype is again placed in # unique suffix, 'deployment'. The expanded prototype is again placed in
# 'components/nginx-depl.jsonnet'. See introduction of help message for more # 'components/nginx-depl.jsonnet'. See introduction of help message for more
# information on how this works. Note that if you have imported another # information on how this works. Note that if you have imported another
# prototype with this suffix, this may resolve ambiguously for you. # prototype with this suffix, this may resolve ambiguously for you.
ks prototype use deployment nginx-depl \ ks prototype use deployment nginx-depl \
--name=nginx \ --name=nginx \
--image=nginx`, --image=nginx`,
} }
func bindPrototypeFlags(cmd *cobra.Command, proto *prototype.SpecificationSchema) { 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: ...@@ -39,7 +39,7 @@ manage in a ksonnet project using the CLI. A typical library contains:
var registryListCmd = &cobra.Command{ var registryListCmd = &cobra.Command{
Use: "list", 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 { RunE: func(cmd *cobra.Command, args []string) error {
const ( const (
nameHeader = "NAME" nameHeader = "NAME"
...@@ -142,5 +142,5 @@ var registryDescribeCmd = &cobra.Command{ ...@@ -142,5 +142,5 @@ var registryDescribeCmd = &cobra.Command{
}, },
Long: `Output documentation for some ksonnet registry prototype uniquely identified in 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). ...@@ -109,19 +109,19 @@ if they do not exist (default: true).
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`, files.`,
Example: ` # Create or update all resources described in a ksonnet application, and 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 # running in the 'dev' environment. Can be used in any subdirectory of the
# application. # application.
ks update dev ks update dev
# Create or update resources described in a YAML file. Automatically picks up # Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'. # the cluster's location from '$KUBECONFIG'.
ks update -f ./pod.yaml ks update -f ./pod.yaml
# Update resources described in a YAML file, and running in cluster referred # Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'. # to by './kubeconfig'.
ks update --kubeconfig=./kubeconfig -f ./pod.yaml ks update --kubeconfig=./kubeconfig -f ./pod.yaml
# Display set of actions we will execute when we run 'update'. # Display set of actions we will execute when we run 'update'.
ks update dev --dry-run`, ks update dev --dry-run`,
} }
cmd/validate.go
+ 12
− 12
View file @ f808801c
...@@ -72,19 +72,19 @@ specification. ...@@ -72,19 +72,19 @@ specification.
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
files.`, files.`,
Example: ` # Validate all resources described in a ksonnet application, expanding Example: `# Validate all resources described in a ksonnet application, expanding
# ksonnet code with 'dev' environment where necessary (i.e., not YAML, JSON, # ksonnet code with 'dev' environment where necessary (i.e., not YAML, JSON,
# or non-ksonnet Jsonnet code). # or non-ksonnet Jsonnet code).
ksonnet validate dev ksonnet validate dev
# Validate resources described in a YAML file. # Validate resources described in a YAML file.
ksonnet validate -f ./pod.yaml ksonnet validate -f ./pod.yaml
# Validate resources described in the JSON file against existing resources # Validate resources described in the JSON file against existing resources
# in the cluster the 'dev' environment is pointing at. # in the cluster the 'dev' environment is pointing at.
ksonnet validate dev -f ./pod.yaml ksonnet validate dev -f ./pod.yaml
# Validate resources described in a Jsonnet file. Does not expand using # Validate resources described in a Jsonnet file. Does not expand using
# environment bindings. # environment bindings.
ksonnet validate -f ./pod.jsonnet`, 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 ...@@ -6,7 +6,7 @@ Apply local configuration to remote cluster
Update (or optionally create) Kubernetes resources on the cluster using the 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). if they do not exist (default: true).
ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
...@@ -19,25 +19,25 @@ ks apply [env-name] [-f <file-or-dir>] ...@@ -19,25 +19,25 @@ ks apply [env-name] [-f <file-or-dir>]
### Examples ### Examples
``` ```
# Create or update all resources described in a ksonnet application, and # Create or update all resources described in a ksonnet application, and
# running in the 'dev' environment. Can be used in any subdirectory of the # running in the 'dev' environment. Can be used in any subdirectory of the
# application. # application.
ks apply dev ks apply dev
# Create or update resources described in a YAML file. Automatically picks up # Create or update resources described in a YAML file. Automatically picks up
# the cluster's location from '$KUBECONFIG'. # the cluster's location from '$KUBECONFIG'.
ks appy -f ./pod.yaml ks appy -f ./pod.yaml
# Create or update resources described in the JSON file. Changes are deployed # Create or update resources described in the JSON file. Changes are deployed
# to the cluster pointed at the 'dev' environment. # to the cluster pointed at the 'dev' environment.
ks apply dev -f ./pod.json ks apply dev -f ./pod.json
# Update resources described in a YAML file, and running in cluster referred # Update resources described in a YAML file, and running in cluster referred
# to by './kubeconfig'. # to by './kubeconfig'.
ks apply --kubeconfig=./kubeconfig -f ./pod.yaml ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
# Display set of actions we will execute when we run 'apply'. # Display set of actions we will execute when we run 'apply'.
ks apply dev --dry-run ks apply dev --dry-run
``` ```
### Options ### Options
......
docs/cli-reference/ks_delete.md
+ 12
− 12
View file @ f808801c
...@@ -18,21 +18,21 @@ ks delete [env-name] [-f <file-or-dir>] ...@@ -18,21 +18,21 @@ ks delete [env-name] [-f <file-or-dir>]
### Examples ### Examples
``` ```
# Delete all resources described in a ksonnet application, from the 'dev' # Delete all resources described in a ksonnet application, from the 'dev'
# environment. Can be used in any subdirectory of the application. # environment. Can be used in any subdirectory of the application.
ks delete dev ks delete dev
# Delete resources described in a YAML file. Automatically picks up the # Delete resources described in a YAML file. Automatically picks up the
# cluster's location from '$KUBECONFIG'. # cluster's location from '$KUBECONFIG'.
ks delete -f ./pod.yaml ks delete -f ./pod.yaml
# Delete resources described in the JSON file from the 'dev' environment. Can # Delete resources described in the JSON file from the 'dev' environment. Can
# be used in any subdirectory of the application. # be used in any subdirectory of the application.
ks delete dev -f ./pod.json ks delete dev -f ./pod.json
# Delete resources described in a YAML file, and running in the cluster # Delete resources described in a YAML file, and running in the cluster
# specified by the current context in specified kubeconfig file. # specified by the current context in specified kubeconfig file.
ks delete --kubeconfig=./kubeconfig -f ./pod.yaml ks delete --kubeconfig=./kubeconfig -f ./pod.yaml
``` ```
### Options ### Options
......
docs/cli-reference/ks_diff.md
+ 29
− 29
View file @ f808801c
...@@ -18,35 +18,35 @@ ks diff [<env1> [<env2>]] [-f <file-or-dir>] ...@@ -18,35 +18,35 @@ ks diff [<env1> [<env2>]] [-f <file-or-dir>]
### Examples ### Examples
``` ```
# Show diff between resources described in a the local 'dev' environment # Show diff between resources described in a the local 'dev' environment
# specified by the ksonnet application and the remote cluster referenced by # specified by the ksonnet application and the remote cluster referenced by
# the same 'dev' environment. Can be used in any subdirectory of the application. # the same 'dev' environment. Can be used in any subdirectory of the application.
ksonnet diff dev ksonnet diff dev
# Show diff between resources at remote clusters. This requires ksonnet # Show diff between resources at remote clusters. This requires ksonnet
# application defined environments. Diff between the cluster defined at the # application defined environments. Diff between the cluster defined at the
# 'us-west/dev' environment, and the cluster defined at the 'us-west/prod' # 'us-west/dev' environment, and the cluster defined at the 'us-west/prod'
# environment. Can be used in any subdirectory of the application. # environment. Can be used in any subdirectory of the application.
ksonnet diff remote:us-west/dev remote:us-west/prod ksonnet diff remote:us-west/dev remote:us-west/prod
# Show diff between resources at a remote and a local cluster. This requires # Show diff between resources at a remote and a local cluster. This requires
# ksonnet application defined environments. Diff between the cluster defined # ksonnet application defined environments. Diff between the cluster defined
# at the 'us-west/dev' environment, and the cluster defined at the # at the 'us-west/dev' environment, and the cluster defined at the
# 'us-west/prod' environment. Can be used in any subdirectory of the # 'us-west/prod' environment. Can be used in any subdirectory of the
# application. # application.
ksonnet diff local:us-west/dev remote:us-west/prod ksonnet diff local:us-west/dev remote:us-west/prod
# Show diff between resources described in a YAML file and the cluster # Show diff between resources described in a YAML file and the cluster
# referenced in '$KUBECONFIG'. # referenced in '$KUBECONFIG'.
ks diff -f ./pod.yaml ks diff -f ./pod.yaml
# Show diff between resources described in a JSON file and the cluster # Show diff between resources described in a JSON file and the cluster
# referenced by the environment 'dev'. # referenced by the environment 'dev'.
ks diff dev -f ./pod.json ks diff dev -f ./pod.json
# Show diff between resources described in a YAML file and the cluster # Show diff between resources described in a YAML file and the cluster
# referred to by './kubeconfig'. # referred to by './kubeconfig'.
ks diff --kubeconfig=./kubeconfig -f ./pod.yaml ks diff --kubeconfig=./kubeconfig -f ./pod.yaml
``` ```
### Options ### Options
......
docs/cli-reference/ks_env.md
+ 20
− 18
View file @ f808801c
...@@ -6,7 +6,7 @@ Manage ksonnet environments ...@@ -6,7 +6,7 @@ Manage ksonnet environments
An environment acts as a sort of "named cluster", allowing for commands like 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 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 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 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 ...@@ -18,25 +18,27 @@ often contained in a kubeconfig file), and
Environments are represented as a hierarchy in the 'environments' directory of a Environments are represented as a hierarchy in the 'environments' directory of a
ksonnet application. For example, in the example below, there are two ksonnet application. For example, in the example below, there are two
environments: 'default' and 'us-west/staging'. Each contains a cached version of 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. uniquely identifies the cluster.
environments/ environments/
default/ [Default generated environment] default/ [Default generated environment]
.metadata/ .metadata/
k.libsonnet k.libsonnet
k8s.libsonnet k8s.libsonnet
swagger.json swagger.json
spec.json spec.json
default.jsonnet default.jsonnet
us-west/ params.libsonnet
staging/ [Example of user-generated env] us-west/
.metadata/ staging/ [Example of user-generated env]
k.libsonnet .metadata/
k8s.libsonnet k.libsonnet
swagger.json k8s.libsonnet
spec.json [This will contain the API server address of the environment and other environment metadata] swagger.json
staging.jsonnet spec.json [This will contain the API server address of the environment and other environment metadata]
staging.jsonnet
params.libsonnet
``` ```
ks env 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 ...@@ -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 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 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".
For more information on what an environment is and how they work, run 'help For more information on what an environment is and how they work, run `ks help env` .
env'.
Environments are represented as a hierarchy in the 'environments' directory of a 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 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. 'us-west/staging'. `ks env add` will add a similar directory to this environment.
environments/ environments/
default/ [Default generated environment] default/ [Default generated environment]
.metadata/ .metadata/
k.libsonnet k.libsonnet
k8s.libsonnet k8s.libsonnet
swagger.json swagger.json
spec.json spec.json
default.jsonnet default.jsonnet
us-west/ params.libsonnet
staging/ [Example of user-generated env] us-west/
.metadata/ staging/ [Example of user-generated env]
k.libsonnet .metadata/
k8s.libsonnet k.libsonnet
swagger.json k8s.libsonnet
spec.json [This will contain the API server address of the environment and other environment metadata], swagger.json
staging.jsonnet 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> ks env add <env-name>
...@@ -42,20 +43,20 @@ ks env add <env-name> ...@@ -42,20 +43,20 @@ ks env add <env-name>
### Examples ### Examples
``` ```
# Initialize a new staging environment at 'us-west'. # Initialize a new staging environment at 'us-west'.
# The environment will be setup using the current context in your kubecfg file. The directory # 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. # structure rooted at 'us-west' in the documentation above will be generated.
ks env add us-west/staging ks env add us-west/staging
# Initialize a new staging environment at 'us-west' with the namespace 'staging', using # 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'. # 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 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. # Initialize a new environment using the 'dev' context in your kubeconfig file.
ks env add my-env --context=dev ks env add my-env --context=dev
# Initialize a new environment using a server address. # Initialize a new environment using a server address.
ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com
``` ```
### Options ### Options
......
docs/cli-reference/ks_env_rm.md
+ 5
− 9
View file @ f808801c
...@@ -6,11 +6,8 @@ Delete an environment from a ksonnet project ...@@ -6,11 +6,8 @@ Delete an environment from a ksonnet project
Delete an environment from a ksonnet project. This is the same Delete an environment from a ksonnet project. This is the same
as removing the <env-name> environment directory and all files contained. If the as removing the <env-name> environment directory and all files contained. All empty
project exists in a hierarchy (e.g., 'us-east/staging') and deleting the parent directories are also subsequently deleted.
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.
``` ```
ks env rm <env-name> ks env rm <env-name>
...@@ -19,10 +16,9 @@ ks env rm <env-name> ...@@ -19,10 +16,9 @@ ks env rm <env-name>
### Examples ### Examples
``` ```
# Remove the directory 'us-west/staging' and all contents # Remove the directory 'us-west/staging' and all contents in the 'environments'
# in the 'environments' directory. This will also remove the parent directory # directory. This will also remove the parent directory 'us-west' if it is empty.
# 'us-west' if it is empty. ks env rm us-west/staging
ks env rm us-west/staging
``` ```
### Options inherited from parent commands ### 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> ...@@ -16,19 +16,19 @@ ks env set <env-name>
### Examples ### Examples
``` ```
# Updates the API server address of the environment 'us-west/staging'. # Updates the API server address of the environment 'us-west/staging'.
ks env set us-west/staging --server=http://example.com ks env set us-west/staging --server=http://example.com
# Updates the namespace of the environment 'us-west/staging'. # Updates the namespace of the environment 'us-west/staging'.
ks env set us-west/staging --namespace=staging ks env set us-west/staging --namespace=staging
# Updates both the name and the server of the environment 'us-west/staging'. # Updates both the name and the server of the environment 'us-west/staging'.
# Updating the name will update the directory structure in 'environments'. # Updating the name will update the directory structure in 'environments'.
ks env set us-west/staging --server=http://example.com --name=us-east/staging 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 # Updates API server address of the environment 'us-west/staging' based on the
# server in the context 'staging-west' in your kubeconfig file. # server in the context 'staging-west' in your kubeconfig file.
ks env set us-west/staging --context=staging-west ks env set us-west/staging --context=staging-west
``` ```
### Options ### 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 ...@@ -5,20 +5,20 @@ Expand prototype, place in components/ directory of ksonnet app
### Synopsis ### 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 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' 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). ksonnet will expand templates as Jsonnet).
ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \ ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
--name=nginx \ --name=nginx \
--image=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 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'. 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 ...@@ -5,28 +5,24 @@ Initialize a ksonnet project
### Synopsis ### 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: consists of two steps:
1. Generating ksonnet-lib. Users can set flags to generate the library based on 1. Generating ksonnet-lib. Users can set flags to generate the library based on
a variety of data, including server configuration and an OpenAPI a variety of data, including server configuration and an OpenAPI
specification of a Kubernetes build. By default, this is generated from the specification of a Kubernetes build. By default, this is generated from the
capabilities of the cluster specified in the cluster of the current context 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. 2. Generating the following tree in the current directory.
app-name/ app-name/
.gitignore Default .gitignore; can customize VCS .gitignore Default .gitignore; can customize VCS
.ksonnet/ Metadata for ksonnet .ksonnet/ Metadata for ksonnet
envs/ environments/
default/ Default generated environment] default/ [Default generated environment]
k.libsonnet components/ Top-level Kubernetes objects defining application
k8s.libsonnet lib/ user-written .libsonnet files
swagger.json vendor/ part libraries, prototypes
spec.json
components/ Top-level Kubernetes objects defining application
lib/ user-written .libsonnet files
vendor/ mixin libraries, prototypes
``` ```
...@@ -36,22 +32,22 @@ ks init <app-name> ...@@ -36,22 +32,22 @@ ks init <app-name>
### Examples ### Examples
``` ```
# Initialize ksonnet application, using the capabilities of live cluster # Initialize ksonnet application, using the capabilities of live cluster
# specified in the $KUBECONFIG environment variable (specifically: the # specified in the $KUBECONFIG environment variable (specifically: the
# current context) to generate 'ksonnet-lib'. # current context) to generate 'ksonnet-lib'.
ks init app-name ks init app-name
# Initialize ksonnet application, using the OpenAPI specification generated # Initialize ksonnet application, using the OpenAPI specification generated
# in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'. # in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
ks init app-name --api-spec=version:v1.7.1 ks init app-name --api-spec=version:v1.7.1
# Initialize ksonnet application, using an OpenAPI specification file # Initialize ksonnet application, using an OpenAPI specification file
# generated by a build of Kubernetes to generate 'ksonnet-lib'. # generated by a build of Kubernetes to generate 'ksonnet-lib'.
ks init app-name --api-spec=file:swagger.json ks init app-name --api-spec=file:swagger.json
# Initialize ksonnet application, using the context 'dev' from the kubeconfig # Initialize ksonnet application, using the context 'dev' from the kubeconfig
# file. # file.
ks init app-name --context=dev ks init app-name --context=dev
``` ```
### Options ### 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