Skip to content

Commit 32dc9e9

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #83051 from ShaunaDiaz/OSDOCS-12192
OSDOCS-12192: table of parameter explainers for config.yaml
2 parents 08b43af + 8bb4a16 commit 32dc9e9

7 files changed

+187
-68
lines changed

‎microshift_configuring/microshift-using-config-yaml.adoc

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,14 @@ A YAML file customizes {microshift-short} instances with your preferences, setti
1010

1111
include::snippets/microshift-greenboot-status-snip.adoc[leveloffset=+2]
1212

13-
include::modules/microshift-default-settings.adoc[leveloffset=+1]
14-
1513
include::modules/microshift-config-yaml.adoc[leveloffset=+1]
1614

15+
include::modules/microshift-default-settings.adoc[leveloffset=+2]
16+
17+
include::modules/microshift-config-yaml-custom.adoc[leveloffset=+1]
18+
19+
include::modules/microshift-config-parameters-table.adoc[leveloffset=+2]
20+
1721
include::modules/microshift-nw-advertise-address.adoc[leveloffset=+2]
1822

1923
include::modules/microshift-config-nodeport-limits.adoc[leveloffset=+2]

‎modules/microshift-config-parameters-table.adoc

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-using-config-yaml.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="microshift-config-parameters-table_{context}"]
7+
= Parameters and values for the {microshift-short} config.yaml file
8+
9+
The following table explains {microshift-short} configuration YAML parameters and valid values for each:
10+
11+
.{microshift-short} `config.yaml` parameters
12+
[cols="3","20%,10%,70%",options="header"]
13+
|===
14+
|Field|Type|Description
15+
16+
|`advertiseAddress`
17+
|`string`
18+
|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.
19+
20+
|`auditLog.maxFileAge`
21+
|`number`
22+
|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.
23+
24+
|`auditLog.maxFileSize`
25+
|`number`
26+
|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.
27+
28+
|`auditLog.maxFiles`
29+
|`number`
30+
|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.
31+
32+
|`auditLog.profile`
33+
|`Default`, `WriteRequestBodies`, `AllRequestBodies`, or `None`
34+
|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.
35+
36+
|`namedCertificates`
37+
|`list`
38+
|Defines externally generated certificates and domain names by using custom certificate authorities.
39+
40+
|`namedCertificates.certPath`
41+
|`path`
42+
|The full path to the certificate.
43+
44+
|`namedCertificates.keyPath`
45+
|`path`
46+
|The full path to the certificate key.
47+
48+
|`namedCertificates.names`
49+
|`list`
50+
|Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If no names are provided, the implicit names are extracted from the certificates.
51+
52+
|`subjectAltNames`
53+
|Fully qualified domain names (FQDNs), wildcards such as `*.domain.com`, or IP addresses
54+
|Subject Alternative Names for API server certificates. SANs indicate all of the domain names and IP addresses that are secured by a certificate.
55+
56+
|`debugging.logLevel`
57+
|`Normal`, `Debug`, `Trace`, or `TraceAll`
58+
|Log verbosity. Default is `Normal`.
59+
60+
|`dns.baseDomain`
61+
|`valid domain`
62+
|Base domain of the cluster. All managed DNS records are subdomains of this base.
63+
64+
|`etcd.memoryLimitMB`
65+
|`number`
66+
|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.
67+
68+
|`ingress.listenAddress`
69+
|IP address, NIC name, or multiple
70+
|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.
71+
72+
|`ingress.ports.http`
73+
|`80`
74+
|Default port shown. Configurable. Valid value is a single, unique port in the 1-65535 range. The values of the `ports.http` and `ports.https` fields cannot be the same.
75+
76+
|`ingress.ports.https`
77+
|`443`
78+
|Default port shown. Configurable. Valid value is a single, unique port in the 1-65535 range. The values of the `ports.http` and `ports.https` fields cannot be the same.
79+
80+
|`ingress.routeAdmissionPolicy.
81+
namespaceOwnership`
82+
|`Strict` or `InterNamespaceAllowed`
83+
|Describes how hostname claims across namespaces are handled. By default, allows routes to claim different paths of the same hostname across namespaces. 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.
84+
85+
|`ingress.status`
86+
|`Managed` or `Removed`
87+
|Router status. Default is `Managed`.
88+
89+
|`kubelet`
90+
|See the {microshift-short} low-latency instructions
91+
|Parameter for passthrough configuration of the kubelet node agent. Used for low-latency configuration. Default value is null.
92+
93+
|`manifests`
94+
|`list of paths`
95+
|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. Default values are `/usr/lib/microshift/manifests`, `/usr/lib/microshift/manifests.d/`, `/etc/microshift/manifests`, and `/etc/microshift/manifests.d/`.
96+
97+
|`network.clusterNetwork`
98+
|IP address block
99+
|A block of IP addresses from which pod IP addresses are allocated. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after {microshift-short} starts. Default range is `10.42.0.0/16`.
100+
101+
|`network.serviceNetwork`
102+
|IP address block
103+
|A block of virtual IP addresses for Kubernetes services. IP address pool for services. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after {microshift-short} starts. Default range is `10.43.0.0/16`.
104+
105+
|`network.serviceNodePortRange`
106+
|`range`
107+
|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 {microshift-short} starts.
108+
109+
|`node.hostnameOverride`
110+
|`string`
111+
|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. This value is immutable after {microshift-short} starts.
112+
113+
|`node.nodeIP`
114+
|IPv4 address
115+
|The IPv4 address of the node. The default value is the IP address of the default route.
116+
117+
|`nodeIPv6`
118+
|IPv6 address
119+
|The IPv6 address for the node for dual-stack configurations. Cannot be configured in single stack for either IPv4 or IPv6. Default is an empty value or null.
120+
121+
|`storage.driver`
122+
|`none` or `lvms`
123+
|Default value is empty. An empty value or null field defaults to LVMS deployment.
124+
125+
|`storage.optionalCsiComponents`
126+
|`array`
127+
|Default value is null or an empty array. A null or empty array defaults to deploying `snapshot-controller` and `snapshot-webhook`. Expected values are `csi-snapshot-controller`, `csi-snapshot-webhook`, or `none`. An entry of `none` is mutually exclusive with all other values.
128+
|===

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-using-config-yaml.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="microshift-yaml-custom_{context}"]
7+
= Using custom settings
8+
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}.
9+
10+
[IMPORTANT]
11+
====
12+
Restart {microshift-short} after changing any configuration settings to have them take effect. The `config.yaml` file is read only when {microshift-short} starts.
13+
====
14+
15+
[id="microshift-yaml-custom-settings_{context}"]
16+
== Separate restarts
17+
Applications and other optional services used with your {microshift-short} cluster might also need to be restarted separately to apply configuration changes throughout the cluster. For example, when making changes to certain networking settings, you must stop and restart service and application pods to apply those changes. See each procedure for the task you are completing for more information.
18+
19+
[TIP]
20+
====
21+
If you add all of the configurations you need at the same time, you can minimize system restarts.
22+
====

