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|go-template|go-tem‐
117 plate-file|template|templatefile|jsonpath|jsonpath-file.
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 --alsologtostderr=false
231 log to standard error as well as files
232 --application-metrics-count-limit=100
235 Max number of application metrics to store (per container)
236 --as=""
239 Username to impersonate for the operation
240 --as-group=[]
243 Group to impersonate for the operation, this flag can be repeated
244 to specify multiple groups.
245 --azure-container-registry-config=""
248 Path to the file containing Azure container registry configuration
249 information.
250 --boot-id-file="/proc/sys/kernel/random/boot_id"
253 Comma-separated list of files to check for boot-id. Use the first
254 one that exists.
255 --cache-dir="/builddir/.kube/http-cache"
258 Default HTTP cache directory
259 --certificate-authority=""
262 Path to a cert file for the certificate authority
263 --client-certificate=""
266 Path to a client certificate file for TLS
267 --client-key=""
270 Path to a client key file for TLS
271 --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
274 CIDRs opened in GCE firewall for LB traffic proxy health checks
275 --cluster=""
278 The name of the kubeconfig cluster to use
279 --container-hints="/etc/cadvisor/container_hints.json"
282 location of the container hints file
283 --containerd="unix:///var/run/containerd.sock"
286 containerd endpoint
287 --context=""
290 The name of the kubeconfig context to use
291 --default-not-ready-toleration-seconds=300
294 Indicates the tolerationSeconds of the toleration for
295 notReady:NoExecute that is added by default to every pod that does not
296 already have such a toleration.
297 --default-unreachable-toleration-seconds=300
300 Indicates the tolerationSeconds of the toleration for unreach‐
301 able:NoExecute that is added by default to every pod that does not
302 already have such a toleration.
303 --docker="unix:///var/run/docker.sock"
306 docker endpoint
307 --docker-env-metadata-whitelist=""
310 a comma-separated list of environment variable keys that needs to
311 be collected for docker containers
312 --docker-only=false
315 Only report docker containers in addition to root stats
316 --docker-root="/var/lib/docker"
319 DEPRECATED: docker root is read from docker info (this is a fall‐
320 back, default: /var/lib/docker)
321 --docker-tls=false
324 use TLS to connect to docker
325 --docker-tls-ca="ca.pem"
328 path to trusted CA
329 --docker-tls-cert="cert.pem"
332 path to client certificate
333 --docker-tls-key="key.pem"
336 path to private key
337 --enable-load-reader=false
340 Whether to enable cpu load reader
341 --event-storage-age-limit="default=0"
344 Max length of time for which to store events (per type). Value is a
345 comma separated list of key values, where the keys are event types
346 (e.g.: creation, oom) or "default" and the value is a duration. Default
347 is applied to all non-specified event types
348 --event-storage-event-limit="default=0"
351 Max number of events to store (per type). Value is a comma sepa‐
352 rated list of key values, where the keys are event types (e.g.: cre‐
353 ation, oom) or "default" and the value is an integer. Default is
354 applied to all non-specified event types
355 --global-housekeeping-interval=1m0s
358 Interval between global housekeepings
359 --housekeeping-interval=10s
362 Interval between container housekeepings
363 --insecure-skip-tls-verify=false
366 If true, the server's certificate will not be checked for validity.
367 This will make your HTTPS connections insecure
368 --kubeconfig=""
371 Path to the kubeconfig file to use for CLI requests.
372 --log-backtrace-at=:0
375 when logging hits line file:N, emit a stack trace
376 --log-cadvisor-usage=false
379 Whether to log the usage of the cAdvisor container
380 --log-dir=""
383 If non-empty, write log files in this directory
384 --log-file=""
387 If non-empty, use this log file
388 --log-flush-frequency=5s
391 Maximum number of seconds between log flushes
392 --logtostderr=true
395 log to standard error instead of files
396 --machine-id-file="/etc/machine-id,/var/lib/dbus/machine-id"
399 Comma-separated list of files to check for machine-id. Use the
400 first one that exists.
401 --match-server-version=false
404 Require server version to match client version
405 --mesos-agent="127.0.0.1:5051"
408 Mesos agent address
409 --mesos-agent-timeout=10s
412 Mesos agent timeout
413 -n, --namespace=""
416 If present, the namespace scope for this CLI request
417 --password=""
420 Password for basic authentication to the API server
421 --profile="none"
424 Name of profile to capture. One of (none|cpu|heap|goroutine|thread‐
425 create|block|mutex)
426 --profile-output="profile.pprof"
429 Name of the file to write the profile to
430 --request-timeout="0"
433 The length of time to wait before giving up on a single server
434 request. Non-zero values should contain a corresponding time unit (e.g.
435 1s, 2m, 3h). A value of zero means don't timeout requests.
436 -s, --server=""
439 The address and port of the Kubernetes API server
440 --skip-headers=false
443 If true, avoid header prefixes in the log messages
444 --stderrthreshold=2
447 logs at or above this threshold go to stderr
448 --storage-driver-buffer-duration=1m0s
451 Writes in the storage driver will be buffered for this duration,
452 and committed to the non memory backends as a single transaction
453 --storage-driver-db="cadvisor"
456 database name
457 --storage-driver-host="localhost:8086"
460 database host:port
461 --storage-driver-password="root"
464 database password
465 --storage-driver-secure=false
468 use secure connection with database
469 --storage-driver-table="stats"
472 table name
473 --storage-driver-user="root"
476 database username
477 --token=""
480 Bearer token for authentication to the API server
481 --user=""
484 The name of the kubeconfig user to use
485 --username=""
488 Username for basic authentication to the API server
489 -v, --v=0
492 log level for V logs
493 --version=false
496 Print version information and quit
497 --vmodule=
500 comma-separated list of pattern=N settings for file-filtered log‐
501 ging
502
506 # Start a single instance of nginx.
507 kubectl run nginx --image=nginx
508 # Start a single instance of hazelcast and let the container expose port 5701 .
510 kubectl run hazelcast --image=hazelcast --port=5701
511 # Start a single instance of hazelcast and set environment variables "DNS_DOMAIN=cluster" and "POD_NAMESPACE=default" in the container.
513 kubectl run hazelcast --image=hazelcast --env="DNS_DOMAIN=cluster" --env="POD_NAMESPACE=default"
514 # Start a single instance of hazelcast and set labels "app=hazelcast" and "env=prod" in the container.
516 kubectl run hazelcast --image=hazelcast --labels="app=hazelcast,env=prod"
517 # Start a replicated instance of nginx.
519 kubectl run nginx --image=nginx --replicas=5
520 # Dry run. Print the corresponding API objects without creating them.
522 kubectl run nginx --image=nginx --dry-run
523 # Start a single instance of nginx, but overload the spec of the deployment with a partial set of values parsed from JSON.
525 kubectl run nginx --image=nginx --overrides='{ "apiVersion": "v1", "spec": { ... } }'
526 # Start a pod of busybox and keep it in the foreground, don't restart it if it exits.
528 kubectl run -i -t busybox --image=busybox --restart=Never
529 # Start the nginx container using the default command, but use custom arguments (arg1 .. argN) for that command.
531 kubectl run nginx --image=nginx -- <arg1> <arg2> ... <argN>
532 # Start the nginx container using a different command and custom arguments.
534 kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>
535 # Start the perl container to compute π to 2000 places and print it out.
537 kubectl run pi --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)'
538 # Start the cron job to compute π to 2000 places and print it out every 5 minutes.
540 kubectl run pi --schedule="0/5 * * * ?" --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)'
541
546 kubectl(1),
547
551 January 2015, Originally compiled by Eric Paris (eparis at redhat dot
552 com) based on the kubernetes source material, but hopefully they have
553 been automatically generated since!
554Eric Paris kubernetes User Manuals KUBERNETES(1)