1KUBERNETES(1) Jan 2015 KUBERNETES(1)
2
6 kubectl run - Run a particular image on the cluster
7
11 kubectl run [OPTIONS]
12
16 Create and run a particular image, possibly replicated.
17 Creates a deployment or job to manage the created container(s).
20
24 --allow-missing-template-keys=true
25 If true, ignore any errors in templates when a field or map key is
26 missing in the template. Only applies to golang and jsonpath output
27 formats.
28 --attach=false
31 If true, wait for the Pod to start running, and then attach to the
32 Pod as if 'kubectl attach ...' were called. Default false, unless
33 '-i/--stdin' is set, in which case the default is true. With
34 '--restart=Never' the exit code of the container process is returned.
35 --cascade=true
38 If true, cascade the deletion of the resources managed by this
39 resource (e.g. Pods created by a ReplicationController). Default true.
40 --command=false
43 If true and extra arguments are present, use them as the 'command'
44 field in the container, rather than the 'args' field which is the
45 default.
46 --dry-run=false
49 If true, only print the object that would be sent, without sending
50 it.
51 --env=[]
54 Environment variables to set in the container
55 --expose=false
58 If true, a public, external service is created for the container(s)
59 which are run
60 -f, --filename=[]
63 to use to replace the resource.
64 --force=false
67 Only used when grace-period=0. If true, immediately remove
68 resources from API and bypass graceful deletion. Note that immediate
69 deletion of some resources may result in inconsistency or data loss and
70 requires confirmation.
71 --generator=""
74 The name of the API generator to use, see ⟨http://kuber‐
75 netes.io/docs/user-guide/kubectl-conventions/#generators⟩ for a list.
76 --grace-period=-1
79 Period of time in seconds given to the resource to terminate grace‐
80 fully. Ignored if negative. Set to 1 for immediate shutdown. Can only
81 be set to 0 when --force is true (force deletion).
82 --hostport=-1
85 The host port mapping for the container port. To demonstrate a sin‐
86 gle-machine container.
87 --image=""
90 The image for the container to run.
91 --image-pull-policy=""
94 The image pull policy for the container. If left empty, this value
95 will not be specified by the client and defaulted by the server
96 -l, --labels=""
99 Comma separated labels to apply to the pod(s). Will override previ‐
100 ous values.
101 --leave-stdin-open=false
104 If the pod is started in interactive mode or with stdin, leave
105 stdin open after the first attach completes. By default, stdin will be
106 closed after the first attach completes.
107 --limits=""
110 The resource requirement limits for this container. For example,
111 'cpu=200m,memory=512Mi'. Note that server side components may assign
112 limits depending on the server configuration, such as limit ranges.
113 -o, --output=""
116 Output format. One of: json|yaml|name|templatefile|template|go-tem‐
117 plate|go-template-file|jsonpath-file|jsonpath.
118 --overrides=""
121 An inline JSON override for the generated object. If this is
122 non-empty, it is used to override the generated object. Requires that
123 the object supply a valid apiVersion field.
124 --pod-running-timeout=1m0s
127 The length of time (like 5s, 2m, or 3h, higher than zero) to wait
128 until at least one pod is running
129 --port=""
132 The port that this container exposes. If --expose is true, this is
133 also the port used by the service that is created.
134 --quiet=false
137 If true, suppress prompt messages.
138 --record=false
141 Record current kubectl command in the resource annotation. If set
142 to false, do not record the command. If set to true, record the com‐
143 mand. If not set, default to updating the existing annotation value
144 only if one already exists.
145 -R, --recursive=false
148 Process the directory used in -f, --filename recursively. Useful
149 when you want to manage related manifests organized within the same
150 directory.
151 -r, --replicas=1
154 Number of replicas to create for this container. Default is 1.
155 --requests=""
158 The resource requirement requests for this container. For example,
159 'cpu=100m,memory=256Mi'. Note that server side components may assign
160 requests depending on the server configuration, such as limit ranges.
161 --restart="Always"
164 The restart policy for this Pod. Legal values [Always, OnFailure,
165 Never]. If set to 'Always' a deployment is created, if set to 'OnFail‐
166 ure' a job is created, if set to 'Never', a regular pod is created. For
167 the latter two --replicas must be 1. Default 'Always', for CronJobs
168 Never.
169 --rm=false
172 If true, delete resources created in this command for attached con‐
173 tainers.
174 --save-config=false
177 If true, the configuration of current object will be saved in its
178 annotation. Otherwise, the annotation will be unchanged. This flag is
179 useful when you want to perform kubectl apply on this object in the
180 future.
181 --schedule=""
184 A schedule in the Cron format the job should be run with.
185 --service-generator="service/v2"
188 The name of the generator to use for creating a service. Only used
189 if --expose is true
190 --service-overrides=""
193 An inline JSON override for the generated service object. If this
194 is non-empty, it is used to override the generated object. Requires
195 that the object supply a valid apiVersion field. Only used if --expose
196 is true.
197 --serviceaccount=""
200 Service account to set in the pod spec
201 -i, --stdin=false
204 Keep stdin open on the container(s) in the pod, even if nothing is
205 attached.
206 --template=""
209 Template string or path to template file to use when -o=go-tem‐
210 plate, -o=go-template-file. The template format is golang templates [
211 ⟨http://golang.org/pkg/text/template/#pkg-overview⟩].
212 --timeout=0s
215 The length of time to wait before giving up on a delete, zero means
216 determine a timeout from the size of the object
217 -t, --tty=false
220 Allocated a TTY for each container in the pod.
221 --wait=false
224 If true, wait for resources to be gone before returning. This waits
225 for finalizers.
226
230 --allow-verification-with-non-compliant-keys=false
231 Allow a SignatureVerifier to use keys which are technically
232 non-compliant with RFC6962.
233 --alsologtostderr=false
236 log to standard error as well as files
237 --application-metrics-count-limit=100
240 Max number of application metrics to store (per container)
241 --as=""
244 Username to impersonate for the operation
245 --as-group=[]
248 Group to impersonate for the operation, this flag can be repeated
249 to specify multiple groups.
250 --azure-container-registry-config=""
253 Path to the file containing Azure container registry configuration
254 information.
255 --boot-id-file="/proc/sys/kernel/random/boot_id"
258 Comma-separated list of files to check for boot-id. Use the first
259 one that exists.
260 --cache-dir="/builddir/.kube/http-cache"
263 Default HTTP cache directory
264 --certificate-authority=""
267 Path to a cert file for the certificate authority
268 --client-certificate=""
271 Path to a client certificate file for TLS
272 --client-key=""
275 Path to a client key file for TLS
276 --cloud-provider-gce-lb-src-cidrs=130.211.0.0/22,209.85.152.0/22,209.85.204.0/22,35.191.0.0/16
279 CIDRs opened in GCE firewall for LB traffic proxy health checks
280 --cluster=""
283 The name of the kubeconfig cluster to use
284 --container-hints="/etc/cadvisor/container_hints.json"
287 location of the container hints file
288 --containerd="unix:///var/run/containerd.sock"
291 containerd endpoint
292 --context=""
295 The name of the kubeconfig context to use
296 --default-not-ready-toleration-seconds=300
299 Indicates the tolerationSeconds of the toleration for
300 notReady:NoExecute that is added by default to every pod that does not
301 already have such a toleration.
302 --default-unreachable-toleration-seconds=300
305 Indicates the tolerationSeconds of the toleration for unreach‐
306 able:NoExecute that is added by default to every pod that does not
307 already have such a toleration.
308 --docker="unix:///var/run/docker.sock"
311 docker endpoint
312 --docker-env-metadata-whitelist=""
315 a comma-separated list of environment variable keys that needs to
316 be collected for docker containers
317 --docker-only=false
320 Only report docker containers in addition to root stats
321 --docker-root="/var/lib/docker"
324 DEPRECATED: docker root is read from docker info (this is a fall‐
325 back, default: /var/lib/docker)
326 --docker-tls=false
329 use TLS to connect to docker
330 --docker-tls-ca="ca.pem"
333 path to trusted CA
334 --docker-tls-cert="cert.pem"
337 path to client certificate
338 --docker-tls-key="key.pem"
341 path to private key
342 --enable-load-reader=false
345 Whether to enable cpu load reader
346 --event-storage-age-limit="default=0"
349 Max length of time for which to store events (per type). Value is a
350 comma separated list of key values, where the keys are event types
351 (e.g.: creation, oom) or "default" and the value is a duration. Default
352 is applied to all non-specified event types
353 --event-storage-event-limit="default=0"
356 Max number of events to store (per type). Value is a comma sepa‐
357 rated list of key values, where the keys are event types (e.g.: cre‐
358 ation, oom) or "default" and the value is an integer. Default is
359 applied to all non-specified event types
360 --global-housekeeping-interval=1m0s
363 Interval between global housekeepings
364 --google-json-key=""
367 The Google Cloud Platform Service Account JSON Key to use for
368 authentication.
369 --housekeeping-interval=10s
372 Interval between container housekeepings
373 --insecure-skip-tls-verify=false
376 If true, the server's certificate will not be checked for validity.
377 This will make your HTTPS connections insecure
378 --kubeconfig=""
381 Path to the kubeconfig file to use for CLI requests.
382 --log-backtrace-at=:0
385 when logging hits line file:N, emit a stack trace
386 --log-cadvisor-usage=false
389 Whether to log the usage of the cAdvisor container
390 --log-dir=""
393 If non-empty, write log files in this directory
394 --log-flush-frequency=5s
397 Maximum number of seconds between log flushes
398 --logtostderr=true
401 log to standard error instead of files
402 --machine-id-file="/etc/machine-id,/var/lib/dbus/machine-id"
405 Comma-separated list of files to check for machine-id. Use the
406 first one that exists.
407 --match-server-version=false
410 Require server version to match client version
411 --mesos-agent="127.0.0.1:5051"
414 Mesos agent address
415 --mesos-agent-timeout=10s
418 Mesos agent timeout
419 -n, --namespace=""
422 If present, the namespace scope for this CLI request
423 --request-timeout="0"
426 The length of time to wait before giving up on a single server
427 request. Non-zero values should contain a corresponding time unit (e.g.
428 1s, 2m, 3h). A value of zero means don't timeout requests.
429 -s, --server=""
432 The address and port of the Kubernetes API server
433 --stderrthreshold=2
436 logs at or above this threshold go to stderr
437 --storage-driver-buffer-duration=1m0s
440 Writes in the storage driver will be buffered for this duration,
441 and committed to the non memory backends as a single transaction
442 --storage-driver-db="cadvisor"
445 database name
446 --storage-driver-host="localhost:8086"
449 database host:port
450 --storage-driver-password="root"
453 database password
454 --storage-driver-secure=false
457 use secure connection with database
458 --storage-driver-table="stats"
461 table name
462 --storage-driver-user="root"
465 database username
466 --token=""
469 Bearer token for authentication to the API server
470 --user=""
473 The name of the kubeconfig user to use
474 -v, --v=0
477 log level for V logs
478 --version=false
481 Print version information and quit
482 --vmodule=
485 comma-separated list of pattern=N settings for file-filtered log‐
486 ging
487
491 # Start a single instance of nginx.
492 kubectl run nginx --image=nginx
493 # Start a single instance of hazelcast and let the container expose port 5701 .
495 kubectl run hazelcast --image=hazelcast --port=5701
496 # Start a single instance of hazelcast and set environment variables "DNS_DOMAIN=cluster" and "POD_NAMESPACE=default" in the container.
498 kubectl run hazelcast --image=hazelcast --env="DNS_DOMAIN=cluster" --env="POD_NAMESPACE=default"
499 # Start a single instance of hazelcast and set labels "app=hazelcast" and "env=prod" in the container.
501 kubectl run hazelcast --image=hazelcast --labels="app=hazelcast,env=prod"
502 # Start a replicated instance of nginx.
504 kubectl run nginx --image=nginx --replicas=5
505 # Dry run. Print the corresponding API objects without creating them.
507 kubectl run nginx --image=nginx --dry-run
508 # Start a single instance of nginx, but overload the spec of the deployment with a partial set of values parsed from JSON.
510 kubectl run nginx --image=nginx --overrides='{ "apiVersion": "v1", "spec": { ... } }'
511 # Start a pod of busybox and keep it in the foreground, don't restart it if it exits.
513 kubectl run -i -t busybox --image=busybox --restart=Never
514 # Start the nginx container using the default command, but use custom arguments (arg1 .. argN) for that command.
516 kubectl run nginx --image=nginx -- <arg1> <arg2> ... <argN>
517 # Start the nginx container using a different command and custom arguments.
519 kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>
520 # Start the perl container to compute π to 2000 places and print it out.
522 kubectl run pi --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)'
523 # Start the cron job to compute π to 2000 places and print it out every 5 minutes.
525 kubectl run pi --schedule="0/5 * * * ?" --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)'
526
531 kubectl(1),
532
536 January 2015, Originally compiled by Eric Paris (eparis at redhat dot
537 com) based on the kubernetes source material, but hopefully they have
538 been automatically generated since!
539Eric Paris kubernetes User Manuals KUBERNETES(1)