‎modules/microshift-config-yaml.adoc

Lines changed: 3 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,11 @@
11
// Module included in the following assemblies:
22
//
3-
// * microshift_configuring/using-config-tools.adoc
3+
// * microshift_configuring/microshift-using-config-yaml.adoc
44

55
:_mod-docs-content-type: CONCEPT
66
[id="microshift-config-yaml_{context}"]
7-
= Using a YAML configuration file
7+
= The {microshift-short} YAML configuration file
88

99
At start up, {microshift-short} checks the system-wide `/etc/microshift/` directory for a configuration file named `config.yaml`. If the configuration file does not exist in the directory, built-in default values are used to start the service.
1010

11-
[id="microshift-yaml-custom_{context}"]
12-
== Custom settings
13-
To create custom configurations, make a copy of the provided `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}.
14-
15-
[IMPORTANT]
16-
====
17-
Restart {microshift-short} after changing any configuration settings to have them take effect. The `config.yaml` file is read only when {microshift-short} starts.
18-
====
19-
20-
[id="microshift-yaml-custom-settings_{context}"]
21-
== Separate restarts
22-
Applications and other optional services used with your {microshift-short} cluster might also need to be restarted separately to apply configuration changes throughout the cluster. For example, when making changes to certain networking settings, you must stop and restart service and application pods to apply those changes. See each procedure for the task you are completing for more information.
23-
24-
[TIP]
25-
====
26-
If you add all of the configurations you need at the same time, you can minimize system restarts.
27-
====
11+
The {microshift-short} configuration file must be used in combination with host and, sometimes, application and service settings. Ensure that each item is configured in tandem when you customize your {microshift-short} cluster.

‎modules/microshift-custom-ca-reserved-names.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ The following certificate problems cause {microshift-short} to ignore certificat
1010

1111
* The certificate files do not exist on the disk or are not readable.
1212
* The certificate is not parsable.
13-
* The certificate overrides the internal certificates IPAddress/DNSNames in a `SubjectAlternativeNames` (SAN) field. Do not use a reserved name when configuring SANs.
13+
* The certificate overrides the internal certificates IP addresses or DNS names in a `SubjectAlternativeNames` (SAN) field. Do not use a reserved name when configuring SANs.
1414
1515
.Reserved Names values
1616
[cols="<,<,<",options="header",]

‎modules/microshift-default-settings.adoc

Lines changed: 26 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -21,73 +21,54 @@ $ microshift show-config
2121
apiServer:
2222
advertiseAddress: 10.44.0.0/32 # <1>
2323
auditLog:
24-
maxFileAge: 0 # <2>
25-
maxFileSize: 200 # <3>
26-
maxFiles: 10 # <4>
27-
profile: Default # <5>
24+
maxFileAge: 0
25+
maxFileSize: 200
26+
maxFiles: 10
27+
profile: Default
2828
namedCertificates:
2929
- certPath: ""
3030
keyPath: ""
3131
names:
3232
- ""
33-
subjectAltNames: [] # <6>
33+
subjectAltNames: []
3434
debugging:
35-
logLevel: "Normal" # <7>
35+
logLevel: "Normal"
3636
dns:
37-
baseDomain: microshift.example.com # <8>
37+
baseDomain: microshift.example.com
3838
etcd:
39-
memoryLimitMB: 0 # <9>
39+
memoryLimitMB: 0
4040
ingress:
4141
listenAddress:
42-
- "" # <10>
43-
ports: # <11>
42+
- ""
43+
ports:
4444
http: 80
4545
https: 443
4646
routeAdmissionPolicy:
47-
namespaceOwnership: InterNamespaceAllowed # <12>
48-
status: Managed # <13>
49-
kubelet: # <14>
50-
manifests: # <15>
47+
namespaceOwnership: InterNamespaceAllowed
48+
status: Managed
49+
kubelet:
50+
manifests:
5151
kustomizePaths:
5252
- /usr/lib/microshift/manifests
5353
- /usr/lib/microshift/manifests.d/*
5454
- /etc/microshift/manifests
5555
- /etc/microshift/manifests.d/*
5656
network:
5757
clusterNetwork:
58-
- 10.42.0.0/16 # <16>
58+
- 10.42.0.0/16
5959
serviceNetwork:
60-
- 10.43.0.0/16 # <17>
61-
serviceNodePortRange: 30000-32767 # <18>
60+
- 10.43.0.0/16
61+
serviceNodePortRange: 30000-32767
6262
node:
63-
hostnameOverride: "" # <19>
64-
nodeIP: "" # <20>
65-
nodeIPv6: "" # <21>
63+
hostnameOverride: ""
64+
nodeIP: "" # <2>
65+
nodeIPv6: ""
6666
storage:
67-
driver: "" # <22>
68-
optionalCsiComponents: # <23>
67+
driver: "" # <3>
68+
optionalCsiComponents: # <4>
6969
- ""
7070
----
71-
<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.
72-
<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.
73-
<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.
74-
<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.
75-
<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.
76-
<6> Subject Alternative Names for API server certificates.
77-
<7> Log verbosity. Valid values for this field are `Normal`, `Debug`, `Trace`, or `TraceAll`.
78-
<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.
79-
<9> Base domain of the cluster. All managed DNS records are subdomains of this base.
80-
<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.
81-
<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.
82-
<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.
83-
<13> Default router status, can be `Managed` or `Removed`.
84-
<14> Parameter for configuring kubelet. Used for low-latency configuration. Default value is null.
85-
<15> 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.
86-
<16> A block of IP addresses from which pod IP addresses are allocated. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after installation.
87-
<17> A block of virtual IP addresses for Kubernetes services. IP address pool for services. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after installation.
88-
<18> 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.
89-
<19> 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. You cannot change this immutable setting after {microshift-short} starts for the first time.
90-
<20> The IPv4 address of the node. The default value is the IP address of the default route.
91-
<21> The IPv6 address for the node for dual-stack configurations. Cannot be configured in single stack for either IPv4 or IPv6. Default is empty or null.
92-
<22> Default value is empty. Valid values are "none" or "lvms". An empty value or null field defaults to LVMS deployment.
93-
<23> Array. Default value is null or an empty array. A null or empty array defaults to deploying `snapshot-controller` and `snapshot-webhook`. Expected values are `csi-snapshot-controller`, `csi-snapshot-webhook`, or `none`. An entry of `none` is mutually exclusive with all other values.
71+
<1> Calculated based on the address of the service network.
72+
<2> The IP address of the default route.
73+
<3> Default null value deploys Logical Volume Managed Storage (LVMS).
74+
<4> Default null value deploys `snapshot-controller` and `snapshot-webhook`.

‎snippets/microshift-greenboot-status-snip.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,5 @@
1010

1111
[NOTE]
1212
====
13-
If you want to make configuration changes or deploy applications through the {microshift-short} API with tools other than `kustomize` manifests, you must wait until the Greenboot health checks have finished. This ensures that your changes are not lost if Greenboot rolls your `rpm-ostree` system back to an earlier state.
13+
If you want to make configuration changes or deploy applications through the {microshift-short} API with tools other than `kustomize` manifests, you must wait until the greenboot health checks have finished. This ensures that your changes are not lost if greenboot rolls your `rpm-ostree` system back to an earlier state.
1414
====

0 commit comments

Comments
 (0)