From 11912ac406838013ab838b38c192bbd8b5659eb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Thu, 3 Oct 2024 15:12:18 -0400 Subject: [PATCH] OSDOCS-12192: creates table of parameter explainers for MicroShift config.yaml --- .../microshift-using-config-yaml.adoc | 8 +- .../microshift-config-parameters-table.adoc | 128 ++++++++++++++++++ modules/microshift-config-yaml-custom.adoc | 22 +++ modules/microshift-config-yaml.adoc | 22 +-- .../microshift-custom-ca-reserved-names.adoc | 2 +- modules/microshift-default-settings.adoc | 71 ++++------ .../microshift-greenboot-status-snip.adoc | 2 +- 7 files changed, 187 insertions(+), 68 deletions(-) create mode 100644 modules/microshift-config-parameters-table.adoc create mode 100644 modules/microshift-config-yaml-custom.adoc diff --git a/microshift_configuring/microshift-using-config-yaml.adoc b/microshift_configuring/microshift-using-config-yaml.adoc index 781a41db7f..bce19a4edd 100644 --- a/microshift_configuring/microshift-using-config-yaml.adoc +++ b/microshift_configuring/microshift-using-config-yaml.adoc @@ -10,10 +10,14 @@ A YAML file customizes {microshift-short} instances with your preferences, setti include::snippets/microshift-greenboot-status-snip.adoc[leveloffset=+2] -include::modules/microshift-default-settings.adoc[leveloffset=+1] - include::modules/microshift-config-yaml.adoc[leveloffset=+1] +include::modules/microshift-default-settings.adoc[leveloffset=+2] + +include::modules/microshift-config-yaml-custom.adoc[leveloffset=+1] + +include::modules/microshift-config-parameters-table.adoc[leveloffset=+2] + include::modules/microshift-nw-advertise-address.adoc[leveloffset=+2] include::modules/microshift-config-nodeport-limits.adoc[leveloffset=+2] diff --git a/modules/microshift-config-parameters-table.adoc b/modules/microshift-config-parameters-table.adoc new file mode 100644 index 0000000000..29b1a09167 --- /dev/null +++ b/modules/microshift-config-parameters-table.adoc @@ -0,0 +1,128 @@ +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-using-config-yaml.adoc + +:_mod-docs-content-type: REFERENCE +[id="microshift-config-parameters-table_{context}"] += Parameters and values for the {microshift-short} config.yaml file + +The following table explains {microshift-short} configuration YAML parameters and valid values for each: + +.{microshift-short} `config.yaml` parameters +[cols="3","20%,10%,70%",options="header"] +|=== +|Field|Type|Description + +|`advertiseAddress` +|`string` +|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. + +|`auditLog.maxFileAge` +|`number` +|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. + +|`auditLog.maxFileSize` +|`number` +|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. + +|`auditLog.maxFiles` +|`number` +|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. + +|`auditLog.profile` +|`Default`, `WriteRequestBodies`, `AllRequestBodies`, or `None` +|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. + +|`namedCertificates` +|`list` +|Defines externally generated certificates and domain names by using custom certificate authorities. + +|`namedCertificates.certPath` +|`path` +|The full path to the certificate. + +|`namedCertificates.keyPath` +|`path` +|The full path to the certificate key. + +|`namedCertificates.names` +|`list` +|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. + +|`subjectAltNames` +|Fully qualified domain names (FQDNs), wildcards such as `*.domain.com`, or IP addresses +|Subject Alternative Names for API server certificates. SANs indicate all of the domain names and IP addresses that are secured by a certificate. + +|`debugging.logLevel` +|`Normal`, `Debug`, `Trace`, or `TraceAll` +|Log verbosity. Default is `Normal`. + +|`dns.baseDomain` +|`valid domain` +|Base domain of the cluster. All managed DNS records are subdomains of this base. + +|`etcd.memoryLimitMB` +|`number` +|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. + +|`ingress.listenAddress` +|IP address, NIC name, or multiple +|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. + +|`ingress.ports.http` +|`80` +|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. + +|`ingress.ports.https` +|`443` +|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. + +|`ingress.routeAdmissionPolicy. + namespaceOwnership` +|`Strict` or `InterNamespaceAllowed` +|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. + +|`ingress.status` +|`Managed` or `Removed` +|Router status. Default is `Managed`. + +|`kubelet` +|See the {microshift-short} low-latency instructions +|Parameter for passthrough configuration of the kubelet node agent. Used for low-latency configuration. Default value is null. + +|`manifests` +|`list of paths` +|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/`. + +|`network.clusterNetwork` +|IP address block +|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`. + +|`network.serviceNetwork` +|IP address block +|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`. + +|`network.serviceNodePortRange` +|`range` +|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. + +|`node.hostnameOverride` +|`string` +|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. + +|`node.nodeIP` +|IPv4 address +|The IPv4 address of the node. The default value is the IP address of the default route. + +|`nodeIPv6` +|IPv6 address +|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. + +|`storage.driver` +|`none` or `lvms` +|Default value is empty. An empty value or null field defaults to LVMS deployment. + +|`storage.optionalCsiComponents` +|`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. +|=== diff --git a/modules/microshift-config-yaml-custom.adoc b/modules/microshift-config-yaml-custom.adoc new file mode 100644 index 0000000000..4ec296564d --- /dev/null +++ b/modules/microshift-config-yaml-custom.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-using-config-yaml.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-yaml-custom_{context}"] += Using custom settings +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}. + +[IMPORTANT] +==== +Restart {microshift-short} after changing any configuration settings to have them take effect. The `config.yaml` file is read only when {microshift-short} starts. +==== + +[id="microshift-yaml-custom-settings_{context}"] +== Separate restarts +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. + +[TIP] +==== +If you add all of the configurations you need at the same time, you can minimize system restarts. +==== \ No newline at end of file diff --git a/modules/microshift-config-yaml.adoc b/modules/microshift-config-yaml.adoc index 7e8ee3b1d2..573ad119a5 100644 --- a/modules/microshift-config-yaml.adoc +++ b/modules/microshift-config-yaml.adoc @@ -1,27 +1,11 @@ // Module included in the following assemblies: // -// * microshift_configuring/using-config-tools.adoc +// * microshift_configuring/microshift-using-config-yaml.adoc :_mod-docs-content-type: CONCEPT [id="microshift-config-yaml_{context}"] -= Using a YAML configuration file += The {microshift-short} YAML configuration file 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. -[id="microshift-yaml-custom_{context}"] -== Custom settings -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}. - -[IMPORTANT] -==== -Restart {microshift-short} after changing any configuration settings to have them take effect. The `config.yaml` file is read only when {microshift-short} starts. -==== - -[id="microshift-yaml-custom-settings_{context}"] -== Separate restarts -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. - -[TIP] -==== -If you add all of the configurations you need at the same time, you can minimize system restarts. -==== +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. diff --git a/modules/microshift-custom-ca-reserved-names.adoc b/modules/microshift-custom-ca-reserved-names.adoc index 30160e5bb9..88d3ba69dd 100644 --- a/modules/microshift-custom-ca-reserved-names.adoc +++ b/modules/microshift-custom-ca-reserved-names.adoc @@ -10,7 +10,7 @@ The following certificate problems cause {microshift-short} to ignore certificat * The certificate files do not exist on the disk or are not readable. * The certificate is not parsable. -* The certificate overrides the internal certificates IPAddress/DNSNames in a `SubjectAlternativeNames` (SAN) field. Do not use a reserved name when configuring SANs. +* 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. .Reserved Names values [cols="<,<,<",options="header",] diff --git a/modules/microshift-default-settings.adoc b/modules/microshift-default-settings.adoc index ac2416db37..7c35d7acb6 100644 --- a/modules/microshift-default-settings.adoc +++ b/modules/microshift-default-settings.adoc @@ -21,33 +21,33 @@ $ microshift show-config apiServer: advertiseAddress: 10.44.0.0/32 # <1> auditLog: - maxFileAge: 0 # <2> - maxFileSize: 200 # <3> - maxFiles: 10 # <4> - profile: Default # <5> + maxFileAge: 0 + maxFileSize: 200 + maxFiles: 10 + profile: Default namedCertificates: - certPath: "" keyPath: "" names: - "" - subjectAltNames: [] # <6> + subjectAltNames: [] debugging: - logLevel: "Normal" # <7> + logLevel: "Normal" dns: - baseDomain: microshift.example.com # <8> + baseDomain: microshift.example.com etcd: - memoryLimitMB: 0 # <9> + memoryLimitMB: 0 ingress: listenAddress: - - "" # <10> - ports: # <11> + - "" + ports: http: 80 https: 443 routeAdmissionPolicy: - namespaceOwnership: InterNamespaceAllowed # <12> - status: Managed # <13> -kubelet: # <14> -manifests: # <15> + namespaceOwnership: InterNamespaceAllowed + status: Managed +kubelet: +manifests: kustomizePaths: - /usr/lib/microshift/manifests - /usr/lib/microshift/manifests.d/* @@ -55,39 +55,20 @@ manifests: # <15> - /etc/microshift/manifests.d/* network: clusterNetwork: - - 10.42.0.0/16 # <16> + - 10.42.0.0/16 serviceNetwork: - - 10.43.0.0/16 # <17> - serviceNodePortRange: 30000-32767 # <18> + - 10.43.0.0/16 + serviceNodePortRange: 30000-32767 node: - hostnameOverride: "" # <19> - nodeIP: "" # <20> - nodeIPv6: "" # <21> + hostnameOverride: "" + nodeIP: "" # <2> + nodeIPv6: "" storage: - driver: "" # <22> - optionalCsiComponents: # <23> + driver: "" # <3> + optionalCsiComponents: # <4> - "" ---- -<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. -<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. -<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. -<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. -<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. -<6> Subject Alternative Names for API server certificates. -<7> Log verbosity. Valid values for this field are `Normal`, `Debug`, `Trace`, or `TraceAll`. -<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. -<9> Base domain of the cluster. All managed DNS records are subdomains of this base. -<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. -<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. -<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. -<13> Default router status, can be `Managed` or `Removed`. -<14> Parameter for configuring kubelet. Used for low-latency configuration. Default value is null. -<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. -<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. -<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. -<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. -<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. -<20> The IPv4 address of the node. The default value is the IP address of the default route. -<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. -<22> Default value is empty. Valid values are "none" or "lvms". An empty value or null field defaults to LVMS deployment. -<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. +<1> Calculated based on the address of the service network. +<2> The IP address of the default route. +<3> Default null value deploys Logical Volume Managed Storage (LVMS). +<4> Default null value deploys `snapshot-controller` and `snapshot-webhook`. \ No newline at end of file diff --git a/snippets/microshift-greenboot-status-snip.adoc b/snippets/microshift-greenboot-status-snip.adoc index c409a00472..4120733649 100644 --- a/snippets/microshift-greenboot-status-snip.adoc +++ b/snippets/microshift-greenboot-status-snip.adoc @@ -10,5 +10,5 @@ [NOTE] ==== -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. +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. ==== \ No newline at end of file