Red Hat Summit이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Chapter 1. Using the MicroShift configuration file
A YAML file customizes MicroShift instances with your preferences, settings, and parameters.
If you want to make configuration changes or deploy applications through the MicroShift API with tools other than kustomize manifests, you must wait until the greenboot health checks have finished. This ensures that your changes are not lost if greenboot rolls your rpm-ostree system back to an earlier state.
1.1. The MicroShift YAML configuration file
At start up, MicroShift 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.
The MicroShift configuration file must be used in combination with host and, sometimes, application and service settings. Ensure that each item is configured in tandem when you customize your MicroShift cluster.
1.1.1. Default settings
If you do not create a config.yaml file or use a configuration snippet YAML file, default values are used. The following example shows the default configuration settings.
To see the default values, run the following command:
$ microshift show-config
Default values example output in YAML form
apiServer: advertiseAddress: 10.44.0.0/32 1 auditLog: maxFileAge: 0 maxFileSize: 200 maxFiles: 10 profile: Default namedCertificates: - certPath: "" keyPath: "" names: - "" subjectAltNames: [] debugging: logLevel: "Normal" dns: baseDomain: microshift.example.com etcd: memoryLimitMB: 0 ingress: defaultHTTPVersion: 1 forwardedHeaderPolicy: "" httpCompression: mimeTypes: - "" httpEmptyRequestsPolicy: Respond listenAddress: - "" logEmptyRequests: Log ports: http: 80 https: 443 routeAdmissionPolicy: namespaceOwnership: InterNamespaceAllowed status: Managed tuningOptions: clientFinTimeout: "" clientTimeout: "" headerBufferBytes: 0 headerBufferMaxRewriteBytes: 0 healthCheckInterval: "" maxConnections: 0 serverFinTimeout: "" serverTimeout: "" threadCount: 0 tlsInspectDelay: "" tunnelTimeout: "" kubelet: manifests: kustomizePaths: - /usr/lib/microshift/manifests - /usr/lib/microshift/manifests.d/* - /etc/microshift/manifests - /etc/microshift/manifests.d/* network: clusterNetwork: - 10.42.0.0/16 serviceNetwork: - 10.43.0.0/16 serviceNodePortRange: 30000-32767 node: hostnameOverride: "" nodeIP: "" 2 nodeIPv6: "" storage: driver: "" 3 optionalCsiComponents: 4 - ""
1.2. 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.
Restart MicroShift after changing any configuration settings to have them take effect. The config.yaml file is read only when MicroShift starts.
1.2.1. Separate restarts
Applications and other optional services used with your MicroShift cluster might also need to be restarted separately to apply configuration changes throughout the cluster. For example, when making changes to certain networking settings, you must stop and restart service and application pods to apply those changes. See each procedure for the task you are completing for more information.
If you add all of the configurations you need at the same time, you can minimize system restarts.
1.2.2. Parameters and values for the MicroShift config.yaml file
The following table explains MicroShift configuration YAML parameters and valid values for each:
| Field | Type | Description |
|---|---|---|
|
|
| A string that specifies the IP address from which the API server is advertised to members of the cluster. The default value is calculated based on the address of the service network. |
|
|
|
How long log files are kept before automatic deletion. The default value of |
|
|
|
By default, when the |
|
|
| The total number of log files kept. By default, MicroShift retains 10 log files. The oldest is deleted when an excess file is created. This value can be configured. |
|
|
|
Logs only metadata for read and write requests; does not log request bodies except for OAuth access token requests. If you do not specify this field, the |
|
|
| Defines externally generated certificates and domain names by using custom certificate authorities. |
|
|
| The full path to the certificate. |
|
|
| The full path to the certificate key. |
|
|
| 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. |
|
|
Fully qualified domain names (FQDNs), wildcards such as | Subject Alternative Names for API server certificates. SANs indicate all of the domain names and IP addresses that are secured by a certificate. |
|
|
|
Log verbosity. Default is |
|
|
| Base domain of the cluster. All managed DNS records are subdomains of this base. |
|
|
|
By default, |
|
|
|
Determines the default HTTP version to be used for ingress. Default value is |
|
|
|
Specifies when and how the ingress router sets the
|
|
|
|
|
|
|
|
Not all MIME types benefit from compression, but |
|
|
|
The default value is
|
|
| IP address, NIC name, or multiple | Value defaults to the entire network of the host. The valid configurable value is a list that can be either a single IP address or NIC name or multiple IP addresses and NIC names. |
|
|
|
Default value is |
|
|
|
Default port shown. Configurable. Valid value is a single, unique port in the |
|
|
|
Default port shown. Configurable. Valid value is a single, unique port in the |
|
|
|
Describes how hostname claims across namespaces are handled. By default, allows routes to claim different paths of the same hostname across namespaces. Specifying |
|
|
|
Router status. Default is |
|
| Objects | Specifies options for tuning the performance of ingress controller pods. |
|
|
|
Defines how long a connection is held open while waiting for a client response to the server/backend before closing the connection. The default timeout is |
|
|
|
Defines how long a connection is held open while waiting for a client response. The default timeout is |
|
|
An |
Describes how much memory in bytes must be reserved for
|
|
|
|
Describes how much memory in bytes must be reserved from
|
|
|
|
The default
|
|
|
|
Default value is
|
|
|
|
Defines how long a connection is held open while waiting for a server or backend response to the client before closing the connection. The default timeout is |
|
|
|
Defines how long a connection is held open while waiting for a server or backend response. The default timeout is |
|
|
|
Defines the number of threads created per
|
|
|
| Defines how long the router can hold data to find a matching route. Setting this interval with too short a value can cause the router to revert to the default certificate for edge-terminated clients or re-encrypt routes, even when a better-matching certificate could be used.
|
|
|
|
Defines how long a tunnel connection, including websockets, are held open while the tunnel is idle. The default timeout is |
|
| See the MicroShift low-latency instructions | Parameter for passthrough configuration of the kubelet node agent. Used for low-latency configuration. Default value is null. |
|
|
|
The locations on the file system to scan for |
|
| IP address block |
A block of IP addresses from which pod IP addresses are allocated. IPv4 is the default network. Dual-stack entries are supported. The first entry in this field is immutable after MicroShift starts. Default range is |
|
| IP address block |
A block of virtual IP addresses for Kubernetes services. IP address pool for services. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after MicroShift starts. Default range is |
|
|
|
The port range allowed for Kubernetes services of type |
|
|
| The name of the node. The default value is the hostname. If non-empty, this string is used to identify the node instead of the hostname. This value is immutable after MicroShift starts. |
|
| IPv4 address | The IPv4 address of the node. The default value is the IP address of the default route. |
|
| IPv6 address | The IPv6 address for the node for dual-stack configurations. Cannot be configured in single stack for either IPv4 or IPv6. Default is an empty value or null. |
|
|
| Default value is empty. An empty value or null field defaults to LVMS deployment. |
|
|
|
Default value is null or an empty array. A null or empty array defaults to deploying |
1.2.3. 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 for new configurations to apply.
To return to previous values, you can delete a configuration snippet and restart MicroShift.
1.2.3.1. How configuration snippets work
At runtime, the YAML files inside /etc/microshift/config.d are merged into the existing MicroShift 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.
Configuration snippets take precedence over both default values and a customized config.yaml configuration file.
1.2.3.2. 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 configuration directory contents
-
/etc/microshift/config.yaml.defaultor/etc/microshift/config.yaml
Example MicroShift configuration snippet directory contents
-
/etc/microshift/config.d/10-san.yaml /etc/microshift/config.d/20-san.yamlExample
10-san.yamlsnippetapiServer: subjectAltNames: - host1 - host2Example
20-san.yamlsnippetapiServer: subjectAltNames: - hostZExample configuration result
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
apiServer:
subjectAltNames:
- host1
- host2
- hostZ
Example configuration result
apiServer:
subjectAltNames:
- host1
- host2
- hostZ
1.2.3.3. Example object configuration snippets
Objects are merged together.
Example 10-advertiseAddress.yaml snippet
apiServer: advertiseAddress: "microshift-example"
Example 20-audit-log.yaml snippet
apiServer:
auditLog:
maxFileAge: 12
Example configuration result
apiServer:
advertiseAddress: "microshift-example"
auditLog:
maxFileAge: 12
1.2.3.4. 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
apiServer: advertiseAddress: "microshift-example"
Example 20-audit-log.yaml snippet
apiServer:
auditLog:
maxFileAge: 12
Example 30-SAN.yaml snippet
apiServer:
subjectAltNames:
- a.com
- b.com
Example 40-SAN.yaml snippet
apiServer:
subjectAltNames:
- c.com
- d.com
Example configuration result
apiServer:
advertiseAddress: "microshift-example"
auditLog:
maxFileAge: 12
subjectAltNames:
- c.com
- d.com
1.2.4. Configuring the advertise address network flag
The apiserver.advertiseAddress flag specifies the IP address on which to advertise the API server to members of the cluster. This address must be reachable by the cluster. You can set a custom IP address here, but you must also add the IP address to a host interface. Customizing this parameter preempts MicroShift from adding a default IP address to the br-ex network interface.
If you customize the advertiseAddress IP address, make sure it is reachable by the cluster when MicroShift 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.
1.2.5. Extending the port range for NodePort services
The serviceNodePortRange setting extends the port range available to NodePort services. This option is useful when specific standard ports under the 30000-32767 range need to be exposed. For example, if your device needs to expose the 1883/tcp MQ Telemetry Transport (MQTT) port on the network because client devices cannot use a different port.
NodePorts can overlap with system ports, causing a malfunction of the system or MicroShift.
Consider the following when configuring the NodePort service ranges:
-
Do not create any NodePort service without an explicit
nodePortselection. When an explicitnodePortis not specified, the port is assigned randomly by thekube-apiserverand cannot be predicted. -
Do not create any NodePort service for any system service port, MicroShift port, or other services you expose on your device
HostNetwork. Table one specifies ports to avoid when extending the port range:
Table 1.2. Ports to avoid. Port Description 22/tcp
SSH port
80/tcp
OpenShift Router HTTP endpoint
443/tcp
OpenShift Router HTTPS endpoint
1936/tcp
Metrics service for the openshift-router, not exposed today
2379/tcp
etcd port
2380/tcp
etcd port
6443
kubernetes API
8445/tcp
openshift-route-controller-manager
9537/tcp
cri-o metrics
10250/tcp
kubelet
10248/tcp
kubelet healthz port
10259/tcp
kube scheduler
