Skip to content

Commit c3cfe38

Browse files
skrthomasskrthomas
authored
Merge pull request #52615 from ShaunaDiaz/OSDOCS-4505
OSDOCS-4505: Adding Configuration book to MicroShift docs
2 parents d114790 + 588148d commit c3cfe38

File tree

9 files changed

+297
-0
lines changed

9 files changed

+297
-0
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,13 @@ Topics:
9999
# Distros: openshift-enterprise,openshift-origin
100100
- Name: Usage of oc and kubectl commands
101101
File: usage-oc-kubectl
102+
---
103+
Name: Configuring
104+
Dir: microshift_configuring
105+
Distros: microshift
106+
Topics:
107+
- Name: Configuring MicroShift
108+
File: microshift-using-config-tools
102109
# ---
103110
# Name: Storage
104111
# Dir: storage

‎microshift_configuring/attributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../_attributes

‎microshift_configuring/images

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images

‎microshift_configuring/microshift-using-config-tools.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
:_content-type: ASSEMBLY
2+
[id="microshift-using-config-tools"]
3+
= Configuring {product-title}
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-configuring
6+
toc::[]
7+
8+
{product-title} uses a YAML configuration file to execute commands.
9+
10+
//include::modules/microshift-config-cli-manifests.adoc[leveloffset=+1]
11+
12+
include::modules/microshift-config-yaml.adoc[leveloffset=+1]
13+
14+
include::modules/microshift-auto-apply-manifests.adoc[leveloffset=+1]

‎microshift_configuring/modules

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules

‎microshift_configuring/snippets

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../snippets/

‎modules/microshift-auto-apply-manifests.adoc

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/using-config-tools.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-auto-apply-manifests_{context}"]
7+
= Automatically applying manifests with `kustomize`
8+
9+
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.
10+
11+
[IMPORTANT]
12+
====
13+
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.
14+
====
15+
16+
[cols="2",options="header"]
17+
|===
18+
|Location
19+
|Intent
20+
21+
|`/etc/microshift/manifests`
22+
|Read-write location for configuration management systems or development.
23+
24+
|`/usr/lib/microshift/manifests`
25+
|Read-only location for embedding configuration manifests on OSTree-based systems.
26+
|===
27+
28+
[id="microshift-manifests-example_{context}"]
29+
== Manifest example
30+
This example demonstrates automatic deployment of a BusyBox container using `kustomize` manifests in the `/etc/microshift/manifests` directory.
31+
32+
.Procedure
33+
. Create the BusyBox manifest files by running the following commands:
34+
+
35+
* Define the directory location.
36+
+
37+
[source,terminal]
38+
----
39+
$ MANIFEST_DIR=/etc/microshift/manifests
40+
----
41+
+
42+
* Make the directory by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ sudo mkdir -p ${MANIFEST_DIR}
47+
----
48+
+
49+
* Place the `yaml` file in the directory.
50+
+
51+
[source,terminal]
52+
----
53+
$ sudo tee ${MANIFEST_DIR}/busybox.yaml &>/dev/null <<EOF
54+
55+
apiVersion: v1
56+
kind: Namespace
57+
metadata:
58+
name: busybox
59+
---
60+
apiVersion: apps/v1
61+
kind: Deployment
62+
metadata:
63+
name: busybox-deployment
64+
spec:
65+
selector:
66+
matchLabels:
67+
app: busybox
68+
template:
69+
metadata:
70+
labels:
71+
app: busybox
72+
spec:
73+
containers:
74+
- name: busybox
75+
image: BUSYBOX_IMAGE
76+
command:
77+
- sleep
78+
- "3600"
79+
----
80+
// what are the "---" after name: busybox?
81+
.Procedure
82+
. Create the `kustomize` manifest files by running the following commands:
83+
+
84+
* Run the command to read and write the standard inputs.
85+
[source,terminal]
86+
+
87+
----
88+
$ sudo tee
89+
----
90+
* Apply the `yaml` configuration.
91+
+
92+
[source,terminal]
93+
----
94+
$ {MANIFEST_DIR}/kustomization.yaml &>/dev/null
95+
96+
apiVersion: kustomize.config.k8s.io/v1beta1
97+
kind: Kustomization
98+
namespace: busybox
99+
resources:
100+
- busybox.yaml
101+
images:
102+
- name: BUSYBOX_IMAGE
103+
newName: registry.k8s.io/busybox
104+
----
105+
106+
. Restart {product-title} to apply the manifests and verify that the BusyBox pod is running by running the following commands:
107+
+
108+
* Restart {product-title}.
109+
+
110+
[source,terminal]
111+
----
112+
$ sudo systemctl restart microshift
113+
----
114+
+
115+
* Apply the manifests and start the BusyBox pod.
116+
+
117+
[source,terminal]
118+
----
119+
$ oc get pods -n busybox
120+
----
121+
122+
// what's the verification look like?

