Skip to content

Commit 09d27ce

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-14578: adds ingress control options to MicroShift
1 parent ffec83d commit 09d27ce

File tree

4 files changed

+191
-17
lines changed

4 files changed

+191
-17
lines changed

‎modules/microshift-config-yaml-custom.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
:_mod-docs-content-type: CONCEPT
66
[id="microshift-yaml-custom_{context}"]
77
= Using custom settings
8+
89
To create custom configurations, make a copy of the `config.yaml.default` file that is provided in the `/etc/microshift/` directory, renaming it `config.yaml`. Keep this file in the `/etc/microshift/` directory, and then you can change supported settings that are expected to override the defaults before starting or restarting {microshift-short}.
910

1011
[IMPORTANT]

‎modules/microshift-default-settings.adoc

Lines changed: 38 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,15 @@ apiServer:
3333
subjectAltNames: []
3434
tls:
3535
cipherSuites:
36-
- ""
36+
- TLS_AES_128_GCM_SHA256
37+
- TLS_AES_256_GCM_SHA384
38+
- TLS_CHACHA20_POLY1305_SHA256
39+
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
40+
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
41+
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
42+
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
43+
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
44+
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
3745
minVersion: VersionTLS12
3846
debugging:
3947
logLevel: "Normal"
@@ -42,6 +50,31 @@ dns:
4250
etcd:
4351
memoryLimitMB: 0
4452
ingress:
53+
accessLogging:
54+
destination:
55+
type:
56+
container:
57+
maxLength: 1024
58+
syslog:
59+
address: ""
60+
facility: ""
61+
maxLength: 1024
62+
port: 0
63+
type: ""
64+
httpCaptureCookies:
65+
- matchType: ""
66+
maxLength: 0
67+
name: ""
68+
namePrefix: ""
69+
httpCaptureHeaders:
70+
request:
71+
- maxLength: 0
72+
name: ""
73+
response:
74+
- maxLength: 0
75+
name: ""
76+
httpLogFormat: ""
77+
status: Disabled
4578
certificateSecret: router-certs-default
4679
clientTLS:
4780
allowedSubjectPatterns:
@@ -54,8 +87,9 @@ ingress:
5487
mimeTypes:
5588
- ""
5689
httpEmptyRequestsPolicy: Respond
57-
listenAddress:
58-
- ""
90+
httpErrorCodePages:
91+
name: ""
92+
listenAddress: []
5993
logEmptyRequests: Log
6094
ports:
6195
http: 80
@@ -65,14 +99,7 @@ ingress:
6599
wildcardPolicy: WildcardPolicyAllowed
66100
status: Managed
67101
tlsSecurityProfile:
68-
type: Custom
69-
custom:
70-
ciphers:
71-
- ECDHE-ECDSA-CHACHA20-POLY1305
72-
- ECDHE-RSA-CHACHA20-POLY1305
73-
- ECDHE-RSA-AES128-GCM-SHA256
74-
- ECDHE-ECDSA-AES128-GCM-SHA256
75-
minTLSVersion: VersionTLS12
102+
type: Intermediate
76103
tuningOptions:
77104
clientFinTimeout: "1s"
78105
clientTimeout: "30s"

‎modules/microshift-ingress-controller-conc.adoc

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,31 @@
66
[id="microshift-ingress-control-concept_{context}"]
77
= Using ingress control in {microshift-short}
88

9-
When you create your {microshift-short} cluster, each pod and service running on the cluster is allocated an IP address. These IP addresses are accessible to other pods and services running nearby by default, but are not accessible to external clients. {microshift-short} uses a minimal implementation of the {ocp} `IngressController` API to enable external access to cluster services.
9+
When you create your {microshift-short} cluster, each pod and service running on the cluster is allocated an IP address. These IP addresses are accessible to other pods and services running nearby by default, but are not accessible to external clients. {microshift-short} uses a minimal implementation of the {OCP} `IngressController` API to enable external access to cluster services.
1010

11-
With more configuration options, you can fine-tune ingress to meet your specific needs. To use enhanced ingress control, update the parameters in the {microshift-short} configuration file and restart the service. Ingress configuration is useful in a variety of ways, for example:
11+
With more configuration options, you can fine-tune ingress to meet your specific needs. To use enhanced ingress control, update the parameters in the {microshift-short} configuration file and restart the service.
1212

13+
Ingress configuration is useful in a variety of ways, for example:
14+
15+
Accommodate server response speed::
1316
* If your application starts processing requests from clients but the connection is
1417
closed before it can respond, you can set the `ingress.tuningOptions.serverTimeout` parameter in the configuration file to a higher value to accommodate the speed of the response from the server.
1518

