diff --git a/docs/kubectl.md b/docs/kubectl.md index 8598f41a7d3..354ce068b1f 100644 --- a/docs/kubectl.md +++ b/docs/kubectl.md @@ -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 - - $ kubectl get replicationController 1234-56-7890-234234-456456 - + $ kubectl get pods + // List all pods in ps output format. - $ kubectl get -o json pod 1234-56-7890-234234-456456 - + $ kubectl get replicationController 1234-56-7890-234234-456456 + // List a single replication controller with specified ID in ps output format. - $ kubectl get rc,services - + $ 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|...] [] [flags] + kubectl get [(-o|--output=)json|yaml|template|...] [] [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 - - $ cat pod.json | kubectl create -f - - + $ 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 - - $ cat pod.json | kubectl update -f - - + $ 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 }]}}' - + $ 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 - - $ cat pod.json | kubectl delete -f - - + $ kubectl delete -f pod.json + // Delete a pod using the type and ID specified in pod.json. - $ kubectl delete pods,services -l 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 - + $ 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 - +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 - +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 - -$ cat frontend-v2.json | kubectl rollingupdate frontend-v1 -f - - + $ 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=. 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 - - $ kubectl run-container nginx --image=dockerfile/nginx --replicas=5 - + $ kubectl run-container nginx --image=dockerfile/nginx + // Starts a single instance of nginx. - $ kubectl run-container nginx --image=dockerfile/nginx --dry-run - + $ 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": { ... } }' - , and uses the selector for that replication controller -as the selector for a new Service which services on +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 - -$ kubectl expose streamer --port=4100 --protocol=udp --service-name=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 diff --git a/pkg/kubectl/cmd/create.go b/pkg/kubectl/cmd/create.go index 7636985b1e0..9b8fac91b24 100644 --- a/pkg/kubectl/cmd/create.go +++ b/pkg/kubectl/cmd/create.go @@ -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 - - $ cat pod.json | kubectl create -f - - `, + $ 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) diff --git a/pkg/kubectl/cmd/delete.go b/pkg/kubectl/cmd/delete.go index 26a1b21e5cf..268f849b5c8 100644 --- a/pkg/kubectl/cmd/delete.go +++ b/pkg/kubectl/cmd/delete.go @@ -34,8 +34,8 @@ func (f *Factory) NewCmdDelete(out io.Writer) *cobra.Command { }{} cmd := &cobra.Command{ Use: "delete ([-f filename] | ( [( | -l