Merge pull request #4295 from MikeJeffrey/kubectldocs

Clean up kubectl help for auto-gen'd kubectl.md
This commit is contained in:
Jeff Lowdermilk
2015-02-11 09:41:30 -08:00
14 changed files with 240 additions and 216 deletions

View File

@@ -5,7 +5,7 @@ kubectl controls the Kubernetes cluster manager
### Commands
#### version
Print version of client and server
Print the client and server version information.
Usage:
```
@@ -16,7 +16,7 @@ Usage:
--api-version="": The API version to use when talking to the server
-a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https.
--certificate-authority="": Path to a cert. file for the certificate authority.
-c, --client=false: Client version only (no server required)
-c, --client=false: Client version only (no server required).
--client-certificate="": Path to a client key file for TLS.
--client-key="": Path to a client key file for TLS.
--cluster="": The name of the kubeconfig cluster to use
@@ -49,7 +49,7 @@ Usage:
Available Flags:
--alsologtostderr=false: log to standard error as well as files
--api-prefix="/api/": Prefix to serve the proxied API under
--api-prefix="/api/": Prefix to serve the proxied API under.
--api-version="": The API version to use when talking to the server
-a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https.
--certificate-authority="": Path to a cert. file for the certificate authority.
@@ -66,7 +66,7 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
-p, --port=8001: The port on which to run the proxy
-p, --port=8001: The port on which to run the proxy.
-s, --server="": The address of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
--token="": Bearer token for authentication to the API server.
@@ -74,8 +74,8 @@ Usage:
--v=0: log level for V logs
--validate=false: If true, use a schema to validate the input before sending it
--vmodule=: comma-separated list of pattern=N settings for file-filtered logging
-w, --www="": Also serve static files from the given directory under the specified prefix
-P, --www-prefix="/static/": Prefix to serve static files under, if static file dir is specified
-w, --www="": Also serve static files from the given directory under the specified prefix.
-P, --www-prefix="/static/": Prefix to serve static files under, if static file directory is specified.
```
@@ -85,25 +85,29 @@ 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.
Usage:
```
kubectl get [(-o|--output=)json|yaml|...] <resource> [<id>] [flags]
kubectl get [(-o|--output=)json|yaml|template|...] <resource> [<id>] [flags]
Available Flags:
--alsologtostderr=false: log to standard error as well as files
@@ -123,9 +127,9 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
--no-headers=false: When using the default output, don't print headers
-o, --output="": Output format: json|yaml|template|templatefile
--output-version="": Output the formatted object with the given version (default api-version)
--no-headers=false: When using the default output, don't print headers.
-o, --output="": Output format. One of: json|yaml|template|templatefile.
--output-version="": Output the formatted object with the given version (default api-version).
-l, --selector="": Selector (label query) to filter on
-s, --server="": The address of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
@@ -183,11 +187,12 @@ Create a resource by filename or stdin.
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.
Usage:
```
@@ -228,14 +233,15 @@ 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.
Usage:
```
@@ -250,7 +256,7 @@ Usage:
--client-key="": Path to a client key file for TLS.
--cluster="": The name of the kubeconfig cluster to use
--context="": The name of the kubeconfig context to use
-f, --filename=[]: Filename, directory, or URL to file to use to update the resource
-f, --filename=[]: Filename, directory, or URL to file to use to update the resource.
-h, --help=false: help for update
--insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
--kubeconfig="": Path to the kubeconfig file to use for CLI requests.
@@ -260,7 +266,7 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
--patch="": A JSON document to override the existing resource. The resource is downloaded, then patched with the JSON, the updated
--patch="": A JSON document to override the existing resource. The resource is downloaded, patched with the JSON, then updated.
-s, --server="": The address of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
--token="": Bearer token for authentication to the API server.
@@ -272,7 +278,7 @@ Usage:
```
#### delete
Delete a resource by filename, stdin, resource and id or by resources and label selector.
Delete a resource by filename, stdin, resource and ID, or by resources and label selector.
JSON and YAML formats are accepted.
@@ -284,17 +290,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.
Usage:
```
@@ -376,20 +383,20 @@ Available Commands:
--vmodule=: comma-separated list of pattern=N settings for file-filtered logging
Additional help topics:
kubectl version Print version of client and server
kubectl version Print the client and server version information.
kubectl proxy Run a proxy to the Kubernetes API server
kubectl get Display one or many resources
kubectl describe Show details of a specific resource
kubectl create Create a resource by filename or stdin
kubectl update Update a resource by filename or stdin
kubectl delete Delete a resource by filename, stdin or resource and id
kubectl update Update a resource by filename or stdin.
kubectl delete Delete a resource by filename, stdin, or resource and ID.
kubectl config config modifies .kubeconfig files
kubectl namespace SUPERCEDED: Set and view the current Kubernetes namespace
kubectl log Print the logs for a container in a pod.
kubectl rollingupdate Perform a rolling update of the given ReplicationController
kubectl resize Set a new size for a resizable resource (currently only Replication Controllers)
kubectl rollingupdate Perform a rolling update of the given ReplicationController.
kubectl resize Set a new size for a Replication Controller.
kubectl run-container Run a particular image on the cluster.
kubectl stop Gracefully shutdown a resource
kubectl stop Gracefully shut down a resource.
kubectl expose Take a replicated application and expose it as Kubernetes Service
kubectl label Update the labels on a resource
@@ -431,9 +438,9 @@ Usage:
--match-server-version=false: Require server version to match client version
--merge=true: merge together the full hierarchy of .kubeconfig files
--namespace="": If present, the namespace scope for this CLI request.
--no-headers=false: When using the default output, don't print headers
-o, --output="": Output format: json|yaml|template|templatefile
--output-version="": Output the formatted object with the given version (default api-version)
--no-headers=false: When using the default output, don't print headers.
-o, --output="": Output format. One of: json|yaml|template|templatefile.
--output-version="": Output the formatted object with the given version (default api-version).
-s, --server="": The address of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
-t, --template="": Template string or path to template file to use when -o=template or -o=templatefile.
@@ -734,13 +741,15 @@ Usage:
```
#### log
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>
Print the logs for a container in a pod. If the pod has only one container, the container name is optional.
$ kubectl log -f 123456-7890 ruby-container
<starts streaming of ruby-container logs from pod 123456-7890>
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.
Usage:
```
@@ -778,16 +787,17 @@ Usage:
#### rollingupdate
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.
Usage:
```
@@ -802,7 +812,7 @@ Usage:
--client-key="": Path to a client key file for TLS.
--cluster="": The name of the kubeconfig cluster to use
--context="": The name of the kubeconfig context to use
-f, --filename="": Filename or URL to file to use to create the new controller
-f, --filename="": Filename or URL to file to use to create the new controller.
-h, --help=false: help for rollingupdate
--insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
--kubeconfig="": Path to the kubeconfig file to use for CLI requests.
@@ -826,21 +836,20 @@ Usage:
```
#### resize
Set a new size for a resizable resource (currently only Replication Controllers)
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.
Usage:
```
@@ -855,7 +864,7 @@ Usage:
--client-key="": Path to a client key file for TLS.
--cluster="": The name of the kubeconfig cluster to use
--context="": The name of the kubeconfig context to use
--current-replicas=-1: Precondition for current size. Requires that the current size of the replication controller match this value in order to resize
--current-replicas=-1: Precondition for current size. Requires that the current size of the replication controller match this value in order to resize.
-h, --help=false: help for resize
--insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
--kubeconfig="": Path to the kubeconfig file to use for CLI requests.
@@ -865,8 +874,8 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
--replicas=-1: The new number desired number of replicas. Required.
--resource-version="": Precondition for resource version. Requires that the current resource version match this value in order to resize
--replicas=-1: The new desired number of replicas. Required.
--resource-version="": Precondition for resource version. Requires that the current resource version match this value in order to resize.
-s, --server="": The address of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
--token="": Bearer token for authentication to the API server.
@@ -879,20 +888,21 @@ Usage:
#### run-container
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
Usage:
```
@@ -907,10 +917,10 @@ Usage:
--client-key="": Path to a client key file for TLS.
--cluster="": The name of the kubeconfig cluster to use
--context="": The name of the kubeconfig context to use
--dry-run=false: If true, only print the object that would be sent, don't actually do anything
--generator="run-container/v1": The name of the api generator that you want to use. Default 'run-container-controller/v1'
--dry-run=false: If true, only print the object that would be sent, without sending it.
--generator="run-container/v1": The name of the API generator to use. Default is 'run-container-controller/v1'.
-h, --help=false: help for run-container
--image="": The image for the container you wish to run.
--image="": The image for the container to run.
--insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
--kubeconfig="": Path to the kubeconfig file to use for CLI requests.
-l, --labels="": Labels to apply to the pod(s) created by this call to run-container.
@@ -920,12 +930,12 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
--no-headers=false: When using the default output, don't print headers
-o, --output="": Output format: json|yaml|template|templatefile
--output-version="": Output the formatted object with the given version (default api-version)
--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.
--no-headers=false: When using the default output, don't print headers.
-o, --output="": Output format. One of: json|yaml|template|templatefile.
--output-version="": Output the formatted object with the given version (default api-version).
--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.
--port=-1: The port that this container exposes.
-r, --replicas=1: Number of replicas to create for this container. Default 1
-r, --replicas=1: Number of replicas to create for this container. Default is 1.
-s, --server="": The address of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
-t, --template="": Template string or path to template file to use when -o=template or -o=templatefile.
@@ -938,14 +948,15 @@ Usage:
```
#### stop
Gracefully shutdown a resource
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.
Usage:
@@ -982,15 +993,16 @@ Usage:
#### expose
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'.
Usage:
@@ -1007,9 +1019,9 @@ Usage:
--cluster="": The name of the kubeconfig cluster to use
--container-port="": Name or number for the port on the container that the service should direct traffic to. Optional.
--context="": The name of the kubeconfig context to use
--create-external-load-balancer=false: If true, create an external load balancer for this service. Implementation is cloud provider dependent. Default false
--dry-run=false: If true, only print the object that would be sent, don't actually do anything
--generator="service/v1": The name of the api generator that you want to use. Default 'service/v1'
--create-external-load-balancer=false: If true, create an external load balancer for this service. Implementation is cloud provider dependent. Default is 'false'.
--dry-run=false: If true, only print the object that would be sent, without creating it.
--generator="service/v1": The name of the API generator to use. Default is 'service/v1'.
-h, --help=false: help for expose
--insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
--kubeconfig="": Path to the kubeconfig file to use for CLI requests.
@@ -1019,14 +1031,14 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
--no-headers=false: When using the default output, don't print headers
-o, --output="": Output format: json|yaml|template|templatefile
--output-version="": Output the formatted object with the given version (default api-version)
--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.
--no-headers=false: When using the default output, don't print headers.
-o, --output="": Output format. One of: json|yaml|template|templatefile.
--output-version="": Output the formatted object with the given version (default api-version).
--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.
--port=-1: The port that the service should serve on. Required.
--protocol="TCP": The network protocol for the service you want to be created. Default 'tcp'
--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.
--selector="": A label selector to use for this service. If empty (the default) infer the selector from the replication controller
--protocol="TCP": The network protocol for the service to be created. Default is 'tcp'.
--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.
--selector="": A label selector to use for this service. If empty (the default) infer the selector from the replication controller.
-s, --server="": The address of the Kubernetes API server
--service-name="": The name for the newly created service.
--stderrthreshold=2: logs at or above this threshold go to stderr
@@ -1080,9 +1092,9 @@ Usage:
--logtostderr=true: log to standard error instead of files
--match-server-version=false: Require server version to match client version
--namespace="": If present, the namespace scope for this CLI request.
--no-headers=false: When using the default output, don't print headers
-o, --output="": Output format: json|yaml|template|templatefile
--output-version="": Output the formatted object with the given version (default api-version)
--no-headers=false: When using the default output, don't print headers.
-o, --output="": Output format. One of: json|yaml|template|templatefile.
--output-version="": Output the formatted object with the given version (default api-version).
--overwrite=false: If true, allow labels to be overwritten, otherwise reject label updates that overwrite existing labels.
--resource-version="": If non-empty, the labels update will only succeed if this is the current resource-version for the object.
-s, --server="": The address of the Kubernetes API server