diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index 37eb68c302be..5eb75850d220 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_topic_maps/_topic_map_ms.yml @@ -113,15 +113,19 @@ Name: Configuring Dir: microshift_configuring Distros: microshift Topics: -- Name: Using the MicroShift configuration file +- Name: About the default MicroShift configuration file + File: microshift-default-config-yaml +- Name: Customizing MicroShift by using the configuration file File: microshift-using-config-yaml +- Name: Using configuration snippets + File: microshift-config-snippets - Name: Configuring IPv6 networking File: microshift-nw-ipv6-config - Name: Using ingress control for a MicroShift cluster File: microshift-ingress-controller - Name: Disabling LVMS CSI provider and CSI snapshot File: microshift-disable-lvms-csi-provider-csi-snapshot -- Name: Checking the status of Greenboot health checks +- Name: Checking the status of greenboot health checks File: microshift-greenboot-checking-status - Name: Cluster access with kubeconfig files File: microshift-cluster-access-kubeconfig diff --git a/microshift_configuring/microshift-config-snippets.adoc b/microshift_configuring/microshift-config-snippets.adoc new file mode 100644 index 000000000000..17520c76e953 --- /dev/null +++ b/microshift_configuring/microshift-config-snippets.adoc @@ -0,0 +1,15 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-config-snippets"] +include::_attributes/attributes-microshift.adoc[] += Using {microshift-short} configuration snippets +:context: microshift-config-snippets + +If you want to configure one or two settings, use the `/etc/microshift/config.d/` configuration directory to drop in configuration snippet YAML files. + +include::modules/microshift-how-config-snippets-work.adoc[leveloffset=+1] + +include::modules/microshift-example-config-snippets-list.adoc[leveloffset=+1] + +include::modules/microshift-example-config-snippets-objects.adoc[leveloffset=+1] + +include::modules/microshift-example-mixed-config-snippets.adoc[leveloffset=+1] diff --git a/microshift_configuring/microshift-default-config-yaml.adoc b/microshift_configuring/microshift-default-config-yaml.adoc new file mode 100644 index 000000000000..b4b2f8ae7694 --- /dev/null +++ b/microshift_configuring/microshift-default-config-yaml.adoc @@ -0,0 +1,23 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-default-config-yaml"] +include::_attributes/attributes-microshift.adoc[] += About the default {microshift-short} configuration file +:context: microshift-default-config-yaml + +toc::[] + +The {microshift-short} built-in default settings are listed in a YAML file. + +include::modules/microshift-config-rhde-con.adoc[leveloffset=+1] + +include::snippets/microshift-greenboot-status-snip.adoc[leveloffset=+2] + +include::modules/microshift-config-yaml.adoc[leveloffset=+1] + +include::modules/microshift-default-settings.adoc[leveloffset=+2] + +//[id="additional-resources_microshift-using-config-yaml_{context}"] +//[role="_additional-resources"] +//== Additional resources + +//* xref:../microshift-using-config-yaml.adoc#microshift-using-config-yaml[Customizing {microshift-short} by using the configuration file] diff --git a/microshift_configuring/microshift-gdp.adoc b/microshift_configuring/microshift-gdp.adoc index 5f58943e4659..4f0722647707 100644 --- a/microshift_configuring/microshift-gdp.adoc +++ b/microshift_configuring/microshift-gdp.adoc @@ -27,7 +27,7 @@ include::modules/microshift-ref-generic-device-plugin-troubleshooting.adoc[level [id="_additional-resources_microshift-gdp_{context}"] == Additional resources -* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-yaml_microshift-configuring[The {microshift-short} YAML configuration file] +//* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-using-config-yaml[Customizing {microshift-short} by using the configuration file] * xref:../microshift_networking/microshift-networking-settings.adoc#microshift-understanding-networking-settings[Understanding networking settings] * xref:../microshift_networking/microshift_multiple_networks/microshift-cni-multus.adoc#microshift-cni-multus[About using multiple networks] * xref:../microshift_networking/microshift_network_policy/microshift-network-policy-index.adoc#microshift-network-policies[About network policies] diff --git a/microshift_configuring/microshift-ingress-controller.adoc b/microshift_configuring/microshift-ingress-controller.adoc index 1e302385f87b..bad534ffc695 100644 --- a/microshift_configuring/microshift-ingress-controller.adoc +++ b/microshift_configuring/microshift-ingress-controller.adoc @@ -20,6 +20,6 @@ include::modules/microshift-ingress-controller-tls-config.adoc[leveloffset=+2] [role="_additional-resources"] == Additional resources -* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-snippets_microshift-configuring[Using configuration snippets] +//* xref:../microshift_configuring/microshift-config-snippets.adoc#microshift-config-snippets[Using configuration snippets] * link:https://docs.redhat.com/container-platform/latest/networking/networking_operators/ingress-operator.html#nw-http2-haproxy_configuring-ingress[Enabling HTTP/2 Ingress connectivity] ({OCP} documentation) diff --git a/microshift_configuring/microshift-using-config-yaml.adoc b/microshift_configuring/microshift-using-config-yaml.adoc index 204c75dd5ea6..37515e62e50e 100644 --- a/microshift_configuring/microshift-using-config-yaml.adoc +++ b/microshift_configuring/microshift-using-config-yaml.adoc @@ -1,37 +1,27 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-using-config-yaml"] include::_attributes/attributes-microshift.adoc[] -= Using the {microshift-short} configuration file -:context: microshift-configuring - -:FeatureName: The Generic Device Plugin for {microshift-short} - -include::snippets/technology-preview.adoc[] += Customizing {microshift-short} by using the configuration file +:context: microshift-using-config-yaml toc::[] -A YAML file customizes {microshift-short} instances with your preferences, settings, and parameters. - -include::modules/microshift-config-rhde-con.adoc[leveloffset=+1] - -include::snippets/microshift-greenboot-status-snip.adoc[leveloffset=+2] +Use the {microshift-short} YAML file to customize your preferences, settings, and parameters. -include::modules/microshift-config-yaml.adoc[leveloffset=+1] +:FeatureName: The Generic Device Plugin for {microshift-short} -include::modules/microshift-default-settings.adoc[leveloffset=+2] +include::snippets/technology-preview.adoc[] include::modules/microshift-config-yaml-custom.adoc[leveloffset=+1] include::modules/microshift-config-parameters-table.adoc[leveloffset=+2] -include::modules/microshift-config-snippets.adoc[leveloffset=+2] - include::modules/microshift-nw-advertise-address.adoc[leveloffset=+2] include::modules/microshift-config-nodeport-limits.adoc[leveloffset=+2] -[role="_additional-resources"] [id="additional-resources_microshift-using-config-yaml_{context}"] +[role="_additional-resources"] == Additional resources * xref:../../microshift-greenboot-checking-status.adoc#microshift-greenboot-checking-status[Checking Greenboot status] diff --git a/microshift_configuring/microshift_auth_security/microshift-tls-config.adoc b/microshift_configuring/microshift_auth_security/microshift-tls-config.adoc index 65d483931b43..cd6e75865c65 100644 --- a/microshift_configuring/microshift_auth_security/microshift-tls-config.adoc +++ b/microshift_configuring/microshift_auth_security/microshift-tls-config.adoc @@ -18,10 +18,10 @@ include::modules/microshift-tls-default-cipher-suites.adoc[leveloffset=+2] [role="_additional-resources"] == Additional resources -* xref:../../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-snippets_microshift-configuring[Using configuration snippets]. +//* xref:../microshift-config-snippets.adoc#microshift-config-snippets[Using configuration snippets] -* To secure pods using security content constraints (SCC), see xref:../../microshift_running_apps/microshift-authentication.adoc#authentication-microshift[Pod security authentication and authorization]. +* To secure pods using security content constraints (SCC), see xref:../../microshift_running_apps/microshift-authentication.adoc#authentication-microshift[Pod security authentication and authorization] -* xref:../../microshift_configuring/microshift-cluster-access-kubeconfig.adoc#microshift-kubeconfig[Cluster access with kubeconfig]. +* xref:../../microshift_configuring/microshift-cluster-access-kubeconfig.adoc#microshift-kubeconfig[Cluster access with kubeconfig] -* xref:../microshift_auth_security/microshift-custom-ca.adoc#microshift-custom-ca[Configuring custom certificate authorities]. \ No newline at end of file +* xref:../microshift_auth_security/microshift-custom-ca.adoc#microshift-custom-ca[Configuring custom certificate authorities] \ No newline at end of file diff --git a/microshift_configuring/microshift_low_latency/microshift-low-latency.adoc b/microshift_configuring/microshift_low_latency/microshift-low-latency.adoc index afc622b34530..2aea73e98fea 100644 --- a/microshift_configuring/microshift_low_latency/microshift-low-latency.adoc +++ b/microshift_configuring/microshift_low_latency/microshift-low-latency.adoc @@ -23,7 +23,7 @@ include::modules/microshift-low-latency-config-yaml.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources //TODO * workload partitioning crossref here -* xref:../../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-yaml_microshift-configuring[Using a YAML configuration file] +//* xref:../../microshift_configuring/microshift-using-config-yaml.adoc#microshift-using-config-yaml[Customizing {microshift-short} by using the configuration file] * link:https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/#kubelet-config-k8s-io-v1beta1-KubeletConfiguration[KubeletConfiguration reference] (Kubernetes upstream documentation) //RHEL TuneD diff --git a/microshift_install_rpm/microshift-install-rpm.adoc b/microshift_install_rpm/microshift-install-rpm.adoc index 4196a6b71dc8..de0413a80e30 100644 --- a/microshift_install_rpm/microshift-install-rpm.adoc +++ b/microshift_install_rpm/microshift-install-rpm.adoc @@ -20,11 +20,11 @@ include::modules/microshift-install-rpm-preparing.adoc[leveloffset=+1] //additional resources for install rpm prep module [role="_additional-resources"] .Additional resources -* Download the link:https://console.redhat.com/openshift/install/pull-secret[pull secret] from the Red Hat Hybrid Cloud Console. -* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-using-config-yaml[Configuring MicroShift]. -* For more options on partition configuration, read link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/performing_a_standard_rhel_9_installation/index#manual-partitioning_graphical-installation[Configuring Manual Partitioning]. +* Download the link:https://console.redhat.com/openshift/install/pull-secret[pull secret] from the Red Hat Hybrid Cloud Console +//* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-using-config-yaml[Customizing {microshift-short} by using the configuration file] +* For more options on partition configuration, read link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/performing_a_standard_rhel_9_installation/index#manual-partitioning_graphical-installation[Configuring Manual Partitioning] * For more information about resizing your existing LVs to free up capacity in your VGs, read link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/configuring_and_managing_logical_volumes/index#managing-lvm-volume-groups_configuring-and-managing-logical-volumes[Managing LVM Volume Groups]. -* For more information about creating VGs and PVs, read link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/overview-of-logical-volume-management_configuring-and-managing-logical-volumes[Overview of logical volume management]. +* For more information about creating VGs and PVs, read link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/overview-of-logical-volume-management_configuring-and-managing-logical-volumes[Overview of logical volume management] include::modules/microshift-install-rpms.adoc[leveloffset=+1] @@ -43,7 +43,7 @@ include::modules/microshift-accessing.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* xref:../microshift_cli_ref/microshift-oc-cli-install.adoc#microshift-oc-cli-install[Installing the OpenShift CLI tool]. +* xref:../microshift_cli_ref/microshift-oc-cli-install.adoc#microshift-oc-cli-install[Installing the OpenShift CLI tool] include::modules/microshift-accessing-cluster-locally.adoc[leveloffset=+2] diff --git a/microshift_networking/microshift-cni.adoc b/microshift_networking/microshift-cni.adoc index 981b1ae25808..2edb7d67400f 100644 --- a/microshift_networking/microshift-cni.adoc +++ b/microshift_networking/microshift-cni.adoc @@ -69,7 +69,7 @@ include::modules/microshift-nw-topology.adoc[leveloffset=+1] [role="_additional-resources"] == Additional resources -* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-yaml_microshift-configuring[Using a YAML configuration file] +//* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-using-config-yaml[Customizing {microshift-short} by using the configuration file] * xref:../microshift_networking/microshift-networking-settings.adoc#microshift-understanding-networking-settings[Understanding networking settings] * xref:../microshift_networking/microshift_multiple_networks/microshift-cni-multus.adoc#microshift-cni-multus[About using multiple networks] * xref:../microshift_networking/microshift_network_policy/microshift-network-policy-index.adoc#microshift-network-policies[About network policies] \ No newline at end of file diff --git a/microshift_networking/microshift-nw-router.adoc b/microshift_networking/microshift-nw-router.adoc index 08e460856a3f..b9bfbca955e3 100644 --- a/microshift_networking/microshift-nw-router.adoc +++ b/microshift_networking/microshift-nw-router.adoc @@ -24,7 +24,7 @@ include::modules/microshift-nw-router-config-ip-address.adoc[leveloffset=+2] [role="_additional-resources"] [id="additional-resources_microshift-understanding-and-configuring-router_{context}"] == Additional resources -* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-yaml-default_microshift-using-config-yaml[Default settings] ({microshift-short}) +* xref:../microshift_configuring/microshift-default-config-yaml.adoc#microshift-default-config-yaml[About the default {microshift-short} configuration file] * xref:../microshift_networking/microshift_network_policy/microshift-network-policy-index.adoc#microshift-network-policies[About network policies] diff --git a/microshift_support/microshift-remote-cluster-monitoring.adoc b/microshift_support/microshift-remote-cluster-monitoring.adoc index d2105142c92e..2910a324144f 100644 --- a/microshift_support/microshift-remote-cluster-monitoring.adoc +++ b/microshift_support/microshift-remote-cluster-monitoring.adoc @@ -14,7 +14,7 @@ include::modules/microshift-info-collected-telemetry.adoc[leveloffset=+1] include::modules/microshift-opt-out-telemetry.adoc[leveloffset=+1] -[id="additional-resources_microshift-remote-cluster-monitoring_{context}"] -== Additional resources +//[id="additional-resources_microshift-remote-cluster-monitoring_{context}"] +//== Additional resources -* xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-snippets_microshift-configuring[Using configuration snippets]. \ No newline at end of file +//* xref:../microshift_configuring/microshift-config-snippets.adoc#microshift-config-snippets[Using configuration snippets]. \ No newline at end of file diff --git a/modules/microshift-config-nodeport-limits.adoc b/modules/microshift-config-nodeport-limits.adoc index 33e3b505c92a..5033d970c26f 100644 --- a/modules/microshift-config-nodeport-limits.adoc +++ b/modules/microshift-config-nodeport-limits.adoc @@ -46,7 +46,7 @@ Consider the following when configuring the NodePort service ranges: |etcd port |6443 -|kubernetes API +|Kubernetes API |8445/tcp |openshift-route-controller-manager diff --git a/modules/microshift-config-parameters-table.adoc b/modules/microshift-config-parameters-table.adoc index 7c18f398fbbb..9c104aff5ef1 100644 --- a/modules/microshift-config-parameters-table.adoc +++ b/modules/microshift-config-parameters-table.adoc @@ -19,15 +19,15 @@ The following table explains {microshift-short} configuration YAML parameters an |`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. +|How long log files are stored before automatic deletion. The default value of `0` in the `maxFileAge` parameter means a log file is never deleted based on age. You can configure this value. |`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. +|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. You can configure this value. |`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. +|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. You can configure this value. |`auditLog.profile` |`Default`, `WriteRequestBodies`, `AllRequestBodies`, or `None` @@ -47,7 +47,7 @@ The following table explains {microshift-short} configuration YAML parameters an |`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. +|Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If you do not list names, the implicit names are extracted from the certificates. |`subjectAltNames` |Fully qualified domain names (FQDNs), wildcards such as `*.domain.com`, or IP addresses. diff --git a/modules/microshift-config-rhde-con.adoc b/modules/microshift-config-rhde-con.adoc index 5ebc647a6023..824b6641c8ae 100644 --- a/modules/microshift-config-rhde-con.adoc +++ b/modules/microshift-config-rhde-con.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * microshift_configuring/microshift-config-rhde-con.adoc +// * microshift_configuring/microshift-default-config-yaml.adoc :_mod-docs-content-type: CONCEPT [id="microshift-config-rhde-con_{context}"] diff --git a/modules/microshift-config-snippets.adoc b/modules/microshift-config-snippets.adoc deleted file mode 100644 index f5dcf7880ebc..000000000000 --- a/modules/microshift-config-snippets.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// Module included in the following assemblies: -// -// * microshift_configuring/microshift-using-config-yaml.adoc - -:_mod-docs-content-type: CONCEPT -[id="microshift-config-snippets_{context}"] -= Using configuration snippets - -If you want to configure one or two settings, such as adding subject alternative names (SANs), you can use the `/etc/microshift/config.d/` configuration directory to drop in configuration snippet YAML files. You must restart {microshift-short} for new configurations to apply. - -To return to previous values, you can delete a configuration snippet and restart {microshift-short}. - -[id="microshift-how-config-snippets-work_{context}"] -== How configuration snippets work - -At runtime, the YAML files inside `/etc/microshift/config.d` are merged into the existing {microshift-short} configuration, whether that configuration is a result of default values or a user-created `config.yaml` file. You do not need to create a `config.yaml` file to use a configuration snippet. - -Files in the snippet directory are sorted in lexicographical order and run sequentially. You can use numerical prefixes for snippets so that each is read in the order you want. The last-read file takes precedence when there is more than one YAML for the same parameter. - -[IMPORTANT] -==== -Configuration snippets take precedence over both default values and a customized `config.yaml` configuration file. -==== - -[id="microshift-example-list-config-snippets_{context}"] -== Example list configuration snippets - -Lists, or arrays, are not merged, they are overwritten. For example, you can replace a SAN or list of SANs by creating an additional snippet for the same field that is read after the first: - -.{microshift-short} configuration directory contents -* `/etc/microshift/config.yaml.default` or `/etc/microshift/config.yaml` - -.Example {microshift-short} configuration snippet directory contents -* `/etc/microshift/config.d/10-san.yaml` -* `/etc/microshift/config.d/20-san.yaml` -+ -.Example `10-san.yaml` snippet -[source,yaml] ----- -apiServer: - subjectAltNames: - - host1 - - host2 ----- -+ -.Example `20-san.yaml` snippet -[source,yaml] ----- -apiServer: - subjectAltNames: - - hostZ ----- -+ -.Example configuration result -[source,yaml] ----- -apiServer: - subjectAltNames: - - hostZ ----- - -If you want to add a value to an existing list, you can add it to an existing snippet. For example, to add `hostZ` to an existing list of SANs, edit the snippet you have instead of creating a new one: - -.Example `10-san.yaml` snippet -[source,yaml] ----- -apiServer: - subjectAltNames: - - host1 - - host2 - - hostZ ----- - -.Example configuration result -[source,yaml] ----- -apiServer: - subjectAltNames: - - host1 - - host2 - - hostZ ----- - -[id="microshift-example-object-config-snippets_{context}"] -== Example object configuration snippets - -Objects are merged together. - -.Example `10-advertiseAddress.yaml` snippet -[source,yaml] ----- -apiServer: - advertiseAddress: "microshift-example" ----- - -.Example `20-audit-log.yaml` snippet -[source,yaml] ----- -apiServer: - auditLog: - maxFileAge: 12 ----- - -.Example configuration result -[source,yaml] ----- -apiServer: - advertiseAddress: "microshift-example" - auditLog: - maxFileAge: 12 ----- - -[id="microshift-example-mixed-config-snippets_{context}"] -== Example mixed configuration snippets - -In this example, the values of both `advertiseAddress` and `auditLog.maxFileAge` fields are merged into the configuration, but only the `c.com` and `d.com` `subjectAltNames` values are retained because the numbering in the filename indicates that they are higher priority. - -.Example `10-advertiseAddress.yaml` snippet -[source,yaml] ----- -apiServer: - advertiseAddress: "microshift-example" ----- - -.Example `20-audit-log.yaml` snippet -[source,yaml] ----- -apiServer: - auditLog: - maxFileAge: 12 ----- - -.Example `30-SAN.yaml` snippet -[source,yaml] ----- -apiServer: - subjectAltNames: - - a.com - - b.com ----- - -.Example `40-SAN.yaml` snippet -[source,yaml] ----- -apiServer: - subjectAltNames: - - c.com - - d.com ----- - -.Example configuration result -[source,yaml] ----- -apiServer: - advertiseAddress: "microshift-example" - auditLog: - maxFileAge: 12 - subjectAltNames: - - c.com - - d.com ----- - diff --git a/modules/microshift-config-yaml-custom.adoc b/modules/microshift-config-yaml-custom.adoc index 3645e1caeeef..ab19c8468406 100644 --- a/modules/microshift-config-yaml-custom.adoc +++ b/modules/microshift-config-yaml-custom.adoc @@ -6,7 +6,9 @@ [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}. +To create custom configurations, make a copy of the `config.yaml.default` file that is given 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 override the defaults before starting or restarting {microshift-short}. + +If you have just a few changes to make to the default settings, consider using configuration drop-in snippets as an alternative method. [IMPORTANT] ==== diff --git a/modules/microshift-config-yaml.adoc b/modules/microshift-config-yaml.adoc index 46dde84726ec..ea7be9f9989c 100644 --- a/modules/microshift-config-yaml.adoc +++ b/modules/microshift-config-yaml.adoc @@ -1,13 +1,13 @@ // Module included in the following assemblies: // -// * microshift_configuring/microshift-using-config-yaml.adoc +// * microshift_configuring/microshift-default-config-yaml.adoc :_mod-docs-content-type: CONCEPT [id="microshift-config-yaml_{context}"] -= The {microshift-short} YAML configuration file += The {microshift-short} configuration file At startup, {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. -You must use the {microshift-short} configuration file must be used in combination with host and, sometimes, application and service settings. Ensure that you configure each function in tandem, as needed, when you adjust settings for your {microshift-short} cluster. +You must use the {microshift-short} configuration file in combination with host and, sometimes, application and service settings. Ensure that you configure each function in tandem when you adjust settings for your {microshift-short} cluster. For your convenience, a `config.yaml.default` file ready for your inputs is automatically installed. diff --git a/modules/microshift-default-settings.adoc b/modules/microshift-default-settings.adoc index 53f289eef5e9..7073d158a4c7 100644 --- a/modules/microshift-default-settings.adoc +++ b/modules/microshift-default-settings.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * microshift_configuring/microshift-using-config-yaml.adoc +// * microshift_configuring/microshift-default-config-yaml.adoc :_mod-docs-content-type: CONCEPT [id="microshift-yaml-default_{context}"] diff --git a/modules/microshift-example-config-snippets-list.adoc b/modules/microshift-example-config-snippets-list.adoc new file mode 100644 index 000000000000..708bfe6ea1d9 --- /dev/null +++ b/modules/microshift-example-config-snippets-list.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-config-snippets.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-ex-config-snippets-lists_{context}"] += Examples of configuration snippet lists or arrays + +Lists, or arrays, are not merged, they are overwritten. For example, you can replace a SAN or list of SANs by creating an additional snippet for the same field that is read after the first: + +.{microshift-short} configuration directory contents +* `/etc/microshift/config.yaml.default` or `/etc/microshift/config.yaml` + +.Example {microshift-short} configuration snippet directory contents +* `/etc/microshift/config.d/10-san.yaml` +* `/etc/microshift/config.d/20-san.yaml` ++ +.Example `10-san.yaml` snippet +[source,yaml] +---- +apiServer: + subjectAltNames: + - host1 + - host2 +---- ++ +.Example `20-san.yaml` snippet +[source,yaml] +---- +apiServer: + subjectAltNames: + - hostZ +---- ++ +.Example configuration result +[source,yaml] +---- +apiServer: + subjectAltNames: + - hostZ +---- + +If you want to add a value to an existing list, you can add it to an existing snippet. For example, to add `hostZ` to an existing list of SANs, edit the snippet you have instead of creating a new one: + +.Example `10-san.yaml` snippet +[source,yaml] +---- +apiServer: + subjectAltNames: + - host1 + - host2 + - hostZ +---- + +.Example configuration result +[source,yaml] +---- +apiServer: + subjectAltNames: + - host1 + - host2 + - hostZ +---- diff --git a/modules/microshift-example-config-snippets-objects.adoc b/modules/microshift-example-config-snippets-objects.adoc new file mode 100644 index 000000000000..9963761ac5af --- /dev/null +++ b/modules/microshift-example-config-snippets-objects.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-config-snippets.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-example-config-snippets-objects_{context}"] += Example configuration snippets that are objects + +Objects are merged together when you use a configuration snippet. + +.Example `10-advertiseAddress.yaml` snippet +[source,yaml] +---- +apiServer: + advertiseAddress: "microshift-example" +---- + +.Example `20-audit-log.yaml` snippet +[source,yaml] +---- +apiServer: + auditLog: + maxFileAge: 12 +---- + +.Example configuration result +[source,yaml] +---- +apiServer: + advertiseAddress: "microshift-example" + auditLog: + maxFileAge: 12 +---- diff --git a/modules/microshift-example-mixed-config-snippets.adoc b/modules/microshift-example-mixed-config-snippets.adoc new file mode 100644 index 000000000000..cfdbcb0ad0b3 --- /dev/null +++ b/modules/microshift-example-mixed-config-snippets.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-config-snippets.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-example-mixed-config-snippets_{context}"] += Examples of mixed configuration snippets + +In this example, the values of both `advertiseAddress` and `auditLog.maxFileAge` fields merge into the configuration, but only the `c.com` and `d.com` `subjectAltNames` values are retained. This happens because the numbering in the filename indicates that the `c.com` and `d.com` values are higher priority. + +.Example `10-advertiseAddress.yaml` snippet +[source,yaml] +---- +apiServer: + advertiseAddress: "microshift-example" +---- + +.Example `20-audit-log.yaml` snippet +[source,yaml] +---- +apiServer: + auditLog: + maxFileAge: 12 +---- + +.Example `30-SAN.yaml` snippet +[source,yaml] +---- +apiServer: + subjectAltNames: + - a.com + - b.com +---- + +.Example `40-SAN.yaml` snippet +[source,yaml] +---- +apiServer: + subjectAltNames: + - c.com + - d.com +---- + +.Example configuration result +[source,yaml] +---- +apiServer: + advertiseAddress: "microshift-example" + auditLog: + maxFileAge: 12 + subjectAltNames: + - c.com + - d.com +---- diff --git a/modules/microshift-how-config-snippets-work.adoc b/modules/microshift-how-config-snippets-work.adoc new file mode 100644 index 000000000000..02a52b6f241f --- /dev/null +++ b/modules/microshift-how-config-snippets-work.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-config-snippets.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-how-config-snippets-work_{context}"] += How configuration snippets work + +If you want to configure one or two settings, such as adding subject alternative names (SANs), you can use the `/etc/microshift/config.d/` configuration directory to drop in configuration snippet YAML files. You must restart {microshift-short} for new configurations to apply. + +To return to previous values, you can delete a configuration snippet and restart {microshift-short}. + +At runtime, the YAML files inside `/etc/microshift/config.d` are merged into the existing {microshift-short} configuration, whether that configuration is a result of default values or a user-created `config.yaml` file. You do not need to create a `config.yaml` file to use a configuration snippet. + +Files in the snippet directory are sorted in lexicographical order and run sequentially. You can use numerical prefixes for snippets so that each is read in the order you want. The last-read file takes precedence when there is more than one YAML for the same parameter. + +[IMPORTANT] +==== +Configuration snippets take precedence over both default values and a customized `config.yaml` configuration file. +==== diff --git a/modules/microshift-nw-advertise-address.adoc b/modules/microshift-nw-advertise-address.adoc index 4c1fe893618a..f0e175a5b85d 100644 --- a/modules/microshift-nw-advertise-address.adoc +++ b/modules/microshift-nw-advertise-address.adoc @@ -13,4 +13,4 @@ The `apiserver.advertiseAddress` flag specifies the IP address on which to adver If you customize the `advertiseAddress` IP address, make sure it is reachable by the cluster when {microshift-short} starts by adding the IP address to a host interface. ==== -If unset, the default value is set to the next immediate subnet after the service network. For example, when the service network is `10.43.0.0/16`, the `advertiseAddress` is set to `10.44.0.0/32`. \ No newline at end of file +If unset, the default value is set to the next immediate subnet after the service network. For example, when the service network is `10.43.0.0/16`, the `advertiseAddress` is set to `10.44.0.0/32`. diff --git a/snippets/microshift-greenboot-status-snip.adoc b/snippets/microshift-greenboot-status-snip.adoc index 41207336495f..fe47d1015cc4 100644 --- a/snippets/microshift-greenboot-status-snip.adoc +++ b/snippets/microshift-greenboot-status-snip.adoc @@ -1,6 +1,6 @@ // Text snippet included in the following assemblies: // -// * microshift_configuring/microshift-using-config-yaml.adoc +// * microshift_configuring/microshift-default-config-yaml.adoc // // Text snippet included in the following modules: //