1KUBERNETES(1)(kubernetes)                            KUBERNETES(1)(kubernetes)
2
3
4
5Eric Paris Jan 2015
6
7

NAME

9       kubectl run - Run a particular image on the cluster
10
11
12

SYNOPSIS

14       kubectl run [OPTIONS]
15
16
17

DESCRIPTION

19       Create and run a particular image in a pod.
20
21
22

OPTIONS

24       --allow-missing-template-keys=true       If  true, ignore any errors in
25       templates when a field or map key is missing in the template. Only  ap‐
26       plies to golang and jsonpath output formats.
27
28
29       --annotations=[]      Annotations to apply to the pod.
30
31
32       --attach=false       If  true,  wait  for the Pod to start running, and
33       then attach to the Pod as if 'kubectl attach ...' were called.  Default
34       false,  unless  '-i/--stdin' is set, in which case the default is true.
35       With '--restart=Never' the exit code of the container  process  is  re‐
36       turned.
37
38
39       --cascade="background"       Must  be "background", "orphan", or "fore‐
40       ground". Selects the deletion cascading  strategy  for  the  dependents
41       (e.g. Pods created by a ReplicationController). Defaults to background.
42
43
44       --command=false       If true and extra arguments are present, use them
45       as the 'command' field in the container, rather than the  'args'  field
46       which is the default.
47
48
49       --dry-run="none"       Must be "none", "server", or "client". If client
50       strategy, only print the object that would be sent, without sending it.
51       If  server  strategy, submit server-side request without persisting the
52       resource.
53
54
55       --env=[]      Environment variables to set in the container.
56
57
58       --expose=false      If true, create a ClusterIP service associated with
59       the pod.  Requires --port.
60
61
62       --field-manager="kubectl-run"       Name  of  the manager used to track
63       field ownership.
64
65
66       -f, --filename=[]      to use to replace the resource.
67
68
69       --force=false      If true, immediately remove resources from  API  and
70       bypass  graceful  deletion.  Note  that  immediate deletion of some re‐
71       sources may result in inconsistency or data loss and requires confirma‐
72       tion.
73
74
75       --grace-period=-1       Period of time in seconds given to the resource
76       to terminate gracefully. Ignored if negative. Set to  1  for  immediate
77       shutdown. Can only be set to 0 when --force is true (force deletion).
78
79
80       --image=""      The image for the container to run.
81
82
83       --image-pull-policy=""       The  image  pull policy for the container.
84       If left empty, this value will not be specified by the client  and  de‐
85       faulted by the server.
86
87
88       -k,  --kustomize=""       Process  a kustomization directory. This flag
89       can't be used together with -f or -R.
90
91
92       -l, --labels=""      Comma separated labels to apply to the  pod.  Will
93       override previous values.
94
95
96       --leave-stdin-open=false      If the pod is started in interactive mode
97       or with stdin, leave stdin open after the first  attach  completes.  By
98       default, stdin will be closed after the first attach completes.
99
100
101       -o,  --output=""      Output format. One of: (json, yaml, name, go-tem‐
102       plate, go-template-file, template, templatefile, jsonpath, jsonpath-as-
103       json, jsonpath-file).
104
105
106       --override-type="merge"       The method used to override the generated
107       object: json, merge, or strategic.
108
109
110       --overrides=""      An inline JSON override for the  generated  object.
111       If  this is non-empty, it is used to override the generated object. Re‐
112       quires that the object supply a valid apiVersion field.
113
114
115       --pod-running-timeout=1m0s      The length of time (like 5s, 2m, or 3h,
116       higher than zero) to wait until at least one pod is running
117
118
119       --port=""      The port that this container exposes.
120
121
122       --privileged=false      If true, run the container in privileged mode.
123
124
125       -q, --quiet=false      If true, suppress prompt messages.
126
127
128       --record=false       Record current kubectl command in the resource an‐
129       notation. If set to false, do not record the command. If set  to  true,
130       record  the command. If not set, default to updating the existing anno‐
131       tation value only if one already exists.
132
133
134       -R, --recursive=false      Process the directory used in -f, --filename
135       recursively. Useful when you want to manage related manifests organized
136       within the same directory.
137
138
139       --restart="Always"      The restart policy for this Pod.  Legal  values
140       [Always, OnFailure, Never].
141
142
143       --rm=false       If  true,  delete  the pod after it exits.  Only valid
144       when  attaching  to  the  container,  e.g.  with  '--attach'  or   with
145       '-i/--stdin'.
146
147
148       --save-config=false       If  true, the configuration of current object
149       will be saved in its annotation. Otherwise, the annotation will be  un‐
150       changed.  This flag is useful when you want to perform kubectl apply on
151       this object in the future.
152
153
154       --show-managed-fields=false      If true, keep the  managedFields  when
155       printing objects in JSON or YAML format.
156
157
158       -i,  --stdin=false       Keep  stdin  open on the container in the pod,
159       even if nothing is attached.
160
161
162       --template=""      Template string or path to template file to use when
163       -o=go-template, -o=go-template-file. The template format is golang tem‐
164       plates [http://golang.org/pkg/text/template/#pkg-overview].
165
166
167       --timeout=0s      The length of time to wait  before  giving  up  on  a
168       delete, zero means determine a timeout from the size of the object
169
170
171       -t, --tty=false      Allocate a TTY for the container in the pod.
172
173
174       --wait=false      If true, wait for resources to be gone before return‐
175       ing. This waits for finalizers.
176
177
178

OPTIONS INHERITED FROM PARENT COMMANDS

180       --as=""      Username to impersonate for the operation. User could be a
181       regular user or a service account in a namespace.
182
183
184       --as-group=[]       Group  to  impersonate for the operation, this flag
185       can be repeated to specify multiple groups.
186
187
188       --as-uid=""      UID to impersonate for the operation.
189
190
191       --azure-container-registry-config=""      Path to the  file  containing
192       Azure container registry configuration information.
193
194
195       --cache-dir="/builddir/.kube/cache"      Default cache directory
196
197
198       --certificate-authority=""      Path to a cert file for the certificate
199       authority
200
201
202       --client-certificate=""      Path to a client certificate file for TLS
203
204
205       --client-key=""      Path to a client key file for TLS
206
207
208       --cluster=""      The name of the kubeconfig cluster to use
209
210
211       --context=""      The name of the kubeconfig context to use
212
213
214       --insecure-skip-tls-verify=false      If true, the server's certificate
215       will not be checked for validity. This will make your HTTPS connections
216       insecure
217
218
219       --kubeconfig=""      Path to the kubeconfig file to  use  for  CLI  re‐
220       quests.
221
222
223       --match-server-version=false        Require  server  version  to  match
224       client version
225
226
227       -n, --namespace=""      If present, the namespace scope  for  this  CLI
228       request
229
230
231       --password=""      Password for basic authentication to the API server
232
233
234       --profile="none"         Name   of   profile   to   capture.   One   of
235       (none|cpu|heap|goroutine|threadcreate|block|mutex)
236
237
238       --profile-output="profile.pprof"      Name of the  file  to  write  the
239       profile to
240
241
242       --request-timeout="0"       The length of time to wait before giving up
243       on a single server request. Non-zero values  should  contain  a  corre‐
244       sponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't time‐
245       out requests.
246
247
248       -s, --server=""      The address and port of the Kubernetes API server
249
250
251       --tls-server-name=""      Server name to  use  for  server  certificate
252       validation.  If  it  is  not provided, the hostname used to contact the
253       server is used
254
255
256       --token=""      Bearer token for authentication to the API server
257
258
259       --user=""      The name of the kubeconfig user to use
260
261
262       --username=""      Username for basic authentication to the API server
263
264
265       --version=false      Print version information and quit
266
267
268       --warnings-as-errors=false      Treat warnings received from the server
269       as errors and exit with a non-zero exit code
270
271
272

EXAMPLE

274                # Start a nginx pod
275                kubectl run nginx --image=nginx
276
277                # Start a hazelcast pod and let the container expose port 5701
278                kubectl run hazelcast --image=hazelcast/hazelcast --port=5701
279
280                # Start a hazelcast pod and set environment variables "DNS_DOMAIN=cluster" and "POD_NAMESPACE=default" in the container
281                kubectl run hazelcast --image=hazelcast/hazelcast --env="DNS_DOMAIN=cluster" --env="POD_NAMESPACE=default"
282
283                # Start a hazelcast pod and set labels "app=hazelcast" and "env=prod" in the container
284                kubectl run hazelcast --image=hazelcast/hazelcast --labels="app=hazelcast,env=prod"
285
286                # Dry run; print the corresponding API objects without creating them
287                kubectl run nginx --image=nginx --dry-run=client
288
289                # Start a nginx pod, but overload the spec with a partial set of values parsed from JSON
290                kubectl run nginx --image=nginx --overrides='{ "apiVersion": "v1", "spec": { ... } }'
291
292                # Start a busybox pod and keep it in the foreground, don't restart it if it exits
293                kubectl run -i -t busybox --image=busybox --restart=Never
294
295                # Start the nginx pod using the default command, but use custom arguments (arg1 .. argN) for that command
296                kubectl run nginx --image=nginx -- <arg1> <arg2> ... <argN>
297
298                # Start the nginx pod using a different command and custom arguments
299                kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>
300
301
302
303

SEE ALSO

305       kubectl(1),
306
307
308

HISTORY

310       January  2015,  Originally compiled by Eric Paris (eparis at redhat dot
311       com) based on the kubernetes source material, but hopefully  they  have
312       been automatically generated since!
313
314
315
316Manuals                              User            KUBERNETES(1)(kubernetes)
Impressum