diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index b7d4d82620..e2062cc180 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_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 diff --git a/microshift_configuring/attributes b/microshift_configuring/attributes new file mode 120000 index 0000000000..93957f0227 --- /dev/null +++ b/microshift_configuring/attributes @@ -0,0 +1 @@ +../_attributes \ No newline at end of file diff --git a/microshift_configuring/images b/microshift_configuring/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/microshift_configuring/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/microshift_configuring/microshift-using-config-tools.adoc b/microshift_configuring/microshift-using-config-tools.adoc new file mode 100644 index 0000000000..d527312395 --- /dev/null +++ b/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] \ No newline at end of file diff --git a/microshift_configuring/modules b/microshift_configuring/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/microshift_configuring/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/microshift_configuring/snippets b/microshift_configuring/snippets new file mode 120000 index 0000000000..9d58b92e50 --- /dev/null +++ b/microshift_configuring/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/modules/microshift-auto-apply-manifests.adoc b/modules/microshift-auto-apply-manifests.adoc new file mode 100644 index 0000000000..2d4be29ec2 --- /dev/null +++ b/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 </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? \ No newline at end of file diff --git a/modules/microshift-config-cli-manifests.adoc b/modules/microshift-config-cli-manifests.adoc new file mode 100644 index 0000000000..63f1e30522 --- /dev/null +++ b/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) +|=== + diff --git a/modules/microshift-config-yaml.adoc b/modules/microshift-config-yaml.adoc new file mode 100644 index 0000000000..4e7f3e5e48 --- /dev/null +++ b/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 , the value in the is used. This configuration file when you run the . +//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: "" +//----