Merge pull request #54335 from dhellmann/microshift-config-example-OSDOCS-4763

OSDOCS-4763: fix microshift configuration example

Author: mburke5678

microshift_configuring/microshift-using-config-tools.adoc

@@ -5,10 +5,8 @@ include::_attributes/attributes-microshift.adoc[]
 :context: microshift-configuring
 toc::[]
 
-{product-title} uses a YAML configuration file to execute commands.
-
-//include::modules/microshift-config-cli-manifests.adoc[leveloffset=+1]
+A YAML file customizes {product-title} instances with your preferences, settings, and parameters.
 
 include::modules/microshift-config-yaml.adoc[leveloffset=+1]
 include::modules/microshift-config-auto-apply-manifests.adoc[leveloffset=+1]
-include::modules/microshift-config-nodeport-limits.adoc[leveloffset=+1]
+include::modules/microshift-config-nodeport-limits.adoc[leveloffset=+1]

modules/microshift-config-nodeport-limits.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: CONCEPT
 [id="microshift-nodeport-range-limits_{context}"]
-= Extending the NodePort service range
+= Extending the port range for NodePort services
 
 The `serviceNodePortRange` setting allows the extension of the port range available to NodePort services. This option is useful when specific standard ports under the `30000-32767` need to be exposed. For example, your device needs to expose the `1883/tcp` MQ Telemetry Transport (MQTT) port on the network because some client devices cannot use a different port.
 

modules/microshift-config-yaml.adoc

@@ -6,79 +6,41 @@
 [id="microshift-config-yaml_{context}"]
 = Using a YAML configuration file
 
-Configure your {product-title} using a YAML file. The values specified in your configuration file are used when you execute a command.
-// Q: can these values be overriden with CLI flags?
+{product-title} searches for a configuration file in the user-specific directory, `~/.microshift/config.yaml`, then the system-wide `/etc/microshift/config.yaml` directory. You must create the configuration file and specify any settings that should override the defaults before starting {product-title}.
 
 [id="microshift-yaml-default_{context}"]
 == Default settings
-If you do not create a `config.yaml` file, the default values are used.
-// Q: what creates the default yaml?
-// Q: can default file be modified? (instead of making a new one)
+If you do not create a `config.yaml` file, the default values are used. The following example configuration contains the default settings. You must change any settings that should override the defaults before starting {product-title}.
 
 .Default YAML file example
 [source,yaml]
 ----
-cluster:
-  clusterCIDR: 10.42.0.0/16
-  serviceCIDR: 10.43.0.0/16
-  serviceNodePortRange: 30000-32767
-  dns: 10.43.0.10
-  domain: cluster.local
-  url: https://127.0.0.1:6443
-nodeIP: ""
-nodeName: ""
-logVLevel: 0
+dns:
+  baseDomain: microshift.example.com <1>
+network:
+  clusterNetwork:
+    - cidr: 10.42.0.0/16 <2>
+  serviceNetwork:
+    - 10.43.0.0/16 <3>
+  serviceNodePortRange: 30000-32767 <4>
+node:
+  hostnameOverride: "" <5>
+  nodeIP: "" <6>
+apiServer:
+  subjectAltNames: [] <7>
+debugging:
+  logLevel: "Normal" <8>
 ----
-
-[IMPORTANT]
+<1> Base domain of the cluster. All managed DNS records will be subdomains of this base.
+<2> A block of IP addresses from which Pod IP addresses are allocated.
+<3> A block of virtual IP addresses for Kubernetes services.
+<4> The port range allowed for Kubernetes services of type NodePort.
+<5> The name of the node. The default value is the hostname.
+<6> The IP address of the node. The default value is the IP address of the default route.
+<7> Subject Alternative Names for API server certificates.
+<8> Log verbosity. Valid values for this field are `Normal`, `Debug`, `Trace`, or `TraceAll`.
+
+[NOTE]
 ====
-The configuration file must be located at the user-specific directory, `~/.microshift/config.yaml`, and the system-wide `/etc/microshift/config.yaml` directory. An existing user-specific `config.yaml` takes precedence.
+{product-title} only reads the configuration file on startup. Restart {product-title} after changing any configuration settings to have them take effect.
 ====
-//Q: can this be done with a command, or is this an instance where user goes into the directory and creates a text file?
-
-[id="microshift-yaml-format-example_{context}"]
-== Formatting a customized YAML file
-
-.Procedure
-//Q: need explicit steps
-. Create a YAML file with the following formatting:
-+
-[source,yaml]
-----
-cluster: ""
-  clusterCIDR: ""
-  serviceCIDR: ""
-  serviceNodePortRange: ""
-  dns: ""
-  domain: ""
-  url: ""
-nodeIP: ""
-nodeName: ""
-logVLevel: ""
-----
-
-. Enter valid values.
-//Q: most docsets contain a table of valid entry types, noting whether required or optional
-//Q: does the user need to enter every value? will any default?
-//Q: how does the user check that this procedure has been done properly?
-
-//Q: Can we give a sample use-case set of values in an example YAML? see below
-//. Next, enter the values specific to your project.
-
-//For example, this configuration file specifies that when you run the <command>, the value in the <field> is used. This configuration file <does this> when you run the <command>.
-//Q: what values can we use as an example?
-//+
-//.Configured YAML file example
-//[source,yaml]
-//----
-//cluster: ""
-//  clusterCIDR: ""
-//  serviceCIDR: ""
-// serviceNodePortRange: ""
-// dns: ""
-//  domain: ""
-//  url: ""
-//nodeIP: ""
-//nodeName: ""
-//logVLevel: ""
-//----