19+
Closing router connections::
1620
* If the router has many connections open because an application running on the cluster does not close connections properly, you can set the `ingress.tuningOptions.serverTimeout` and `spec.tuningOptions.serverFinTimeout` parameters to a lower value, forcing those connections to close sooner.
1721

18-
* If you need to configure the ingress controller to verify client certificates, you can use the `ingress.clientTLS` parameter to set a clientCA value, which is a reference to a config map. The config map contains the PEM-encoded CA certificate bundle that is used to verify a client's certificate. Optionally, you can also configure a list of certificate subject filters.
22+
Verify client certificates::
23+
* If you need to configure the ingress controller to verify client certificates, you can use the `ingress.clientTLS` parameter to set a clientCA value, which is a reference to a config map. The config map contains the PEM-encoded CA certificate bundle that is used to verify a client's certificate. Optionally, you can also configure a list of certificate subject filters.
1924

25+
Configure a TLS security profile::
2026
* If you need to configure a TLS security profile for an ingress controller, you can use the `ingress.tlsSecurityProfile` parameter to specify a default or custom individual TLS security profiles. The TLS security profile defines the minimum TLS version and the TLS ciphers for TLS connections for the ingress controllers.
2127
If a TLS security profile is not configured, the default value is based on the TLS security profile set for the API server.
2228

23-
* If you need to define a policy for handling new route claims, you can use the `routeAdmission` parameter to allow or deny claims across namespaces. You set the `routeAdmission` parameter to describe how hostname claims across namespaces should be handled and to describe how routes with wildcard policies are handled by the ingress controller.
29+
Create policies for new route claims::
30+
* If you need to define a policy for handling new route claims, you can use the `routeAdmission` parameter to allow or deny claims across namespaces. You set the `routeAdmission` parameter to describe how hostname claims across namespaces should be handled and to describe how routes with wildcard policies are handled by the ingress controller.
31+
32+
Customize error pages::
33+
* If you want more than the default error pages, which are usually empty and only return the http status code, configure custom error pages.
34+
35+
Capture HTTP headers or cookies::
36+
* If you want to include the capture of HTTP headers or cookies, configure access logging.

‎modules/microshift-ingress-controller-config.adoc

Lines changed: 135 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,30 @@ Configuration snippet YAMLs take precedence over both built-in settings and the
4141
apiServer:
4242
# ...
4343
ingress:
44+
accessLogging:
45+
destination:
46+
container:
47+
maxLength: 1024
48+
syslog:
49+
address: ""
50+
facility: ""
51+
maxLength: 1024
52+
port: 0
53+
type: ""
54+
httpCaptureCookies:
55+
- matchType: ""
56+
maxLength: 0
57+
name: ""
58+
namePrefix: ""
59+
httpCaptureHeaders:
60+
request:
61+
- maxLength: 0
62+
name: ""
63+
response:
64+
- maxLength: 0
65+
name: ""
66+
httpLogFormat: ""
67+
status: Disabled
4468
certificateSecret: router-certs-custom
4569
clientTLS:
4670
allowedSubjectPatterns: []
@@ -53,6 +77,8 @@ ingress:
5377
mimeTypes:
5478
- ""
5579
httpEmptyRequestsPolicy: Respond
80+
httpErrorCodePages:
81+
name: ""
5682
listenAddress: []
5783
logEmptyRequests: Log
5884
ports:
@@ -69,7 +95,6 @@ ingress:
6995
minTLSVersion:""
7096
intermediate: {}
7197
old: {}
72-
type: ""
7398
tuningOptions:
7499
clientFinTimeout: 1s
75100
clientTimeout: 30s
@@ -91,7 +116,108 @@ ingress:
91116
|Parameter |Description
92117

