Questo contenuto non è disponibile nella lingua selezionata.
Chapter 2. Customizing MicroShift by using the configuration file
Use the MicroShift YAML file to customize your preferences, settings, and parameters.
2.1. Using custom settings Copia collegamentoCollegamento copiato negli appunti!
To create custom configurations, make a copy of the config.yaml.default file in the /etc/microshift/ directory, renaming it config.yaml. Keep this file in the /etc/microshift/ directory, and then change supported settings that override the defaults before starting or restarting MicroShift.
If you have just a few changes to make to the default settings, consider using configuration drop-in snippets as an alternative method.
Restart MicroShift after changing any configuration settings to have them take effect. The config.yaml file is read only when MicroShift starts.
2.1.1. Separate restarts Copia collegamentoCollegamento copiato negli appunti!
Applications and other optional services used with your MicroShift node might also need to be restarted separately to apply configuration changes throughout the node. 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.
2.1.2. Parameters and values for the MicroShift config.yaml file Copia collegamentoCollegamento copiato negli appunti!
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 node. The default value is calculated based on the address of the service network. |
|
|
|
How long log files are stored 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. You can configure this value. |
|
|
|
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 you do not list names, 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. |
|
|
| Defines the transport later protocol (TLS) used and the cipher suites allowed. Provides security for the exposed MicroShift API server and internal control plane endpoints. |
|
|
|
Lists the allowed cipher suites that the API server accepts and serves. Defaults to the cipher suites allowed with the TLS specification set in the |
|
|
|
Specifies the minimum version of TLS to serve from the API server. The default value is |
|
|
|
Log verbosity. The default value is |
|
|
| Base domain of the node. All managed DNS records are subdomains of this base. |
|
|
|
Default set to |
|
|
|
Filepath by default set to |
|
|
|
By default, |
|
|
| Lists the device definitions to be exposed by the plugin. Each Device entry contains a 'name' and a list of groups. |
|
|
| Lists device groups. Devices within a group comprise a pool of devices under a common name. When you request a device from that pool, you can receive a device from different defined paths. |
|
|
|
Specifies how many times this group of devices can be mounted concurrently. If unspecified, Count defaults to 1. Setting a high count, for example, |
|
|
|
Lists the host device file paths. Paths can be glob patterns. For example, |
|
|
|
Specifies up to how many times this device can be used in the group concurrently when other devices in the group yield more matches. For example, if one path in the group matches 5 devices and another matches 1 device, but has a limit of 10, then the group provides 5 pairs of devices. When unspecified, the limit defaults to |
|
|
|
The file path at which the host device should be mounted within the container. When unspecified, mountPath defaults to |
|
|
|
The file path of a device on the host. For example, |
|
|
|
The file-system permissions given to the mounted device. Applies only to mounts of type
When unspecified, the value defaults to |
|
|
|
Specifies whether the path should be mounted read-only. Applies only to mounts of type |
|
|
|
Describes what type of file-system node this |
|
|
|
Lists the USB specifications that this device group consists of. The vendor and product IDs must always match. The serial ID must match if provided, or skipped if the ID is empty. The |
|
|
|
The USB Product ID of the device to match on. For example, |
|
|
| The serial number of the device to match on. A USB device must match exactly on all the given attributes to pass. |
|
|
|
The USB Vendor ID of the device to match on. For example, |
|
|
|
A unique string representing the kind of device this specification describes. For example, |
|
|
|
Specifies the domain prefix with which devices are advertised and present in the node. For example, |
|
|
| Specifies the default GDP status. |
|
|
|
A reference to a secret that contains the default certificate that is served by the ingress controller. When routes do not specify their own certificate, The secret must contain the following keys and data:
If you do not set one of these values, a wildcard certificate is automatically generated and used. The certificate is valid for the ingress controller Any certificate in use is automatically integrated in the MicroShift OAuth server. |
|
|
|
Authenticates client access to the node and services. Mutual TLS authentication is enabled when using these settings. If you do not set values for the |
|
|
| Optional subfield which specifies a list of regular expressions that are matched against the distinguished name on a valid client certificate to filter requests. Use this parameter to cause the ingress controller to reject certificates based on the distinguished name. The Perl Compatible Regular Expressions (PCRE) syntax is required. If you configure this field, it must contain a valid expression or the MicroShift service fails. At least one pattern must match a client certificate’s distinguished name; otherwise, the ingress controller rejects the certificate and denies the connection. |
|
|
|
Required subfield that specifies a config map in the |
|
|
| Required subfield that creates a secure route using reencrypt TLS termination with a custom certificate. You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host. The ingress controller only checks client certificates for edge-terminated and reencrypt TLS routes. Certificates for plain text HTTP or passthrough TLS routes are not checked with this setting. |
|
|
|
Determines the default HTTP version to be used for ingress. The default value is |
|
|
|
Specifies when and how the ingress controller sets the
|
|
|
| Defines a policy for HTTP traffic compression. There is no HTTP compression by default. |
|
|
|
A list of MIME types to compress. When the list is empty, the ingress controller does not apply any compression. To define a list, use the format of the Content-Type definition in RFC 1341 that specifies the type and subtype of data in the body of a message and the native encoding of the data. For example,
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. |
|
|
|
The default value is |
|
|
|
The default port shown. Configurable. Valid value is a single, unique port in the |
|
|
|
The default port shown. Configurable. Valid value is a single, unique port in the |
|
|
| Defines a policy for handling new route claims, such as allowing or denying claims across namespaces. By default, allows routes to claim different paths of the same hostname across namespaces. |
|
|
|
Describes how hostname claims across namespaces should be handled. The default value is
|
|
|
| Describes how routes with wildcard policies are handled by the ingress controller.
|
|
|
|
Router status. The default is |
|
|
|
Specifies settings for ingress controller TLS connections, including the minimum TLS version and cipher suites. If you do not set a profile, the default value is based on the
The ingress controller advertises default TLS curves. When the node does not run in FIPS mode, the default curves are |
|
|
|
Specifies the profile type for the TLS security profile. The default value is
When using the |
|
|
| Specifies the TLS version for ingress controllers.
The minimum TLS version 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
|
|
|
|
The 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. The 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. The default range is |
|
| String |
Deploys the Open Virtual Networking - Kubernetes (OVN-K) network plugin as the default container network interface (CNI) when empty or set to |
|
|
|
Controls the deployment of the Multus Container Network Interface (CNI). The default status 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. The 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. The default is an empty value or null. |
|
|
| The default value is empty. An empty value or null field defaults to LVMS deployment. |
|
|
|
The default value is null or an empty array. A null or empty array defaults to deploying |
|
|
The endpoint where telemetry data is sent. No user or private data is included in the metrics reported. The default value is | |
|
|
|
Telemetry status, which can be |
2.1.3. Configure the advertise address network flag Copia collegamentoCollegamento copiato negli appunti!
The apiserver.advertiseAddress flag specifies the IP address on which to advertise the API server to members of the node. This address must be reachable by the node. 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 node 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.
2.1.4. Extending the port range for NodePort services Copia collegamentoCollegamento copiato negli appunti!
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 2.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
2.1.5. Configure custom hostnames Copia collegamentoCollegamento copiato negli appunti!
You can use the hosts file to resolve custom hostnames for pod workloads. This enables applications to resolve fixed hostnames, such as the local machine or external services, by applying /etc/hosts functionality to DNS queries within the node.
The functionality is applied by adding specific configuration to the MicroShift configuration YAML file, and completing a service restart.
Prerequisites
-
You installed the OpenShift CLI (
oc). - You have root access to the node.
Procedure
-
Edit the MicroShift configuration in the
/etc/microshift/config.yamlfile. Add the following
hostsconfiguration at the end of the file:dns: hosts: status: <Enabled|Disabled> file: <filepath>- Save your configuration YAML file.
Restart the MicroShift service to activate the configuration changes:
$ sudo systemctl restart microshiftAfter this initial restart, if
dns.hosts.statusis set toEnabled, MicroShift automatically monitors thedns.hosts.filefile for updates. You do not have to restart the MicroShift service until the MicroShift configuration YAML file is changed again.NoteAfter you save the
/etc/hostsfile, it takes up to 90 seconds for the change to be active in the pods. During this period, the pods might not properly resolve hostnames.
2.1.6. Understanding custom DNS configuration Copia collegamentoCollegamento copiato negli appunti!
By default, MicroShift renders an internal CoreDNS Corefile for the node. You can replace that built-in configuration by setting the dns.configFile parameter in the MicroShift configuration file to the absolute path of a custom Corefile on the host filesystem.
Use a custom Corefile when the default DNS configuration does not meet advanced networking requirements. Typical use cases include split-horizon DNS, custom forwarding rules, and conditional zone delegation.
You are responsible for the correctness of a custom CoreDNS configuration. An invalid Corefile can break DNS resolution or cause intermittent errors. Red Hat support for issues that involve a custom Corefile is limited to commercially reasonable efforts. Support might require you to reproduce the issue without the custom configuration.
If you do not set dns.configFile, or you leave the value empty, MicroShift uses the built-in Corefile.
The dns.configFile and dns.hosts parameters are mutually exclusive. If you set dns.configFile and you also set dns.hosts.status to Enabled, MicroShift fails to start.
When you set dns.configFile, the custom Corefile must meet the following constraints. If any constraint fails, MicroShift fails to start:
-
The path must be absolute. For example,
/etc/microshift/dns/Corefile. - The file must exist.
- The file must be a regular file.
- The file must be readable.
- The file must not be empty.
- The file must not exceed 1 MiB.
2.1.7. Configure MicroShift with a custom CoreDNS Corefile Copia collegamentoCollegamento copiato negli appunti!
You can replace the built-in CoreDNS configuration by placing a custom Corefile on the host and pointing the dns.configFile parameter to that file. MicroShift copies the file contents into the dns-default config map in the openshift-dns namespace.
Prerequisites
-
You installed the OpenShift CLI (
oc). - You have root access to the node.
-
You created a MicroShift
config.yamlfile in the/etc/microshift/directory. -
The
dns.hosts.statusparameter is not set toEnabled.
Procedure
Create the directory for the custom Corefile by running the following command:
$ sudo mkdir -p /etc/microshift/dnsCreate a custom Corefile. Use the following example as a starting point, then add the forwarding rules or zone stanzas that your environment requires:
Example starter Corefile
.:5353 { bufsize 1232 errors log . { class error } health { lameduck 20s } ready kubernetes cluster.local in-addr.arpa ip6.arpa { pods insecure fallthrough in-addr.arpa ip6.arpa } prometheus 127.0.0.1:9153 forward . /etc/resolv.conf { policy sequential } cache 900 { denial 9984 30 } reload } hostname.bind:5353 { chaos }Save the file as
/etc/microshift/dns/Corefile.ImportantKeep the
reloadplugin in the custom Corefile so that CoreDNS applies config map updates. An invalid Corefile can break DNS resolution or cause MicroShift to fail to start.Optional: To forward queries to a specific upstream resolver, replace the
forwardstanza in the Corefile with values for your environment:Example custom forwarding stanza
forward . 192.0.2.53 { policy sequential }Edit the
/etc/microshift/config.yamlfile and set thedns.configFileparameter to the absolute path of the custom Corefile:Example custom Corefile configuration
apiServer: # ... dns: configFile: /etc/microshift/dns/Corefile # ...where:
dns.configFile-
Specifies the absolute path to the custom Corefile on the host. The path must exist, be readable, and not exceed 1 MiB. This parameter is mutually exclusive with
dns.hosts.status: Enabled.
NoteYou can set the same parameter in a configuration snippet in the
/etc/microshift/config.d/directory instead of editingconfig.yaml.- Save the configuration file.
Restart the MicroShift service by running the following command:
$ sudo systemctl restart microshiftAfter this initial restart, MicroShift monitors the custom Corefile for content changes. You do not restart the MicroShift service to apply edits to that file. If you change the
dns.configFilepath in the configuration YAML file, restart the MicroShift service again.
Verification
Confirm that the
dns-defaultconfig map contains the custom Corefile by running the following command:$ oc get configmap dns-default -n openshift-dns -o jsonpath='{.data.Corefile}{"\n"}'The output matches the contents of
/etc/microshift/dns/Corefile.Confirm that the config map annotation points to your custom Corefile by running the following command:
$ oc get configmap dns-default -n openshift-dns -o jsonpath='{.metadata.annotations.microshift\.io/dns-config-file}{"\n"}'Example output
/etc/microshift/dns/CorefileConfirm that the DNS pods are running by running the following command:
$ oc get pods -n openshift-dnsExample output
NAME READY STATUS RESTARTS AGE dns-default-xxxxx 2/2 Running 0 1m node-resolver-xxxxx 1/1 Running 0 1m
2.1.8. Updating a custom Corefile at runtime Copia collegamentoCollegamento copiato negli appunti!
After you set the dns.configFile parameter and restart MicroShift, MicroShift watches the custom Corefile on the host.
When you save changes to that file, MicroShift updates the Corefile key in the dns-default config map in the openshift-dns namespace. You do not need to restart the MicroShift service to apply those content changes.
CoreDNS applies the updated config map only if the custom Corefile includes the reload plugin. Keep that plugin in the file so that DNS changes take effect without restarting MicroShift or the DNS pods.
The file watcher applies only to the Corefile path that was set when MicroShift started. Restart the MicroShift service when you make any of the following changes:
-
You change the
dns.configFilevalue in theconfig.yamlfile or in a configuration snippet. -
You remove the
dns.configFilesetting from theconfig.yamlfile or from a configuration snippet and delete the custom Corefile. MicroShift then uses the built-in Corefile after the restart. -
You enable or disable
dns.hostsin the MicroShift configuration. Thedns.configFileanddns.hosts.status: Enabledsettings remain mutually exclusive.
Deleting the custom Corefile without removing dns.configFile does not restore the built-in configuration. While MicroShift is running, the file watcher keeps the last contents of the dns-default config map. On the next start, MicroShift fails if dns.configFile points to a file that does not exist. Remove the dns.configFile setting before you delete the file, and then restart the MicroShift service.
The MicroShift configuration YAML file is read only when the service starts. Runtime watching does not apply to config.yaml or to configuration snippets. Only the contents of the already configured Corefile are synchronized without a restart.
An invalid edit to the Corefile can break DNS resolution on a running node. Verify the dns-default config map and the DNS pods after you change the file.