Skip to content

Commit e5faad4

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-9421: router configuration MicroShift
1 parent d824edb commit e5faad4

6 files changed

+299
-30
lines changed

‎microshift_networking/microshift-nw-router.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,22 @@ toc::[]
88

99
Learn about default and custom settings for configuring the router with {microshift-short}.
1010

11+
include::modules/microshift-nw-router-con.adoc[leveloffset=+1]
12+
13+
include::modules/microshift-nw-router-disable.adoc[leveloffset=+1]
14+
15+
[id="microshift-configuring-router-ingress_{context}"]
16+
== Configuring router ingress
17+
18+
If your {microshift-short} applications need to listen only for data traffic, you can configure the `listenAddress` setting to isolate your devices. You can also configure specific ports and IP addresses for network connections. Use the combination required to customize the endpoint configuration for your use case.
19+
20+
include::modules/microshift-nw-router-config-ports.adoc[leveloffset=+2]
21+
22+
include::modules/microshift-nw-router-config-ip-address.adoc[leveloffset=+2]
23+
24+
[role="_additional-resources"]
25+
[id="additional-resources_microshift-understanding-and-configuring-router_{context}"]
26+
== Additional resources
27+
* xref:../microshift_configuring/microshift-using-config-tools.adoc#microshift-yaml-default_microshift-using-config-tools[Default settings] ({microshift-short})
28+
29+
* xref:../microshift_networking/microshift_network_policy/microshift-network-policy-index.adoc#microshift-network-policies[About network policies]

‎modules/microshift-default-settings.adoc