93118
|`ingress`
94-
|The `ingress` section of the {microshift-short} `config.yaml` file defines the configurable parameters for the implemented portions of the {OCP} Ingress Control Operator. All parameters in the rest of this table are subsections in the `ingress` section of the `config.yaml`.
119+
|The `ingress` section of the {microshift-short} `config.yaml` file defines the configurable parameters for the implementation of the {OCP} `IngressController` API. All of the following parameters in this table are subsections in the `ingress` section of the {microshift-short} `config.yaml`.
120+
121+
|`accessLogging`
122+
|This `ingress` subsection describes how client requests are logged. If the `status` field is empty, access logging is disabled. When the status field is set to `Enabled`, access requests are logged as configured with the `accessLogging` parameters and the `accessLogging.destination.type` is automatically set to `Container`.
123+
124+
* When enabled, access logging is part of the `openshift-router` logs. Logs from this pod are captured in the sos report procedure for {microshift-short}.
125+
//how come `status` is not first in this list? is it typical for this to be way at the bottom of the config section? it seems like the "on switch")
126+
127+
|`accessLogging.destination`
128+
|A destination for logs. The destination for logs can be a local sidecar container or remote. Default value is null.
129+
130+
|`accessLogging.destination.type`
131+
|The type of destination for logs. Valid values are `Container` or `Syslog`.
132+
133+
* Setting this value to `Container` specifies that logs should go to a sidecar container. The container is called `access-log` and is created when the destination type is `Container`. Using container logs means that logs might be dropped if the rate of logs exceeds the container runtime capacity or the custom logging solution capacity. A custom logging solution that reads logs from this sidecar is required.
134+
135+
* Setting this value to `Syslog` specifies that logs are sent to a Syslog endpoint. You must configure a custom Syslog instance and specify an endpoint that can receive Syslog messages. A custom Syslog instance is required.
136+
//should we supply instructions or links for these actions?
137+
138+
|`accessLogging.destination.container`
139+
|Describes parameters for the `Container` logging destination type. You must configure a custom logging solution that reads logs from this sidecar.
140+
141+
|`accessLogging.destination.container.maxLength`
142+
|Optional configuration. The default value is `1024` bytes. Message length must be at least `480` and not greater than `8192` bytes.
143+
144+
|`accessLogging.destination.syslog`
145+
|Describes parameters for the `Syslog` logging destination type. You must configure a custom Syslog instance with an endpoint that can receive Syslog messages.
146+
147+
|`accessLogging.destination.syslog.address`
148+
|Required configuration when the `Syslog` destination type is set. Valid value is the IP address of the syslog endpoint that receives log messages.
149+
//any conformance for values that we should know about?
150+
151+
|`accessLogging.destination.syslog.facility`
152+
|Optional configuration when the `Syslog` destination type is set. Specifies the syslog facility of log messages. If this field is empty, the facility is `local1`. Otherwise, the field must specify one of the following valid syslog facilities: `kern`, `user`, `mail`, `daemon`, `auth`, `syslog`, `lpr`, `news`, `uucp`, `cron`, auth2`, `ftp`, `ntp`, `audit`, `alert`, `cron2`, `local0`, `local1`, `local2`, `local3`, `local4`, `local5`, `local6`, or `local7`.
153+
154+
|`accessLogging.destination.syslog.maxLength`
155+
|Optional configuration when the `Syslog` destination type is set. The maximum length of the `Syslog` message. Message length must be at least `480` and not greater than `4096` bytes. If this field is empty, the maximum length is set to the default value of `1024` bytes.
156+
157+
|`accessLogging.destination.syslog.port`
158+
|Required configuration when the `Syslog` destination type is set. The UDP port number of the syslog endpoint that receives log messages. The default value is `0`.
159+
160+
|`httpCaptureCookies`
161+
|Specifies HTTP cookies that you want to capture in access logs. If the `httpCaptureCookies` field is empty, access logs do not capture the cookies. Default value is empty. Configuring `ingress.accessLogging.httpCaptureCookies` automatically enables ingress access logging. For any cookie that you want to capture, you must also set the `matchType` and `maxLength` parameters.
162+
163+
* For example:
164+
+
165+
[source,yam]
166+
----
167+
httpCaptureCookies:
168+
- matchType: Exact
169+
maxLength: 128
170+
name: MYCOOKIE
171+
----
172+
173+
|`httpCaptureCookies.matchType`
174+
|Specifies whether the field name of the cookie exactly matches the capture cookie setting or is a prefix of the capture cookie setting. Valid values are `Exact` for an exact string match and `Prefix` for a string prefix match.
175+
176+
* If the `Exact` setting is used, a name must also be specified in the `httpCaptureCookiesname` field.
177+
* If the `Prefix` setting is used, a prefix must be specified in the `httpCaptureCookiesnamePrefix` field. For example, specifying matchType "Prefix" and namePrefix "foo" will capture a cookie named "foo" or "foobar" but not one named "bar". The first matching cookie is captured.
178+
179+
|`httpCaptureCookies.maxLength`
180+
|Specifies tha maximum length of the cookie that is logged, which includes the cookie name, cookie value, and
181+
one-character delimiter. If the log entry exceeds this length, the value is truncated in the log message. The ingress controller might impose a separate bound on the total length of HTTP headers in a request. The minimum value is `1` byte, maximum value is `1024` bytes.
182+
183+
|`httpCaptureCookies.name`
184+
|Specifies the exact name used for a cookie name match as set in the `httpCaptureCookies.matchType` parameter. The value must be a valid HTTP cookie name as defined in link:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1[RFC 6265 section 4.1]. The minimum length is `0` bytes and the maximum length is `1024` bytes.
185+
186+
|`httpCaptureCookies.namePrefix`
187+
|Specifies the prefix for a cookie name match as set in the `httpCaptureCookies.matchType` parameter. The value must be a valid HTTP cookie name as defined in link:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1[RFC 6265 section 4.1]. The minimum length is `0` bytes and the maximum length is `1024` bytes.
188+
189+
|`httpCaptureHeaders`
190+
|Defines the HTTP headers that should be captured in the access logs. This field is a list and allows capturing request and response headers independently. If this field is empty, no headers are captured. This option only applies to 1) plain text HTTP connections and 2) to secure HTTP connections for which the ingress controller terminates encryption: for example, edge-terminated or reencrypt connections. Headers cannot be captured for TLS `passthrough` connections. Configuring `ingress.accessLogging.httpCaptureCookies` automatically enables ingress access logging.
191+
192+
|`httpCaptureHeaders.request`
193+
|Specifies which HTTP request headers to capture. If this field is empty, no request headers are captured.
194+
195+
|`httpCaptureHeaders.request.maxLength`
196+
|Specifies a maximum length for the header value. If a header value exceeds this length, the value is truncated in the log message. The minimum required value is `1` byte. The ingress controller might impose a separate bound on the total length of HTTP headers in a request.
197+
198+
|`httpCaptureHeaders.request.name`
199+
|Specifies a header name. The value must be a valid HTTP header name as defined in link:https://datatracker.ietf.org/doc/html/rfc2616#section-4.2[RFC 2616 section 4.2]. If you configure this value, you must specify `maxLength` and `name` values.
200+
201+
|`httpCaptureHeaders.response`
202+
|Specifies which HTTP response headers to capture. If this field is empty, no response headers are captured.
203+
204+
|`httpCaptureHeaders.response.maxLength`
205+
|Specifies a maximum length for the header value. If a header value exceeds this length, the value is truncated in the
206+
log message. The ingress controller might impose a separate bound on the total length of HTTP headers in a request.
207+
208+
|`httpCaptureHeaders.response.name`
209+
|Specifies a header name. The value must be a valid HTTP header name as defined in link:https://datatracker.ietf.org/doc/html/rfc2616#section-4.2[RFC 2616 section 4.2].
210+
211+
|`httpLogFormat`
212+
|Specifies the format of the log message for an HTTP request. If this field is empty, log messages use the default HTTP log format. For HAProxy default HTTP log format, see the link:https://cbonte.github.io/haproxy-dconv/2.0/configuration.html#8.2.3[HAProxy documentation].
213+
214+
|`status`
215+
|Specifies whether access is logged or not. Valid values are `Enabled` and `Disabled`. Default value is `Disabled`.
216+
217+
* Configuring either `ingress.accessLogging.httpCaptureHeaders` or
218+
`ingress.accessLogging.httpCaptureCookies` automatically sets `ingress.accessLogging.status` to `Enabled`.
219+
* When the `ingress.status` field is set to `Enabled`, the `accessLogging.destination.type` is automatically set to `Container` and the router logs all requests in the `access-log` container.
220+
* If this value is set to `Disabled`, the router does not log any requests in the access log.
95221
96222
|`certificateSecret`
97223
|A reference to a `kubernetes.io/tls` type of secret that contains the default certificate that is served by the {microshift-short} ingress controller. When routes do not specify their own certificate, the `certificateSecret` parameter is used. All secrets used must contain `tls.key` key file contents and `tls.crt` certificate file contents.
@@ -156,6 +282,13 @@ When configured, this field must contain a valid expression or the {microshift-s
156282
* Setting this value to `Log` indicates that an event should be logged.
157283
* Setting this value to `Ignore` sets the `dontlognull` option in the `HAproxy` configuration.
158284
285+
|`httpErrorCodePages`
286+
|Describes custom error code pages. To use this setting, you must configure the `httpErrorCodePages.name` parameter.
287+
//so if I set up `name`, is this setting automatically turned on?
288+
289+
|`httpErrorCodePages.name`
290+
|Specifies custom error code pages. Only errors for `503` and `404` page codes can be customized. To customize error code pages, specify a configmap name. The configmap must be in the `openshift-config` namespace and contain keys in the `error-page-<error code>.http` format where `<error code>` is an HTTP status code. Each value in the configmap must be the full response, including HTTP headers. The default value of this parameter is null.
291+
159292
|`ports`
160293
|Defines default router ports.
161294

0 commit comments

Comments
 (0)