OSDOCS-4505 Adding Configuration book to MicroShift docs

_topic_maps/_topic_map_ms.yml

@@ -99,6 +99,13 @@ Topics:
   #   Distros: openshift-enterprise,openshift-origin
   - Name: Usage of oc and kubectl commands
     File: usage-oc-kubectl
+---
+Name: Configuring
+Dir: microshift_configuring
+Distros: microshift
+Topics:
+- Name: Configuring MicroShift
+  File: microshift-using-config-tools
 # ---
 # Name: Storage
 # Dir: storage

microshift_configuring/attributes

@@ -0,0 +1 @@
+../_attributes

microshift_configuring/images

@@ -0,0 +1 @@
+../images

microshift_configuring/microshift-using-config-tools.adoc

@@ -0,0 +1,14 @@
+:_content-type: ASSEMBLY
+[id="microshift-using-config-tools"]
+= Configuring {product-title}
+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]
+
+include::modules/microshift-config-yaml.adoc[leveloffset=+1]
+
+include::modules/microshift-auto-apply-manifests.adoc[leveloffset=+1]

microshift_configuring/modules

@@ -0,0 +1 @@
+../modules

microshift_configuring/snippets

@@ -0,0 +1 @@
+../snippets/

modules/microshift-auto-apply-manifests.adoc

@@ -0,0 +1,122 @@
+// Module included in the following assemblies:
+//
+// * microshift/using-config-tools.adoc
+
+:_content-type: CONCEPT
+[id="microshift-auto-apply-manifests_{context}"]
+= Automatically applying manifests with `kustomize`
+
+ Providing multiple directories allows a flexible method of managing {product-title} workloads. When you run the `kustomize` configuration management tool, {product-title} searches the `/etc/microshift/manifests` and `/usr/lib/microshift/` manifest directories for a `kustomization.yaml` file. If it finds one, {product-title} automatically runs the `kubectl apply -k` command to apply the manifests to the cluster.
+
+[IMPORTANT]
+====
+The `kustomize` tool must be either running as a separate step in the boot process, or it must be part of the {product-title} image.
+====
+
+[cols="2",options="header"]
+|===
+|Location
+|Intent
+
+|`/etc/microshift/manifests`
+|Read-write location for configuration management systems or development.
+
+|`/usr/lib/microshift/manifests`
+|Read-only location for embedding configuration manifests on OSTree-based systems.
+|===
+
+[id="microshift-manifests-example_{context}"]
+== Manifest example
+This example demonstrates automatic deployment of a BusyBox container using `kustomize` manifests in the `/etc/microshift/manifests` directory.
+
+.Procedure
+. Create the BusyBox manifest files by running the following commands:
++
+* Define the directory location.
++
+[source,terminal]
+----
+$ MANIFEST_DIR=/etc/microshift/manifests
+----
++
+* Make the directory by running the following command:
++
+[source,terminal]
+----
+$ sudo mkdir -p ${MANIFEST_DIR}
+----
++
+* Place the `yaml` file in the directory.
++
+[source,terminal]
+----
+$ sudo tee ${MANIFEST_DIR}/busybox.yaml &>/dev/null <<EOF
+
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: busybox
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: busybox-deployment
+spec:
+  selector:
+    matchLabels:
+      app: busybox
+  template:
+    metadata:
+      labels:
+        app: busybox
+    spec:
+      containers:
+      - name: busybox
+        image: BUSYBOX_IMAGE
+        command:
+          - sleep
+          - "3600"
+----
+// what are the "---" after name: busybox?
+.Procedure
+. Create the `kustomize` manifest files by running the following commands:
++
+* Run the command to read and write the standard inputs.
+[source,terminal]
++
+----
+$ sudo tee
+----
+* Apply the `yaml` configuration.
++
+[source,terminal]
+----
+$ {MANIFEST_DIR}/kustomization.yaml &>/dev/null
+
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: busybox
+resources:
+  - busybox.yaml
+images:
+  - name: BUSYBOX_IMAGE
+    newName: registry.k8s.io/busybox
+----
+
+. Restart {product-title} to apply the manifests and verify that the BusyBox pod is running by running the following commands:
++
+* Restart {product-title}.
++
+[source,terminal]
+----
+$ sudo systemctl restart microshift
+----
++
+* Apply the manifests and start the BusyBox pod.
++
+[source,terminal]
+----
+$ oc get pods -n busybox
+----
+
+// what's the verification look like?

modules/microshift-config-cli-manifests.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// * microshift/using-config-tools.adoc
+
+:_content-type: CONCEPT
+[id="microshift-config-cli-manifests_{context}"]
+= Using CLI tools and creating manifests
+
+Configure your {product-title} using the supported command line arguments and environment variables.
+
+[id="microshift-config-cli-environ-vars_{context}"]
+== Supported command-line arguments and environment variables
+
+[cols="4",options="header"]
+|===
+|Field name
+|CLI argument
+|Environment variable
+|Description
+
+|`clusterCIDR`
+|`--cluster-cidr`
+|`MICROSHIFT_CLUSTER_CLUSTERCIDR`
+|A block of IP addresses from which pod IP addresses are allocated.
+
+|`serviceCIDR`
+|`--service-cidr`
+|`MICROSHIFT_CLUSTER_SERVICECIDR`
+|A block of virtual IP addresses for Kubernetes services.
+
+|`serviceNodePortRange`
+|`--service-node-port-range`
+|`MICROSHIFT_CLUSTER_SERVICENODEPORTRANGE`
+|The port range allowed for Kubernetes services of type NodePort.
+
+|`dns`
+|`--cluster-dns`
+|`MICROSHIFT_CLUSTER_DNS`
+|The Kubernetes service IP address where pods query for name resolution.
+
+|`domain`
+|`--cluster-domain`
+|`MICROSHIFT_CLUSTER_DOMAIN`
+|Base DNS domain used to construct fully qualified pod and service domain names.
+
+|`url`
+|`--url`
+|`MICROSHIFT_CLUSTER_URL`
+|URL of the API server for the cluster.
+
+|`nodeIP`
+|`--node-ip`
+|`MICROSHIFT_NODEIP`
+|The IP address of the node, defaults to IP of the default route.
+
+|`nodeName`
+|`--node-name`
+|`MICROSHIFT_NODENAME`
+|The name of the node, defaults to hostname.
+
+|`logVLevel`
+|`--v`
+|`MICROSHIFT_LOGVLEVEL`
+|Log verbosity (0-5)
+|===
+

modules/microshift-config-yaml.adoc

@@ -0,0 +1,84 @@
+// Module included in the following assemblies:
+//
+// * microshift/using-config-tools.adoc
+
+:_content-type: CONCEPT
+[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?
+
+[id="microshift-yaml-default_{context}"]
+== Default settings
+If you do not create a `config.yaml` file, the default values are used.
+// Q: what creates this default yaml?
+// Q: can default file be modified? (instead of making a new one)
+
+.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
+----
+
+[IMPORTANT]
+====
+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.
+====
+//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: ""
+//----