Lines changed: 36 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -21,57 +21,63 @@ $ microshift show-config
2121
apiServer:
2222
advertiseAddress: 10.44.0.0/32 # <1>
2323
auditLog:
24-
maxFileAge: 10
25-
maxFileSize: 200
26-
maxFiles: 10
27-
profile: Default
24+
maxFileAge: 0 # <2>
25+
maxFileSize: 200 # <3>
26+
maxFiles: 10 # <4>
27+
profile: Default # <5>
2828
namedCertificates:
2929
- certPath: ""
3030
keyPath: ""
3131
names:
3232
- ""
33-
subjectAltNames: [] # <2>
33+
subjectAltNames: [] # <6>
3434
debugging:
35-
logLevel: "Normal" # <3>
35+
logLevel: "Normal" # <7>
3636
dns:
37-
baseDomain: microshift.example.com <4>
37+
baseDomain: microshift.example.com # <8>
3838
etcd:
39-
memoryLimitMB: 0 # <5>
39+
memoryLimitMB: 0 # <9>
4040
ingress:
4141
listenAddress:
42-
- ""
43-
ports:
42+
- "" # <10>
43+
ports: # <11>
4444
http: 80
4545
https: 443
4646
routeAdmissionPolicy:
47-
namespaceOwnership: InterNamespaceAllowed # <6>
48-
status: Managed # <7>
49-
manifests: # <8>
47+
namespaceOwnership: InterNamespaceAllowed # <12>
48+
status: Managed # <13>
49+
manifests: # <14>
5050
kustomizePaths:
5151
- /usr/lib/microshift/manifests
5252
- /usr/lib/microshift/manifests.d/*
5353
- /etc/microshift/manifests
5454
- /etc/microshift/manifests.d/*
5555
network:
5656
clusterNetwork:
57-
- 10.42.0.0/16 # <9>
57+
- 10.42.0.0/16 # <15>
5858
serviceNetwork:
59-
- 10.43.0.0/16 # <10>
60-
serviceNodePortRange: 30000-32767 # <11>
59+
- 10.43.0.0/16 # <16>
60+
serviceNodePortRange: 30000-32767 # <17>
6161
node:
62-
hostnameOverride: "" # <12>
63-
nodeIP: "" # <13>
62+
hostnameOverride: "" # <18>
63+
nodeIP: "" # <19>
6464
----
6565
<1> A string that specifies the IP address from which the API server is advertised to members of the cluster. The default value is calculated based on the address of the service network.
66-
<2> Subject Alternative Names for API server certificates.
67-
<3> Log verbosity. Valid values for this field are `Normal`, `Debug`, `Trace`, or `TraceAll`.
68-
<4> By default, `etcd` uses as much memory as needed to handle the load on the system. However, in memory constrained systems, it might be preferred or necessary to limit the amount of memory `etcd` can to use at a given time.
69-
<5> Base domain of the cluster. All managed DNS records are subdomains of this base.
70-
<6> Describes how host name claims across namespaces are handled. By default, allows routes to claim different paths of the same host name across namespaces. Can also be set as `Strict` to not allow routes in different namespaces to claim the same host. If the value is deleted and a new one is not added, `InterNamespaceAllowed` is automatically set.
71-
<7> Default router status, can be `Managed` or `Removed`.
72-
<8> The locations on the filesystem to scan for `kustomization` files to use to load manifests. Set to a list of paths to scan only those paths. Set to an empty list to disable loading manifests. The entries in the list can be glob patterns to match multiple subdirectories.
73-
<9> A block of IP addresses from which Pod IP addresses are allocated. This field is immutable after installation.
74-
<10> A block of virtual IP addresses for Kubernetes services. IP address pool for services. A single entry is supported. This field is immutable after installation.
75-
<11> The port range allowed for Kubernetes services of type NodePort. If not specified, the default range of 30000-32767 is used. Services without a `NodePort` specified are automatically allocated one from this range. This parameter can be updated after the cluster is installed.
76-
<12> The name of the node. The default value is the hostname. If non-empty, this string is used to identify the node instead of the hostname.
77-
<13> The IP address of the node. The default value is the IP address of the default route.
66+
<2> How long log files are kept before automatic deletion. The default value of `0` in the `maxFileAge` parameter means a log file is never deleted based on age. This value can be configured.
67+
<3> By default, when the `audit.log` file reaches the `maxFileSize` limit, the `audit.log` file is rotated and {microshift-short} begins writing to a new `audit.log` file. This value can be configured.
68+
<4> The total number of log files kept. By default, {microshift-short} retains 10 log files. The oldest is deleted when an excess file is created. This value can be configured.
69+
<5> Logs only metadata for read and write requests; does not log request bodies except for OAuth access token requests. If you do not specify this field, the `Default` profile is used.
70+
<6> Subject Alternative Names for API server certificates.
71+
<7> Log verbosity. Valid values for this field are `Normal`, `Debug`, `Trace`, or `TraceAll`.
72+
<8> By default, `etcd` uses as much memory as needed to handle the load on the system. However, in memory constrained systems, it might be preferred or necessary to limit the amount of memory `etcd` can to use at a given time.
73+
<9> Base domain of the cluster. All managed DNS records are subdomains of this base.
74+
<10> The `ingress.listenAddress` value defaults to the entire network of the host. The valid configurable value is a list that can be either a single IP address or NIC name or multiple IP addresses and NIC names.
75+
<11> Default ports shown. Configurable. Valid values for both port entries are a single, unique port in the 1-65535 range. The values of the `ports.http` and `ports.https` fields cannot be the same.
76+
<12> Describes how hostname claims across namespaces are handled. By default, allows routes to claim different paths of the same hostname across namespaces. Valid values are `Strict` and `InterNamespaceAllowed`. Specifying `Strict` prevents routes in different namespaces from claiming the same hostname. If the value is deleted in a customized {microshift-short} `config.yaml`, the `InterNamespaceAllowed` value is automatically set.
77+
<13> Default router status, can be `Managed` or `Removed`.
78+
<14> The locations on the file system to scan for `kustomization` files to use to load manifests. Set to a list of paths to scan only those paths. Set to an empty list to disable loading manifests. The entries in the list can be glob patterns to match multiple subdirectories.
79+
<15> A block of IP addresses from which pod IP addresses are allocated. This field is immutable after installation.
80+
<16> A block of virtual IP addresses for Kubernetes services. IP address pool for services. A single entry is supported. This field is immutable after installation.
81+
<17> The port range allowed for Kubernetes services of type `NodePort`. If not specified, the default range of 30000-32767 is used. Services without a `NodePort` specified are automatically allocated one from this range. This parameter can be updated after the cluster is installed.
82+
<18> The name of the node. The default value is the hostname. If non-empty, this string is used to identify the node instead of the hostname.
83+
<19> The IP address of the node. The default value is the IP address of the default route.

‎modules/microshift-nw-router-con.adoc

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-nw-router.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="microshift-about-router-config_{context}"]
7+
= About configuring the router
8+
9+
To make ingress optional, you can configure {microshift-short} ingress router settings to manage which ports, if any, are exposed to network traffic. Specified routing is an example of ingress load balancing.
10+
11+
* The default ingress router is always on, running on all IP addresses on the `http: 80` and `https: 443` ports.
12+
* Default router settings allow access to any namespace.
13+
14+
Some applications running on top of {microshift-short} might not require the default router and instead create their own. You can configure the router to control both ingress and namespace access.
15+
16+
[TIP]
17+
====
18+
You can check for the presence of the default router in your {microshift-short} installation before you begin configurations by using the `oc get deployment -n openshift-ingress` command, which returns the following output:
19+
20+
[source,terminal]
21+
----
22+
NAME READY UP-TO-DATE AVAILABLE AGE
23+
router-default 1/1 1 1 2d23h
24+
----
25+
====
26+
27+
[id="microshift-router-csettings_{context}"]
28+
== Router settings and valid values
29+
30+
The ingress router settings consist of the following parameters and valid values:
31+
32+
.Example `config.yaml` router settings
33+
[source,yaml]
34+
----
35+
# ...
36+
ingress:
37+
listenAddress:
38+
- "" # <1>
39+
ports: # <2>
40+
http: 80
41+
https: 443
42+
routeAdmissionPolicy:
43+
namespaceOwnership: InterNamespaceAllowed # <3>
44+
status: Managed # <4>
45+
# ...
46+
----
47+
<1> The `ingress.listenAddress` value defaults to the entire network of the host. Valid customizable values can be a single IP address or host name or a list of IP addresses or host names.
48+
<2> Valid values for both port entries are a single, unique port in the 1-65535 range. The values of the `ports.http` and `ports.https` fields cannot be the same.
49+
<3> Default value. Allows routes to claim different paths of the same host name across namespaces.
50+
<4> Default value. `Managed` is required for the ingress ports to remain open.
51+
52+
[IMPORTANT]
53+
====
54+
The firewalld service is bypassed by the default {microshift-short} router and by configurations that enable the router. Ingress and egress must be controlled by setting network policies when the router is active.
55+
====

‎modules/microshift-nw-router-config-ip-address.adoc

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-nw-router.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-config-ip-addresses_{context}"]
7+
= Configuring router IP addresses
8+
9+
You can restrict the network traffic to the router by configuring specific IP addresses. For example:
10+
11+
* Use cases where the router is reachable only on internal networks, but not on northbound public networks
12+
* Use cases where the router is reachable only by northbound public networks, but not on internal networks
13+
* Use cases where the router is reachable by both internal networks and northbound public networks, but on separate IP addresses
14+
15+
.Prerequisites
16+
17+
* You installed {microshift-short}.
18+
* You created a {microshift-short} `config.yaml` file.
19+
* The {oc-first} is installed.
20+
21+
[TIP]
22+
====
23+
If you complete all the configurations that you need to make in the {microshift-short} `config.yaml` file at the same time, you can minimize system restarts.
24+
====
25+
26+
.Procedure
27+
28+
. Update the list in the `ingress.listenAddress` field in the {microshift-short} `config.yaml` according to your requirements and as shown in the following examples:
29+
+
30+
.Default router IP address list
31+
[source,yaml]
32+
----
33+
# ...
34+
ingress:
35+
listenAddress:
36+
- "<host_network>" # <1>
37+
# ...
38+
----
39+
<1> The `ingress.listenAddress` value defaults to the entire network of the host. To continue to use the default list, remove the `listen.Address` field from the {microshift-short} `config.yaml` file. To customize this parameter, use a list. The list can contain either a single IP address or NIC name or multiple IP addresses and NIC names.
40+
+
41+
[IMPORTANT]
42+
====
43+
You must either remove the `listenAddress` parameter or add values to it in the form of a list when using the `config.yaml` file. Do not leave the field empty or {microshift-short} crashes on restart.
44+
====
45+
+
46+
.Example router setting with a single host IP address
47+
[source,yaml]
48+
----
49+
# ...
50+
ingress:
51+
listenAddress:
52+
- 10.2.1.100
53+
# ...
54+
----
55+
+
56+
.Example router setting with a combination of IP addresses and NIC names
57+
[source,yaml]
58+
----
59+
# ...
60+
ingress:
61+
listenAddress:
62+
- 10.2.1.100
63+
- 10.2.2.10
64+
- ens3
65+
# ...
66+
----
67+
68+
. Restart the {microshift-short} service by running the following command:
69+
+
70+
[source,terminal]
71+
----
72+
$ sudo systemctl restart microshift
73+
----
74+
75+
.Verification
76+
77+
* To verify that your settings are applied, make sure that the `ingress.listenAddress` IP addresses are reachable, then you can `curl` the route with the destination to one of these load balancer IP address.

‎modules/microshift-nw-router-config-ports.adoc

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-nw-router.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-config-router-ports_{context}"]
7+
= Configuring router ports
8+
9+
You can control which ports your devices use by configuring the router ingress fields.
10+
11+
.Prerequisites
12+
13+
* You installed {microshift-short}.
14+
* You created a {microshift-short} `config.yaml` file.
15+
* The {oc-first} is installed.
16+
17+
[TIP]
18+
====
19+
If you complete all the configurations that you need to make in the {microshift-short} `config.yaml` file at the same time, you can minimize system restarts.
20+
====
21+
22+
.Procedure
23+
24+
. Update the {microshift-short} `config.yaml` port values in the `ingress.ports.http` and `ingress.ports.https` fields to the ports you want to use:
25+
+
26+
.Example `config.yaml` router settings
27+
[source,yaml]
28+
----
29+
# ...
30+
ingress:
31+
ports: # <1>
32+
http: 80
33+
https: 443
34+
routeAdmissionPolicy:
35+
namespaceOwnership: InterNamespaceAllowed
36+
status: Managed # <2>
37+
# ...
38+
----
39+
<1> Default ports shown. Customizable. Valid values for both port entries are a single, unique port in the 1-65535 range. The values of the `ports.http` and `ports.https` fields cannot be the same.
40+
<2> The default value. `Managed` is required for the ingress ports to remain open.
41+
42+
. Restart the {microshift-short} service by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ sudo systemctl restart microshift
47+
----

‎modules/microshift-nw-router-disable.adoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-nw-router.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-disabling-the-router_{context}"]
7+
= Disabling the router
8+
9+
In use cases such as industrial IoT spaces where {microshift-short} pods only need to connect to southbound operational systems and northbound cloud-data systems, inbound services are not needed. Use this procedure to disable the router in such egress-only use cases.
10+
11+
.Prerequisites
12+
13+
* You installed {microshift-short}.
14+
* You created a {microshift-short} `config.yaml` file.
15+
* The {oc-first} is installed.
16+
17+
[TIP]
18+
====
19+
If you complete all the configurations that you need to make in the {microshift-short} `config.yaml` file at the same time, you can minimize system restarts.
20+
====
21+
22+
.Procedure
23+
24+
. Update the value of `ingress.status` field to `Removed` in the {microshift-short} `config.yaml` file as shown in the following example:
25+
+
26+
.Example `config.yaml` ingress stanza
27+
[source,yaml]
28+
----
29+
# ...
30+
ingress:
31+
ports:
32+
http: 80
33+
https: 443
34+
routeAdmissionPolicy:
35+
namespaceOwnership: InterNamespaceAllowed
36+
status: Removed # <1>
37+
# ...
38+
----
39+
<1> When the value is set to `Removed`, the ports listed in `ingress.ports` are automatically closed. Any other settings in the `ingress` stanza are ignored, for example, any values in the `routeAdmissionPolicy.namespaceOwnership` field.
40+
41+
. Restart the {microshift-short} service by running the following command:
42+
+
43+
[source,terminal]
44+
----
45+
$ sudo systemctl restart microshift
46+
----
47+
+
48+
[NOTE]
49+
====
50+
The {microshift-short} service outputs current configurations during restarts.
51+
====
52+
53+
.Verification
54+
* After the system restarts, verify that the router has been removed and that ingress is stopped by running the following command:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc -n openshift-ingress get svc
59+
----
60+
+
61+
.Expected output
62+
[source,text]
63+
----
64+
No resources found in openshift-ingress namespace.
65+
----

0 commit comments

Comments
 (0)