diff --git a/.travis.yml b/.travis.yml index 29d616121be12..e5a30c6dc05d5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,6 +16,7 @@ install: script: - KUBE_RACE="-race" KUBE_COVER="-cover -covermode=atomic" KUBE_TIMEOUT='-timeout 60s' ./hack/test-go.sh - PATH=$HOME/gopath/bin:./third_party/etcd:$PATH ./hack/test-cmd.sh + - PATH=$HOME/gopath/bin:./third_party/etcd:$PATH ./hack/verify-gendocs.sh - PATH=$HOME/gopath/bin:./third_party/etcd:$PATH ./hack/test-integration.sh notifications: diff --git a/cmd/gendocs/gen_kubectl_docs.go b/cmd/gendocs/gen_kubectl_docs.go new file mode 100644 index 0000000000000..d6490b48ac6dc --- /dev/null +++ b/cmd/gendocs/gen_kubectl_docs.go @@ -0,0 +1,58 @@ +/* +Copyright 2014 Google Inc. All rights reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package main + +import ( + "fmt" + "io" + "os" + + "github.com/GoogleCloudPlatform/kubernetes/pkg/kubectl/cmd" + "github.com/spf13/cobra" +) + +func main() { + out := os.Stdout + // Set environment variables used by kubectl so the output is consistent, + // regardless of where we run. + os.Setenv("HOME", "/home/username") + kubectl := cmd.NewFactory().NewKubectlCommand(out) + fmt.Fprintf(out, "## %s\n\n", kubectl.Name()) + fmt.Fprintf(out, "%s\n\n", kubectl.Short) + fmt.Fprintln(out, "### Commands\n") + for _, c := range kubectl.Commands() { + genMarkdown(c, nil, out) + } +} + +func genMarkdown(command, parent *cobra.Command, out io.Writer) { + name := command.Name() + if parent != nil { + name = fmt.Sprintf("%s %s", parent.Name(), name) + } + fmt.Fprintf(out, "#### %s\n", name) + desc := command.Long + if len(desc) == 0 { + desc = command.Short + } + fmt.Fprintf(out, "%s\n\n", desc) + usage := command.UsageString() + fmt.Fprintf(out, "Usage:\n```\n%s\n```\n\n", usage[9:len(usage)-1]) + for _, c := range command.Commands() { + genMarkdown(c, command, out) + } +} diff --git a/docs/cli.md b/docs/cli.md index faec73a8d2a73..4ba9ee3057e4c 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,410 +1,7 @@ ## kubectl The ```kubectl``` command provides command line access to the kubernetes API. -### Commands - -#### version -Print the version of the client and server. - -Usage: -``` - kubectl version [flags] - - Available Flags: - --api-version="v1beta1": The version of the API to use against the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": Path to the auth info file. If missing, prompt the user. Only used if using https. - --certificate-authority="": Path to a certificate file for the certificate authority - -c, --client=false: Client version only (no server required) - --client-certificate="": Path to a client certificate for TLS. - --client-key="": Path to a client key file for TLS. - -h, --help=false: help for version - --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -s, --server="": Kubernetes apiserver to connect to - - -Use "kubectl help [command]" for more information about that command. -``` - -#### proxy -Create a local proxy to the API server - -Usage: -``` - kubectl proxy [flags] - - Available Flags: - --api-version="v1beta1": The API version to use when talking to the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": 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. - --client-certificate=: Path to a client key file for TLS. - --client-key=: Path to a client key file for TLS. - -h, --help=false: help for proxy - --insecure-skip-tls-verify=%!s(bool=false): If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -p, --port=8001: The port on which to run the proxy - -s, --server="": The address of the Kubernetes API server - --token=: Bearer token for authentication to the API server. - --validate=false: If true, use a schema to validate the input before sending it - -w, --www="": Also serve static files from the given directory under the prefix /static -``` - -#### get -Display one or more 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. - -Examples: -```sh - $ kubectl get pods - - - $ kubectl get replicationController 1234-56-7890-234234-456456 - - - $ kubectl get -o json pod 1234-56-7890-234234-456456 - -``` -Usage: -``` - kubectl get [(-o|--output=)json|yaml|...] [] [flags] - - Available Flags: - --api-version="v1beta1": The API version to use when talking to the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": 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. - --client-certificate=: Path to a client key file for TLS. - --client-key=: Path to a client key file for TLS. - -h, --help=false: help for get - --insecure-skip-tls-verify=%!s(bool=false): If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --no-headers=false: When using the default output, don't print headers - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -o, --output="": Output format: 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 - -t, --template="": Template string or path to template file to use when --output=template or --output=templatefile - --token=: Bearer token for authentication to the API server. - --validate=false: If true, use a schema to validate the input before sending it - -w, --watch=false: After listing/getting the requested object, watch for changes. - --watch-only=false: Watch for changes to the requseted object(s), without listing/getting first. -``` - -#### describe -Show details of a specific resource. - -This command joins many API calls together to form a detailed description of a -given resource. - -Usage: -``` - kubectl describe [flags] - - Available Flags: - --api-version="v1beta1": The API version to use when talking to the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": 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. - --client-certificate=: Path to a client key file for TLS. - --client-key=: Path to a client key file for TLS. - -h, --help=false: help for describe - --insecure-skip-tls-verify=%!s(bool=false): If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -s, --server="": The address of the Kubernetes API server - --token=: Bearer token for authentication to the API server. - --validate=false: If true, use a schema to validate the input before sending it -``` - -### run-container -Easily run one or more replicas of an image. - -Creates a replica controller running the specified image, with one or more replicas. - -Examples: -```sh - $ kubectl run-container nginx --image=dockerfile/nginx - - - $ kubectl run-container nginx --image=dockerfile/nginx --replicas=5 - - - $ kubectl run-container nginx --image=dockerfile/nginx --dry-run - - -Usage: - kubectl run-container --image= [--replicas=replicas] [--dry-run=] [flags] - - Available Flags: - --alsologtostderr=false: log to standard error as well as files - --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. - --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 - --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-controller-v1": The name of the api generator that you want to use. Default 'run-container-controller-v1' - -h, --help=false: help for run-container - --image="": The image for the container you wish 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. - --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace - --log_dir=: If non-empty, write log files in this directory - --log_flush_frequency=5s: Maximum number of seconds between log flushes - --logtostderr=true: log to standard error instead of files - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --no-headers=false: When using the default output, don't print headers - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -o, --output="": Output format: json|yaml|template|templatefile - --output-version="": Output the formatted object with the given version (default api-version) - -r, --replicas=1: Number of replicas to create for this container. Default 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. - --token="": Bearer token for authentication to the API server. - --user="": The name of the kubeconfig user to use - --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 $ kubectl run nginx dockerfile/nginx - -``` - - -#### create -Create a resource by filename or stdin. - -JSON and YAML formats are accepted. - -Examples: -```sh - $ kubectl create -f pod.json - - - $ cat pod.json | kubectl create -f - - -``` -Usage: -``` - kubectl create -f filename [flags] - - Available Flags: - --api-version="v1beta1": The API version to use when talking to the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": 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. - --client-certificate=: Path to a client key file for TLS. - --client-key=: Path to a client key file for TLS. - -f, --filename="": Filename or URL to file to use to create the resource - -h, --help=false: help for create - --insecure-skip-tls-verify=%!s(bool=false): If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -s, --server="": The address of the Kubernetes API server - --token=: Bearer token for authentication to the API server. - --validate=false: If true, use a schema to validate the input before sending it -``` - -#### createall -Create all resources contained in JSON file specified in a directory, filename or stdin - -JSON and YAML formats are accepted. - -Examples: -```sh - $ kubectl createall -d configs/ - - - $ kubectl createall -f config.json - - - $ cat config.json | kubectl apply -f - - -``` -Usage: -``` - kubectl createall [-d directory] [-f filename] [flags] - - Available Flags: - --api-version="v1beta1": The API version to use when talking to the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": 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. - --client-certificate=: Path to a client key file for TLS. - --client-key=: Path to a client key file for TLS. - -d, --directory="": Directory of JSON or YAML files to use to update the resource - -f, --filename="": Filename or URL to file to use to update the resource - -h, --help=false: help for createall - --insecure-skip-tls-verify=%!s(bool=false): If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -s, --server="": The address of the Kubernetes API server - --token=: Bearer token for authentication to the API server. - --validate=false: If true, use a schema to validate the input before sending it -``` - -#### update -Update a resource by filename or stdin. - -JSON and YAML formats are accepted. - -Examples: -```sh - $ kubectl update -f pod.json - - - $ cat pod.json | kubectl update -f - - -``` - -Usage: -``` - kubectl update -f filename [flags] - - Available Flags: - --api-version="v1beta1": The API version to use when talking to the server - -a, --auth-path="/Users/bburns/.kubernetes_auth": 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. - --client-certificate=: Path to a client key file for TLS. - --client-key=: Path to a client key file for TLS. - -f, --filename="": Filename or URL to file to use to update the resource - -h, --help=false: help for update - --insecure-skip-tls-verify=%!s(bool=false): If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. - --match-server-version=false: Require server version to match client version - -n, --namespace="": If present, the namespace scope for this CLI request. - --ns-path="/Users/bburns/.kubernetes_ns": Path to the namespace info file that holds the namespace context to use for CLI requests. - -s, --server="": The address of the Kubernetes API server - --token=: Bearer token for authentication to the API server. - --validate=false: If true, use a schema to validate the input before sending it -``` - -#### delete -Delete a resource by filename, stdin, resource and id or by resources and label selector. - -JSON and YAML formats are accepted. - -If both a filename and command line arguments are passed, the command line -arguments are used and the filename is ignored. - -Note that the delete command does NOT do resource version checks, so if someone -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: -```sh - $ kubectl delete -f pod.json - - - $ cat pod.json | kubectl delete -f - - - - $ kubectl delete pods,services -l name=myLabel - - - $ kubectl delete pod 1234-56-7890-234234-456456 - -``` - -Usage: -``` - kubectl delete ([-f filename] | ( [( | -l