Skip to content

K
k3s
Commit 8276a9e0 authored by Jeff Lowdermilk's avatar Jeff Lowdermilk
Browse files
Options

Merge pull request #4295 from MikeJeffrey/kubectldocs

Clean up kubectl help for auto-gen'd kubectl.md
parents fcee2e16 e5459c88
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 113 additions and 101 deletions
pkg/kubectl/cmd/create.go
View file @ 8276a9e0
......@@ -38,11 +38,12 @@ func (f *Factory) NewCmdCreate(out io.Writer) *cobra.Command {
JSON and YAML formats are accepted.
Examples:
$ kubectl create -f pod.json
<create a pod using the data in pod.json>
$ cat pod.json | kubectl create -f -
<create a pod based on the json passed into stdin>`,
$ kubectl create -f pod.json
// Create a pod using the data in pod.json.
$ cat pod.json | kubectl create -f -
// Create a pod based on the JSON passed into stdin.`,
Run: func(cmd *cobra.Command, args []string) {
schema, err := f.Validator(cmd)
checkErr(err)
......
pkg/kubectl/cmd/delete.go
View file @ 8276a9e0
......@@ -34,8 +34,8 @@ func (f *Factory) NewCmdDelete(out io.Writer) *cobra.Command {
}{}
cmd := &cobra.Command{
Use: "delete ([-f filename] | (<resource> [(<id> | -l <label>)]",
Short: "Delete a resource by filename, stdin or resource and id",
Long: `Delete a resource by filename, stdin, resource and id or by resources and label selector.
Short: "Delete a resource by filename, stdin, or resource and ID.",
Long: `Delete a resource by filename, stdin, resource and ID, or by resources and label selector.
JSON and YAML formats are accepted.
......@@ -47,17 +47,18 @@ submits an update to a resource right when you submit a delete, their update
will be lost along with the rest of the resource.
Examples:
$ kubectl delete -f pod.json
<delete a pod using the type and id pod.json>
$ cat pod.json | kubectl delete -f -
<delete a pod based on the type and id in the json passed into stdin>
$ kubectl delete -f pod.json
// Delete a pod using the type and ID specified in pod.json.
$ kubectl delete pods,services -l name=myLabel
<delete pods and services with label name=myLabel>
$ cat pod.json | kubectl delete -f -
// Delete a pod based on the type and ID in the JSON passed into stdin.
$ kubectl delete pod 1234-56-7890-234234-456456
<delete a pod with ID 1234-56-7890-234234-456456>`,
$ kubectl delete pods,services -l name=myLabel
// Delete pods and services with label name=myLabel.
$ kubectl delete pod 1234-56-7890-234234-456456
// Delete a pod with ID 1234-56-7890-234234-456456.`,
Run: func(cmd *cobra.Command, args []string) {
cmdNamespace, err := f.DefaultNamespace(cmd)
checkErr(err)
......
pkg/kubectl/cmd/expose.go
View file @ 8276a9e0
......@@ -32,15 +32,16 @@ func (f *Factory) NewCmdExposeService(out io.Writer) *cobra.Command {
Short: "Take a replicated application and expose it as Kubernetes Service",
Long: `Take a replicated application and expose it as Kubernetes Service.
Looks up a ReplicationController named <name>, and uses the selector for that replication controller
as the selector for a new Service which services on <port>
Looks up a ReplicationController by name, and uses the selector for that replication controller
as the selector for a new Service on the specified port.
Examples:
$ kubectl expose nginx --port=80 --container-port=8000
<creates a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000>
$ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
<create a service for a replicated streaming application on port 4100 balancing UDP traffic and is named 'video-stream'>
$ kubectl expose nginx --port=80 --container-port=8000
// Creates a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000.
$ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
// Create a service for a replicated streaming application on port 4100 balancing UDP traffic and named 'video-stream'.
`,
Run: func(cmd *cobra.Command, args []string) {
if len(args) != 1 {
......@@ -99,15 +100,15 @@ $ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
},
}
util.AddPrinterFlags(cmd)
cmd.Flags().String("generator", "service/v1", "The name of the api generator that you want to use. Default 'service/v1'")
cmd.Flags().String("protocol", "TCP", "The network protocol for the service you want to be created. Default 'tcp'")
cmd.Flags().String("generator", "service/v1", "The name of the API generator to use. Default is 'service/v1'.")
cmd.Flags().String("protocol", "TCP", "The network protocol for the service to be created. Default is 'tcp'.")
cmd.Flags().Int("port", -1, "The port that the service should serve on. Required.")
cmd.Flags().Bool("create-external-load-balancer", false, "If true, create an external load balancer for this service. Implementation is cloud provider dependent. Default false")
cmd.Flags().String("selector", "", "A label selector to use for this service. If empty (the default) infer the selector from the replication controller")
cmd.Flags().Bool("dry-run", false, "If true, only print the object that would be sent, don't actually do anything")
cmd.Flags().Bool("create-external-load-balancer", false, "If true, create an external load balancer for this service. Implementation is cloud provider dependent. Default is 'false'.")
cmd.Flags().String("selector", "", "A label selector to use for this service. If empty (the default) infer the selector from the replication controller.")
cmd.Flags().Bool("dry-run", false, "If true, only print the object that would be sent, without creating it.")
cmd.Flags().String("container-port", "", "Name or number for the port on the container that the service should direct traffic to. Optional.")
cmd.Flags().String("public-ip", "", "Name of a public ip address to set for the service. The service will be assigned this IP in addition to its generated service IP.")
cmd.Flags().String("overrides", "", "An inline JSON override for the generated object. If this is non-empty, it is parsed used to override the generated object. Requires that the object supply a valid apiVersion field.")
cmd.Flags().String("public-ip", "", "Name of a public IP address to set for the service. The service will be assigned this IP in addition to its generated service IP.")
cmd.Flags().String("overrides", "", "An inline JSON override for the generated object. If this is non-empty, it is used to override the generated object. Requires that the object supply a valid apiVersion field.")
cmd.Flags().String("service-name", "", "The name for the newly created service.")
return cmd
}
pkg/kubectl/cmd/get.go
View file @ 8276a9e0
......@@ -34,28 +34,32 @@ import (
// retrieves one or more resources from a server.
func (f *Factory) NewCmdGet(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "get [(-o|--output=)json|yaml|...] <resource> [<id>]",
Use: "get [(-o|--output=)json|yaml|template|...] <resource> [<id>]",
Short: "Display one or many resources",
Long: `Display one or many resources.
Possible resources include pods (po), replication controllers (rc), services
(se), minions (mi), or events (ev).
If you specify a Go template, you can use any fields defined for the API version
you are connecting to the server with.
By specifying the output as 'template' and providing a Go template as the value
of the --template flag, you can filter the attributes of the fetched resource(s).
Examples:
$ kubectl get pods
<list all pods in ps output format>
$ kubectl get replicationController 1234-56-7890-234234-456456
<list single replication controller in ps output format>
$ kubectl get pods
// List all pods in ps output format.
$ kubectl get -o json pod 1234-56-7890-234234-456456
<list single pod in json output format>
$ kubectl get replicationController 1234-56-7890-234234-456456
// List a single replication controller with specified ID in ps output format.
$ kubectl get rc,services
<list replication controllers and services together in ps output format>`,
$ kubectl get -o json pod 1234-56-7890-234234-456456
// List a single pod in JSON output format.
$ kubectl get -o template pod 1234-56-7890-234234-456456 --template={{.currentState.status}}
// Return only the status value of the specified pod.
$ kubectl get rc,services
// List all replication controllers and services together in ps output format.`,
Run: func(cmd *cobra.Command, args []string) {
RunGet(f, out, cmd, args)
},
......
pkg/kubectl/cmd/log.go
View file @ 8276a9e0
......@@ -28,13 +28,15 @@ func (f *Factory) NewCmdLog(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "log [-f] <pod> [<container>]",
Short: "Print the logs for a container in a pod.",
Long: `Print the logs for a container in a pod. If the pod has only one container, the container name is optional
Long: `Print the logs for a container in a pod. If the pod has only one container, the container name is optional.
Examples:
$ kubectl log 123456-7890 ruby-container
<returns snapshot of ruby-container logs from pod 123456-7890>
$ kubectl log -f 123456-7890 ruby-container
<starts streaming of ruby-container logs from pod 123456-7890>`,
$ kubectl log 123456-7890 ruby-container
// Returns snapshot of ruby-container logs from pod 123456-7890.
$ kubectl log -f 123456-7890 ruby-container
// Starts streaming of ruby-container logs from pod 123456-7890.`,
Run: func(cmd *cobra.Command, args []string) {
if len(args) == 0 {
usageError(cmd, "<pod> is required for log")
......
pkg/kubectl/cmd/proxy.go
View file @ 8276a9e0
......@@ -53,9 +53,9 @@ func (f *Factory) NewCmdProxy(out io.Writer) *cobra.Command {
glog.Fatal(server.Serve(port))
},
}
cmd.Flags().StringP("www", "w", "", "Also serve static files from the given directory under the specified prefix")
cmd.Flags().StringP("www-prefix", "P", "/static/", "Prefix to serve static files under, if static file dir is specified")
cmd.Flags().StringP("api-prefix", "", "/api/", "Prefix to serve the proxied API under")
cmd.Flags().IntP("port", "p", 8001, "The port on which to run the proxy")
cmd.Flags().StringP("www", "w", "", "Also serve static files from the given directory under the specified prefix.")
cmd.Flags().StringP("www-prefix", "P", "/static/", "Prefix to serve static files under, if static file directory is specified.")
cmd.Flags().StringP("api-prefix", "", "/api/", "Prefix to serve the proxied API under.")
cmd.Flags().IntP("port", "p", 8001, "The port on which to run the proxy.")
return cmd
}
pkg/kubectl/cmd/resize.go
View file @ 8276a9e0
......@@ -28,22 +28,21 @@ import (
func (f *Factory) NewCmdResize(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "resize [--resource-version=<version>] [--current-replicas=<count>] --replicas=<count> <resource> <id>",
Short: "Set a new size for a resizable resource (currently only Replication Controllers)",
Long: `Set a new size for a resizable resource (currently only Replication Controllers)
Short: "Set a new size for a Replication Controller.",
Long: `Set a new size for a Replication Controller.
Resize also allows users to specify one or more preconditions for the resize action.
The new size is specified by --replicas=<n>. You can also specify an optional precondition.
The two currently supported options are --current-replicas or --resource-version.
If a precondition is specified, it is validated before the resize is attempted, and it is
guaranteed that the precondition holds true when the resize is sent to the server.
If --current-replicas or --resource-version is specified, it is validated before the
resize is attempted, and it is guaranteed that the precondition holds true when the
resize is sent to the server.
Examples:
$ kubectl resize --replicas=3 replicationcontrollers foo
resized
# will only execute if the current size is 2
$ kubectl resize --current-replicas=2 --replicas=3 replicationcontrollers foo
`,
$ kubectl resize --replicas=3 replicationcontrollers foo
// Resize replication controller named 'foo' to 3.
$ kubectl resize --current-replicas=2 --replicas=3 replicationcontrollers foo
// If the replication controller named foo's current size is 2, resize foo to 3.`,
Run: func(cmd *cobra.Command, args []string) {
count := util.GetFlagInt(cmd, "replicas")
if len(args) != 2 || count < 0 {
......@@ -66,8 +65,8 @@ Examples:
fmt.Fprintf(out, "%s\n", s)
},
}
cmd.Flags().String("resource-version", "", "Precondition for resource version. Requires that the current resource version match this value in order to resize")
cmd.Flags().Int("current-replicas", -1, "Precondition for current size. Requires that the current size of the replication controller match this value in order to resize")
cmd.Flags().Int("replicas", -1, "The new number desired number of replicas. Required.")
cmd.Flags().String("resource-version", "", "Precondition for resource version. Requires that the current resource version match this value in order to resize.")
cmd.Flags().Int("current-replicas", -1, "Precondition for current size. Requires that the current size of the replication controller match this value in order to resize.")
cmd.Flags().Int("replicas", -1, "The new desired number of replicas. Required.")
return cmd
}
pkg/kubectl/cmd/rollingupdate.go
View file @ 8276a9e0
......@@ -35,19 +35,20 @@ const (
func (f *Factory) NewCmdRollingUpdate(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "rollingupdate <old-controller-name> -f <new-controller.json>",
Short: "Perform a rolling update of the given ReplicationController",
Short: "Perform a rolling update of the given ReplicationController.",
Long: `Perform a rolling update of the given ReplicationController.
Replaces named controller with new controller, updating one pod at a time to use the
Replaces the specified controller with new controller, updating one pod at a time to use the
new PodTemplate. The new-controller.json must specify the same namespace as the
existing controller and overwrite at least one (common) label in its replicaSelector.
Examples:
$ kubectl rollingupdate frontend-v1 -f frontend-v2.json
<update pods of frontend-v1 using new controller data in frontend-v2.json>
$ cat frontend-v2.json | kubectl rollingupdate frontend-v1 -f -
<update pods of frontend-v1 using json data passed into stdin>`,
$ kubectl rollingupdate frontend-v1 -f frontend-v2.json
// Update pods of frontend-v1 using new controller data in frontend-v2.json.
$ cat frontend-v2.json | kubectl rollingupdate frontend-v1 -f -
// Update pods of frontend-v1 using JSON data passed into stdin.`,
Run: func(cmd *cobra.Command, args []string) {
filename := util.GetFlagString(cmd, "filename")
if len(filename) == 0 {
......@@ -119,6 +120,6 @@ $ cat frontend-v2.json | kubectl rollingupdate frontend-v1 -f -
cmd.Flags().String("update-period", updatePeriod, `Time to wait between updating pods. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".`)
cmd.Flags().String("poll-interval", pollInterval, `Time delay between polling controller status after update. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".`)
cmd.Flags().String("timeout", timeout, `Max time to wait for a controller to update before giving up. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".`)
cmd.Flags().StringP("filename", "f", "", "Filename or URL to file to use to create the new controller")
cmd.Flags().StringP("filename", "f", "", "Filename or URL to file to use to create the new controller.")
return cmd
}
pkg/kubectl/cmd/run.go
View file @ 8276a9e0
......@@ -31,20 +31,21 @@ func (f *Factory) NewCmdRunContainer(out io.Writer) *cobra.Command {
Use: "run-container <name> --image=<image> [--port=<port>] [--replicas=replicas] [--dry-run=<bool>] [--overrides=<inline-json>]",
Short: "Run a particular image on the cluster.",
Long: `Create and run a particular image, possibly replicated.
Creates a replication controller to manage the created container(s)
Creates a replication controller to manage the created container(s).
Examples:
$ kubectl run-container nginx --image=dockerfile/nginx
<starts a single instance of nginx>
$ kubectl run-container nginx --image=dockerfile/nginx --replicas=5
<starts a replicated instance of nginx>
$ kubectl run-container nginx --image=dockerfile/nginx
// Starts a single instance of nginx.
$ kubectl run-container nginx --image=dockerfile/nginx --dry-run
<just print the corresponding API objects, don't actually send them to the apiserver>
$ kubectl run-container nginx --image=dockerfile/nginx --replicas=5
// Starts a replicated instance of nginx.
$ kubectl run-container nginx --image=dockerfile/nginx --dry-run
// Dry run. Print the corresponding API objects without creating them.
$ kubectl run-container nginx --image=dockerfile/nginx --overrides='{ "apiVersion": "v1beta1", "desiredState": { ... } }'
<start a single instance of nginx, but overload the desired state with a partial set of values parsed from JSON`,
$ kubectl run-container nginx --image=dockerfile/nginx --overrides='{ "apiVersion": "v1beta1", "desiredState": { ... } }'
// Start a single instance of nginx, but overload the desired state with a partial set of values parsed from JSON`,
Run: func(cmd *cobra.Command, args []string) {
if len(args) != 1 {
usageError(cmd, "<name> is required for run-container")
......@@ -87,11 +88,11 @@ Examples:
},
}
util.AddPrinterFlags(cmd)
cmd.Flags().String("generator", "run-container/v1", "The name of the api generator that you want to use. Default 'run-container-controller/v1'")
cmd.Flags().String("image", "", "The image for the container you wish to run.")
cmd.Flags().IntP("replicas", "r", 1, "Number of replicas to create for this container. Default 1")
cmd.Flags().Bool("dry-run", false, "If true, only print the object that would be sent, don't actually do anything")
cmd.Flags().String("overrides", "", "An inline JSON override for the generated object. If this is non-empty, it is parsed used to override the generated object. Requires that the object supply a valid apiVersion field.")
cmd.Flags().String("generator", "run-container/v1", "The name of the API generator to use. Default is 'run-container-controller/v1'.")
cmd.Flags().String("image", "", "The image for the container to run.")
cmd.Flags().IntP("replicas", "r", 1, "Number of replicas to create for this container. Default is 1.")
cmd.Flags().Bool("dry-run", false, "If true, only print the object that would be sent, without sending it.")
cmd.Flags().String("overrides", "", "An inline JSON override for the generated object. If this is non-empty, it is used to override the generated object. Requires that the object supply a valid apiVersion field.")
cmd.Flags().Int("port", -1, "The port that this container exposes.")
cmd.Flags().StringP("labels", "l", "", "Labels to apply to the pod(s) created by this call to run-container.")
return cmd
......
pkg/kubectl/cmd/stop.go
View file @ 8276a9e0
......@@ -27,15 +27,16 @@ import (
func (f *Factory) NewCmdStop(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "stop <resource> <id>",
Short: "Gracefully shutdown a resource",
Long: `Gracefully shutdown a resource
Short: "Gracefully shut down a resource.",
Long: `Gracefully shut down a resource.
Attempts to shutdown and delete a resource that supports graceful termination.
Attempts to shut down and delete a resource that supports graceful termination.
If the resource is resizable it will be resized to 0 before deletion.
Examples:
$ kubectl stop replicationcontroller foo
foo stopped
$ kubectl stop replicationcontroller foo
// Shut down foo.
`,
Run: func(cmd *cobra.Command, args []string) {
if len(args) != 2 {
......
pkg/kubectl/cmd/update.go
View file @ 8276a9e0
......@@ -32,20 +32,21 @@ func (f *Factory) NewCmdUpdate(out io.Writer) *cobra.Command {
}{}
cmd := &cobra.Command{
Use: "update -f filename",
Short: "Update a resource by filename or stdin",
Short: "Update a resource by filename or stdin.",
Long: `Update a resource by filename or stdin.
JSON and YAML formats are accepted.
Examples:
$ kubectl update -f pod.json
<update a pod using the data in pod.json>
$ cat pod.json | kubectl update -f -
<update a pod based on the json passed into stdin>
$ kubectl update -f pod.json
// Update a pod using the data in pod.json.
$ kubectl update pods my-pod --patch='{ "apiVersion": "v1beta1", "desiredState": { "manifest": [{ "cpu": 100 }]}}'
<update a pod by downloading it, applying the patch, then updating, requires apiVersion be specified>`,
$ cat pod.json | kubectl update -f -
// Update a pod based on the JSON passed into stdin.
$ kubectl update pods my-pod --patch='{ "apiVersion": "v1beta1", "desiredState": { "manifest": [{ "cpu": 100 }]}}'
// Update a pod by downloading it, applying the patch, then updating. Requires apiVersion be specified.`,
Run: func(cmd *cobra.Command, args []string) {
schema, err := f.Validator(cmd)
checkErr(err)
......@@ -97,8 +98,8 @@ Examples:
},
}
cmd.Flags().VarP(&flags.Filenames, "filename", "f", "Filename, directory, or URL to file to use to update the resource")
cmd.Flags().String("patch", "", "A JSON document to override the existing resource. The resource is downloaded, then patched with the JSON, the updated")
cmd.Flags().VarP(&flags.Filenames, "filename", "f", "Filename, directory, or URL to file to use to update the resource.")
cmd.Flags().String("patch", "", "A JSON document to override the existing resource. The resource is downloaded, patched with the JSON, then updated.")
return cmd
}
......
pkg/kubectl/cmd/util/printing.go
View file @ 8276a9e0
......@@ -23,9 +23,9 @@ import (
)
func AddPrinterFlags(cmd *cobra.Command) {
cmd.Flags().StringP("output", "o", "", "Output format: json|yaml|template|templatefile")
cmd.Flags().String("output-version", "", "Output the formatted object with the given version (default api-version)")
cmd.Flags().Bool("no-headers", false, "When using the default output, don't print headers")
cmd.Flags().StringP("output", "o", "", "Output format. One of: json|yaml|template|templatefile.")
cmd.Flags().String("output-version", "", "Output the formatted object with the given version (default api-version).")
cmd.Flags().Bool("no-headers", false, "When using the default output, don't print headers.")
cmd.Flags().StringP("template", "t", "", "Template string or path to template file to use when -o=template or -o=templatefile.")
}
......
pkg/kubectl/cmd/version.go
View file @ 8276a9e0
......@@ -28,7 +28,7 @@ import (
func (f *Factory) NewCmdVersion(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "version",
Short: "Print version of client and server",
Short: "Print the client and server version information.",
Run: func(cmd *cobra.Command, args []string) {
if util.GetFlagBool(cmd, "client") {
kubectl.GetClientVersion(out)
......@@ -41,6 +41,6 @@ func (f *Factory) NewCmdVersion(out io.Writer) *cobra.Command {
kubectl.GetVersion(out, client)
},
}
cmd.Flags().BoolP("client", "c", false, "Client version only (no server required)")
cmd.Flags().BoolP("client", "c", false, "Client version only (no server required).")
return cmd
}
Markdown is supported
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