‎modules/microshift-config-cli-manifests.adoc

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/using-config-tools.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-config-cli-manifests_{context}"]
7+
= Using CLI tools and creating manifests
8+
9+
Configure your {product-title} using the supported command line arguments and environment variables.
10+
11+
[id="microshift-config-cli-environ-vars_{context}"]
12+
== Supported command-line arguments and environment variables
13+
14+
[cols="4",options="header"]
15+
|===
16+
|Field name
17+
|CLI argument
18+
|Environment variable
19+
|Description
20+
21+
|`clusterCIDR`
22+
|`--cluster-cidr`
23+
|`MICROSHIFT_CLUSTER_CLUSTERCIDR`
24+
|A block of IP addresses from which pod IP addresses are allocated.
25+
26+
|`serviceCIDR`
27+
|`--service-cidr`
28+
|`MICROSHIFT_CLUSTER_SERVICECIDR`
29+
|A block of virtual IP addresses for Kubernetes services.
30+
31+
|`serviceNodePortRange`
32+
|`--service-node-port-range`
33+
|`MICROSHIFT_CLUSTER_SERVICENODEPORTRANGE`
34+
|The port range allowed for Kubernetes services of type NodePort.
35+
36+
|`dns`
37+
|`--cluster-dns`
38+
|`MICROSHIFT_CLUSTER_DNS`
39+
|The Kubernetes service IP address where pods query for name resolution.
40+
41+
|`domain`
42+
|`--cluster-domain`
43+
|`MICROSHIFT_CLUSTER_DOMAIN`
44+
|Base DNS domain used to construct fully qualified pod and service domain names.
45+
46+
|`url`
47+
|`--url`
48+
|`MICROSHIFT_CLUSTER_URL`
49+
|URL of the API server for the cluster.
50+
51+
|`nodeIP`
52+
|`--node-ip`
53+
|`MICROSHIFT_NODEIP`
54+
|The IP address of the node, defaults to IP of the default route.
55+
56+
|`nodeName`
57+
|`--node-name`
58+
|`MICROSHIFT_NODENAME`
59+
|The name of the node, defaults to hostname.
60+
61+
|`logVLevel`
62+
|`--v`
63+
|`MICROSHIFT_LOGVLEVEL`
64+
|Log verbosity (0-5)
65+
|===
66+

‎modules/microshift-config-yaml.adoc

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/using-config-tools.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-config-yaml_{context}"]
7+
= Using a YAML configuration file
8+
9+
Configure your {product-title} using a YAML file. The values specified in your configuration file are used when you execute a command.
10+
// Q: can these values be overriden with CLI flags?
11+
12+
[id="microshift-yaml-default_{context}"]
13+
== Default settings
14+
If you do not create a `config.yaml` file, the default values are used.
15+
// Q: what creates this default yaml?
16+
// Q: can default file be modified? (instead of making a new one)
17+
18+
.Default YAML file example
19+
[source,yaml]
20+
----
21+
cluster:
22+
clusterCIDR: 10.42.0.0/16
23+
serviceCIDR: 10.43.0.0/16
24+
serviceNodePortRange: 30000-32767
25+
dns: 10.43.0.10
26+
domain: cluster.local
27+
url: https://127.0.0.1:6443
28+
nodeIP: ""
29+
nodeName: ""
30+
logVLevel: 0
31+
----
32+
33+
[IMPORTANT]
34+
====
35+
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.
36+
====
37+
//Q: can this be done with a command, or is this an instance where user goes into the directory and creates a text file?
38+
39+
[id="microshift-yaml-format-example_{context}"]
40+
== Formatting a customized YAML file
41+
42+
.Procedure
43+
//Q: need explicit steps
44+
. Create a YAML file with the following formatting:
45+
+
46+
[source,yaml]
47+
----
48+
cluster: ""
49+
clusterCIDR: ""
50+
serviceCIDR: ""
51+
serviceNodePortRange: ""
52+
dns: ""
53+
domain: ""
54+
url: ""
55+
nodeIP: ""
56+
nodeName: ""
57+
logVLevel: ""
58+
----
59+
60+
. Enter valid values.
61+
//Q: most docsets contain a table of valid entry types, noting whether required or optional
62+
//Q: does the user need to enter every value? will any default?
63+
//Q: how does the user check that this procedure has been done properly?
64+
65+
//Q: Can we give a sample use-case set of values in an example YAML? see below
66+
//. Next, enter the values specific to your project.
67+
68+
//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>.
69+
//Q: what values can we use as an example?
70+
//+
71+
//.Configured YAML file example
72+
//[source,yaml]
73+
//----
74+
//cluster: ""
75+
// clusterCIDR: ""
76+
// serviceCIDR: ""
77+
// serviceNodePortRange: ""
78+
// dns: ""
79+
// domain: ""
80+
// url: ""
81+
//nodeIP: ""
82+
//nodeName: ""
83+
//logVLevel: ""
84+
//----

0 commit comments

Comments
 (0)