1OC ADM(1)                          June 2016                         OC ADM(1)
2
3
4

NAME

6       oc adm router - Install a router
7
8
9

SYNOPSIS

11       oc adm router [OPTIONS]
12
13
14

DESCRIPTION

16       Install or configure a router
17
18
19       This  command  helps to setup a router to take edge traffic and balance
20       it to your application. With no arguments, the command will  check  for
21       an  existing  router  service called 'router' and create one if it does
22       not exist. If you want to test whether a router has already  been  cre‐
23       ated  add  the  --dry-run  flag and the command will exit with 1 if the
24       registry does not exist.
25
26
27       If a router does not exist with the given name, this command will  cre‐
28       ate a deployment configuration and service that will run the router. If
29       you are running your router in production, you should pass --replicas=2
30       or higher to ensure you have failover protection.
31
32
33

OPTIONS

35       --ciphers=""
36           Specifies  the  cipher  suites  to use. You can choose a predefined
37       cipher set ('modern', 'intermediate', or 'old') or specify exact cipher
38       suites by passing a : separated list. Not supported for F5.
39
40
41       --create=false
42           deprecated; this is now the default behavior
43
44
45       --default-cert=""
46           Optional  path  to  a  certificate file that be used as the default
47       certificate.  The file should contain the cert, key, and any  CA  certs
48       necessary  for  the  router to serve the certificate. Does not apply to
49       external appliance based routers (e.g. F5)
50
51
52       --disable-namespace-ownership-check=false
53           Disables the namespace ownership check and allows different  names‐
54       paces  to  claim  either different paths to a route host or overlapping
55       host names in case of a wildcard route. The default behavior (false) to
56       restrict  claims  to  the  oldest namespace that has claimed either the
57       host or the subdomain. Please be  aware  that  if  namespace  ownership
58       checks are disabled, routes in a different namespace can use this mech‐
59       anism to 'steal' sub-paths for existing domains. This is only  safe  if
60       route  creation  privileges  are restricted, or if all the users can be
61       trusted.
62
63
64       --dry-run=false
65           If true, show the result of the operation without performing it.
66
67
68       --extended-logging=false
69           If true, then configure the router with additional logging.
70
71
72       --external-host=""
73           If the underlying router implementation connects with  an  external
74       host, this is the external host's hostname.
75
76
77       --external-host-http-vserver=""
78           If  the underlying router implementation uses virtual servers, this
79       is the name of the virtual server for HTTP connections.
80
81
82       --external-host-https-vserver=""
83           If the underlying router implementation uses virtual servers,  this
84       is the name of the virtual server for HTTPS connections.
85
86
87       --external-host-insecure=false
88           If  the  underlying router implementation connects with an external
89       host over a secure connection, this causes the router  to  skip  strict
90       certificate verification with the external host.
91
92
93       --external-host-internal-ip=""
94           If  the underlying router implementation requires the use of a spe‐
95       cific network interface to connect to the pod network, this is  the  IP
96       address of that internal interface.
97
98
99       --external-host-partition-path=""
100           If the underlying router implementation uses partitions for control
101       boundaries, this is the path to use for that partition.
102
103
104       --external-host-password=""
105           If the underlying router implementation connects with  an  external
106       host, this is the password for authenticating with the external host.
107
108
109       --external-host-private-key=""
110           If  the  underlying  router  implementation requires an SSH private
111       key, this is the path to the private key file.
112
113
114       --external-host-username=""
115           If the underlying router implementation connects with  an  external
116       host, this is the username for authenticating with the external host.
117
118
119       --external-host-vxlan-gw=""
120           If  the  underlying  router implementation requires VxLAN access to
121       the pod network, this is the gateway address that  should  be  used  in
122       cidr format.
123
124
125       --force-subdomain=""
126           A  router  path  format  to force on all routes used by this router
127       (will ignore the route host value)
128
129
130       --host-network=true
131           If true (the default), then use host networking rather than using a
132       separate  container  network stack. Not required for external appliance
133       based routers (e.g. F5)
134
135
136       --host-ports=true
137           If true (the default), when not using host  networking  host  ports
138       will  be  exposed.  Not  required  for external appliance based routers
139       (e.g. F5)
140
141
142       --images="openshift/origin-${component}:${version}"
143           The image to base this router on - ${component}  will  be  replaced
144       with --type
145
146
147       --labels="router=<name>"
148           A set of labels to uniquely identify the router and its components.
149
150
151       --latest-images=false
152           If true, attempt to use the latest images for the router instead of
153       the latest release.
154
155
156       --local=false
157           If true, do not contact the apiserver
158
159
160       --max-connections=""
161           Specifies the maximum number of concurrent  connections.  Not  sup‐
162       ported for F5.
163
164
165       --mutual-tls-auth="none"
166           Controls  access  to the router using mutually agreed upon TLS con‐
167       figuration  (example  client  certificates).  You  can  choose  one  of
168       'required', 'optional', or 'none'. The default is none.
169
170
171       --mutual-tls-auth-ca=""
172           Optional path to a file containing one or more CA certificates used
173       for mutual TLS authentication. The CA certificate[s] are  used  by  the
174       router to verify a client's certificate.
175
176
177       --mutual-tls-auth-crl=""
178           Optional  path to a file containing the certificate revocation list
179       used for mutual TLS authentication. The certificate revocation list  is
180       used by the router to verify a client's certificate.
181
182
183       --mutual-tls-auth-filter=""
184           Optional  regular  expression to filter the client certificates. If
185       the client certificate  subject  field  does  not  match  this  regular
186       expression, requests will be rejected by the router.
187
188
189       -o, --output=""
190           Output  results  as  yaml or json instead of executing, or use name
191       for succint output (resource/name).
192
193
194       --output-version=""
195           The preferred API versions of the output objects
196
197
198       --ports="80:80,443:443"
199           A comma delimited list of ports or port pairs that set the port  in
200       the  router  pod  containerPort and hostPort. It also sets service port
201       and targetPort to expose on the router pod. This does  not  modify  the
202       env  variables.  That  can  be  done using oc set env or by editing the
203       router's dc. This is used when host-network=false.
204
205
206       --replicas=1
207           The replication factor of the router; commonly 2 when  high  avail‐
208       ability is desired.
209
210
211       --router-canonical-hostname=""
212           CanonicalHostname is the external host name for the router that can
213       be used as a CNAME for the host requested for this route. This value is
214       optional and may not be set in all cases.
215
216
217       --secrets-as-env=false
218           If true, use environment variables for master secrets.
219
220
221       --selector=""
222           Selector used to filter nodes on deployment. Used to run routers on
223       a specific set of nodes.
224
225
226       --service-account="router"
227           Name of the service account to use to run the router pod.
228
229
230       -a, --show-all=true
231           When printing, show all  resources  (false  means  hide  terminated
232       pods.)
233
234
235       --show-labels=false
236           When  printing,  show  all  labels as the last column (default hide
237       labels column)
238
239
240       --sort-by=""
241           If non-empty, sort list types using this field specification.   The
242       field  specification  is  expressed  as  a  JSONPath  expression  (e.g.
243       '{.metadata.name}'). The field in the API resource  specified  by  this
244       JSONPath expression must be an integer or a string.
245
246
247       --stats-password=""
248           If the underlying router implementation can provide statistics this
249       is the requested password for auth.  If not set a password will be gen‐
250       erated. Not available for external appliance based routers (e.g. F5)
251
252
253       --stats-port=1936
254           If the underlying router implementation can provide statistics this
255       is a hint to expose it on this port. Specify 0 if you want to turn  off
256       exposing the statistics.
257
258
259       --stats-user="admin"
260           If the underlying router implementation can provide statistics this
261       is the requested username for auth. Not available for  external  appli‐
262       ance based routers (e.g. F5)
263
264
265       --strict-sni=false
266           Use  strict-sni bind processing (do not use default cert). Not sup‐
267       ported for F5.
268
269
270       --subdomain=""
271           The template for the route subdomain exposed by this  router,  used
272       for  routes  that  are not externally specified. E.g. '${name}-${names‐
273       pace}.apps.mycompany.com'
274
275
276       --template=""
277           Template string or path to template file  to  use  when  -o=go-tem‐
278       plate,  -o=go-template-file.  The template format is golang templates [
279http://golang.org/pkg/text/template/#pkg-overview⟩].
280
281
282       --threads=0
283           Specifies the number of threads for the haproxy router.
284
285
286       --type="haproxy-router"
287           The type of router to use - if you specify --images this  flag  may
288       be ignored.
289
290
291

OPTIONS INHERITED FROM PARENT COMMANDS

293       --allow_verification_with_non_compliant_keys=false
294           Allow  a  SignatureVerifier  to  use  keys  which  are  technically
295       non-compliant with RFC6962.
296
297
298       --alsologtostderr=false
299           log to standard error as well as files
300
301
302       --application_metrics_count_limit=100
303           Max number of application metrics to store (per container)
304
305
306       --as=""
307           Username to impersonate for the operation
308
309
310       --as-group=[]
311           Group to impersonate for the operation, this flag can  be  repeated
312       to specify multiple groups.
313
314
315       --azure-container-registry-config=""
316           Path  to the file containing Azure container registry configuration
317       information.
318
319
320       --boot_id_file="/proc/sys/kernel/random/boot_id"
321           Comma-separated list of files to check for boot-id. Use  the  first
322       one that exists.
323
324
325       --cache-dir="/builddir/.kube/http-cache"
326           Default HTTP cache directory
327
328
329       --certificate-authority=""
330           Path to a cert file for the certificate authority
331
332
333       --client-certificate=""
334           Path to a client certificate file for TLS
335
336
337       --client-key=""
338           Path to a client key file for TLS
339
340
341       --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
342           CIDRs opened in GCE firewall for LB traffic proxy  health checks
343
344
345       --cluster=""
346           The name of the kubeconfig cluster to use
347
348
349       --container_hints="/etc/cadvisor/container_hints.json"
350           location of the container hints file
351
352
353       --containerd="unix:///var/run/containerd.sock"
354           containerd endpoint
355
356
357       --context=""
358           The name of the kubeconfig context to use
359
360
361       --default-not-ready-toleration-seconds=300
362           Indicates   the   tolerationSeconds   of   the    toleration    for
363       notReady:NoExecute  that is added by default to every pod that does not
364       already have such a toleration.
365
366
367       --default-unreachable-toleration-seconds=300
368           Indicates the tolerationSeconds  of  the  toleration  for  unreach‐
369       able:NoExecute  that  is  added  by  default to every pod that does not
370       already have such a toleration.
371
372
373       --docker="unix:///var/run/docker.sock"
374           docker endpoint
375
376
377       --docker-tls=false
378           use TLS to connect to docker
379
380
381       --docker-tls-ca="ca.pem"
382           path to trusted CA
383
384
385       --docker-tls-cert="cert.pem"
386           path to client certificate
387
388
389       --docker-tls-key="key.pem"
390           path to private key
391
392
393       --docker_env_metadata_whitelist=""
394           a comma-separated list of environment variable keys that  needs  to
395       be collected for docker containers
396
397
398       --docker_only=false
399           Only report docker containers in addition to root stats
400
401
402       --docker_root="/var/lib/docker"
403           DEPRECATED:  docker  root is read from docker info (this is a fall‐
404       back, default: /var/lib/docker)
405
406
407       --enable_load_reader=false
408           Whether to enable cpu load reader
409
410
411       --event_storage_age_limit="default=24h"
412           Max length of time for which to store events (per type). Value is a
413       comma  separated  list  of  key  values, where the keys are event types
414       (e.g.: creation, oom) or "default" and the value is a duration. Default
415       is applied to all non-specified event types
416
417
418       --event_storage_event_limit="default=100000"
419           Max  number  of  events to store (per type). Value is a comma sepa‐
420       rated list of key values, where the keys are event  types  (e.g.:  cre‐
421       ation,  oom)  or  "default"  and  the  value  is an integer. Default is
422       applied to all non-specified event types
423
424
425       --global_housekeeping_interval=0
426           Interval between global housekeepings
427
428
429       --housekeeping_interval=0
430           Interval between container housekeepings
431
432
433       --insecure-skip-tls-verify=false
434           If true, the server's certificate will not be checked for validity.
435       This will make your HTTPS connections insecure
436
437
438       --kubeconfig=""
439           Path to the kubeconfig file to use for CLI requests.
440
441
442       --log-flush-frequency=0
443           Maximum number of seconds between log flushes
444
445
446       --log_backtrace_at=:0
447           when logging hits line file:N, emit a stack trace
448
449
450       --log_cadvisor_usage=false
451           Whether to log the usage of the cAdvisor container
452
453
454       --log_dir=""
455           If non-empty, write log files in this directory
456
457
458       --logtostderr=true
459           log to standard error instead of files
460
461
462       --machine_id_file="/etc/machine-id,/var/lib/dbus/machine-id"
463           Comma-separated  list  of  files  to  check for machine-id. Use the
464       first one that exists.
465
466
467       --match-server-version=false
468           Require server version to match client version
469
470
471       -n, --namespace=""
472           If present, the namespace scope for this CLI request
473
474
475       --request-timeout="0"
476           The length of time to wait before giving  up  on  a  single  server
477       request. Non-zero values should contain a corresponding time unit (e.g.
478       1s, 2m, 3h). A value of zero means don't timeout requests.
479
480
481       -s, --server=""
482           The address and port of the Kubernetes API server
483
484
485       --stderrthreshold=2
486           logs at or above this threshold go to stderr
487
488
489       --storage_driver_buffer_duration=0
490           Writes in the storage driver will be buffered  for  this  duration,
491       and committed to the non memory backends as a single transaction
492
493
494       --storage_driver_db="cadvisor"
495           database name
496
497
498       --storage_driver_host="localhost:8086"
499           database host:port
500
501
502       --storage_driver_password="root"
503           database password
504
505
506       --storage_driver_secure=false
507           use secure connection with database
508
509
510       --storage_driver_table="stats"
511           table name
512
513
514       --storage_driver_user="root"
515           database username
516
517
518       --token=""
519           Bearer token for authentication to the API server
520
521
522       --user=""
523           The name of the kubeconfig user to use
524
525
526       -v, --v=0
527           log level for V logs
528
529
530       --version=false
531           Print version information and quit
532
533
534       --vmodule=
535           comma-separated  list  of pattern=N settings for file-filtered log‐
536       ging
537
538
539

EXAMPLE

541                # Check the default router ("router")
542                oc adm router --dry-run
543
544                # See what the router would look like if created
545                oc adm router -o yaml
546
547                # Create a router with two replicas if it does not exist
548                oc adm router router-west --replicas=2
549
550                # Use a different router image
551                oc adm router region-west --images=myrepo/somerouter:mytag
552
553                # Run the router with a hint to the underlying implementation to _not_ expose statistics.
554                oc adm router router-west --stats-port=0
555
556
557
558

SEE ALSO

560       oc-adm(1),
561
562
563

HISTORY

565       June 2016, Ported from the Kubernetes man-doc generator
566
567
568
569Openshift                  Openshift CLI User Manuals                OC ADM(1)
Impressum