Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

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
Copiar o link

To create custom configurations, make a copy of the config.yaml.default file that is given 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 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.

Important

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
Copiar o link

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.

Tip

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
Copiar o link

The following table explains MicroShift configuration YAML parameters and valid values for each:

Expand
Table 2.1. MicroShift config.yaml parameters
FieldTypeDescription

advertiseAddress

string

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.

auditLog.maxFileAge

number

How long log files are stored before automatic deletion. The default value of 0 in the maxFileAge parameter means a log file is never deleted based on age. You can configure this value.

auditLog.maxFileSize

number

By default, when the audit.log file reaches the maxFileSize limit, the audit.log file is rotated and MicroShift begins writing to a new audit.log file. You can configure this value.

auditLog.maxFiles

number

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.

auditLog.profile

Default, WriteRequestBodies, AllRequestBodies, or None

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 Default profile is used.

namedCertificates

list

Defines externally generated certificates and domain names by using custom certificate authorities.

namedCertificates.certPath

path

The full path to the certificate.

namedCertificates.keyPath

path

The full path to the certificate key.

namedCertificates.names

list

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.

subjectAltNames

Fully qualified domain names (FQDNs), wildcards such as *.domain.com, or IP addresses.

Subject Alternative Names for API server certificates. SANs indicate all of the domain names and IP addresses that are secured by a certificate.

tls

list

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.

tls.cipherSuites

string

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 tls.minVersion parameter.

tls.minVersion

VersionTLS12 or VersionTLS13

Specifies the minimum version of TLS to serve from the API server. The default value is VersionTLS12.

debugging.logLevel

Normal, Debug, Trace, or TraceAll

Log verbosity. The default value is Normal.

dns.baseDomain

valid domain

Base domain of the cluster. All managed DNS records are subdomains of this base.

etcd.memoryLimitMB

number

By default, etcd uses as much memory as needed to handle the load on the system. However, in memory constrained systems, it might be preferred or necessary to limit the amount of memory etcd can to use at a given time.

ingress.certificateSecret

string

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, certificateSecret is used.

The secret must contain the following keys and data:

  • tls.crt: certificate file contents
  • tls.key: key file contents

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 domain and subdomains fields, and the generated CA for the certificate is automatically integrated with the truststore for the cluster.

Any certificate in use is automatically integrated in the MicroShift OAuth server.

ingress.clientTLS

AllowedSubjectPatterns, spec.clientTLS.ClientCA, spec.clientTLS.clientCertificatePolicy

Authenticates client access to the cluster and services. Mutual TLS authentication is enabled when using these settings. If you do not set values for the spec.clientTLS.clientCertificatePolicy and spec.clientTLS.ClientCA required subfields, client TLS is not enabled.

ingress.clientTLS.AllowedSubjectPatterns

list in PCRE syntax

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.

ingress.clientTLS.ClientCA

string

Required subfield that specifies a config map in the openshift-ingress namespace. The config map must contain a CA certificate bundle.

ingress.clientTLS.ClientCertificatePolicy

Required, Optional

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.

ingress.defaultHTTPVersion

number

Determines the default HTTP version to be used for ingress. The default value is 1, which is the HTTP/1.1 protocol.

ingress.forwardedHeaderPolicy

Append, Replace, IfNone, Never

Specifies when and how the ingress controller sets the Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, and X-Forwarded-Proto-Version HTTP headers. The default value is Append.

  • Append specifies that the ingress controller appends existing headers.
  • Replace specifies that the ingress controller sets the headers and replaces any existing Forwarded or X-Forwarded-* headers.
  • IfNone specifies that the ingress controller sets headers if they are not already set.
  • Never specifies that ingress controller never sets the headers, preserving any existing headers.

ingress.httpCompression

object

Defines a policy for HTTP traffic compression. There is no HTTP compression by default.

ingress.httpCompression.mimeTypes

array or null

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, Content-Type := type \"/\" subtype *[\";\" parameter].

  • The value of Content-Type can be one of the following types: application, audio, image, message, multipart, text, video, or a custom type preceded by \"X-\" and followed by a token. The token must be defined in one of the following ways:
  • The token is a string of at least one character, and does not contain white spaces, control characters, or any of the characters in the tspecials set.
  • The tspecials set contains the characters ()\u003c\u003e@,;:\\\"/[]?.=.
  • The subtype in Content-Type is also a token.
  • The optional parameters following the subtype are defined as token \"=\" (token / quoted-string).
  • The quoted-string, as defined in RFC 822, is surrounded by double quotes and can contain white spaces plus any character except \\, \", and CR. The quoted-string can also contain any single ASCII character if it is escaped by the following characters: \\.",.

Not all MIME types benefit from compression, but HAProxy uses resources to try to compress files when compression is configured. Generally speaking, text formats such as html, ccs, and js benefit from compression. Spending CPU resources to compress file types that are already compressed, such as images, audio, and video, is probably not worth the limited benefit.

ingress.httpEmptyRequestsPolicy

Respond or Ignore

The default value is Respond. Describes how HTTP connections should be handled if the connection times out before a request is received. These connections typically come from the health probes of a load balancer service or a web browser’s speculative connections, such as a preconnect.

  • If the field is set to Respond, the ingress controller sends an "HTTP 400" or "408" response, logs the connection if access logging is enabled, and counts the connection in the appropriate metrics.
  • If the field is set to Ignore, the ingress controller closes the connection without sending a response, logging the connection, or incrementing metrics. Setting this field to Ignore might impede detection and diagnosis of problems or intrusions, especially when timed-out connections are caused by network errors or port scans. In both cases, logging empty requests can be useful for diagnosing errors and detecting intrusion attempts.

ingress.listenAddress

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.

ingress.logEmptyRequests

Log or Ignore

The default value is Log. Specifies how connections on which empty requests are received are logged. These connections typically come from the health probes of a load balancer service health or a web browser’s speculative connections, such as a preconnect. Logging typical requests might be undesirable, but requests can also be caused by network errors or port scans, in which case logging can be useful for diagnosing errors and detecting intrusion attempts.

ingress.ports.http

80

The default port shown. Configurable. Valid value is a single, unique port in the 1-65535 range. The values of the ports.http and ports.https fields cannot be the same.

ingress.ports.https

443

The default port shown. Configurable. Valid value is a single, unique port in the 1-65535 range. The values of the ports.http and ports.https fields cannot be the same.

ingress.routeAdmissionPolicy

namespaceOwnership or wildcardPolicy

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.

ingress.routeAdmissionPolicy.namespaceOwnership

Strict or InterNamespaceAllowed

Describes how hostname claims across namespaces should be handled. The default value is InterNamespaceAllowed. Specifying Strict prevents routes in different namespaces from claiming the same hostname. If the value is deleted in a customized MicroShift config.yaml file, the InterNamespaceAllowed value is automatically set.

  • Strict: does not allow routes to claim the same hostname across namespaces.
  • InterNamespaceAllowed: allows routes to claim different paths of the same hostname across namespaces.

ingress.routeAdmissionPolicy.wildcardPolicy

WildcardsAllowed or WildcardsDisallowed

Describes how routes with wildcard policies are handled by the ingress controller.

  • WildcardsAllowed: Indicates routes with any wildcard policy are admitted by the ingress controller.
  • WildcardsDisallowed: Indicates only routes with a wildcard policy of None are admitted by the ingress controller. Updating wildcardPolicy from WildcardsAllowed to WildcardsDisallowed causes admitted routes with a wildcard policy of Subdomain to stop working. These routes must be recreated to a wildcard policy of None to be readmitted by the ingress controller. WildcardsDisallowed is the default setting.

ingress.status

Managed or Removed

Router status. The default is Managed.

ingress.tlsSecurityProfile

object

Specifies settings for ingress controllers TLS connections. If you do not set one, the default value is based on the apiservers.config.openshift.io/cluster resource.

ingress.tlsSecurityProfile.type

Old, Intermediate, Modern, Custom

Specifies the profile type for the TLS Security. The default value is Intermediate.

When using the Old, Intermediate, and Modern profile types, the effective profile configuration is subject to change between releases. For example, given a specification to use the Intermediate profile deployed on release X.Y.Z, an upgrade to release X.Y.Z+1 might cause a new profile configuration to be applied to the ingress controller, resulting in a rollout.

ingress.tlsSecurityProfile.minTLSVersion

number

Specifies the TLS version for ingress controllers.

The minimum TLS version is 1.1, and the maximum TLS version is 1.3.

  • Ciphers and the minimum TLS version of the configured security profile are reflected in the TLSProfile status.
  • The ingress controller converts the TLS 1.0 of an Old or Custom profile to 1.1.

ingress.tuningOptions

Objects

Specifies options for tuning the performance of ingress controller pods.

ingress.tuningOptions.clientFinTimeout

string with format duration

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 1s, which is 1 second.

ingress.tuningOptions.clientTimeout

string with format duration

Defines how long a connection is held open while waiting for a client response. The default timeout is 30s, which is 30 seconds.

ingress.tuningOptions.headerBufferBytes

An integer with the format of int32; 16384 is the minimum value when HTTP/2 is enabled.

Describes how much memory in bytes must be reserved for IngressController connection sessions. The default value is 32768 in bytes.

  • Setting this field is generally not recommended because headerBufferBytes values that are too small can break the IngressController and headerBufferBytes values that are too large can cause the IngressController to use significantly more memory than necessary.

ingress.tuningOptions.headerBufferMaxRewriteBytes

integer, formatted int32; 4096 is the minimum value

Describes how much memory in bytes must be reserved from headerBufferBytes for HTTP header rewriting and appending for IngressController connection sessions. The default value is 8192 bytes. Incoming HTTP requests are limited to the headerBufferBytes bytes minus the headerBufferMaxRewriteBytes bytes, meaning that the value of headerBufferBytes must be greater than the value of headerBufferMaxRewriteBytes.

  • Setting this field is generally not recommended because headerBufferMaxRewriteBytes values that are too small can break the IngressController and headerBufferMaxRewriteBytes values that are too large can cause the IngressController to use significantly more memory than necessary.

ingress.tuningOptions.healthCheckInterval: ""

string with pattern: ^(0|([0-9]+(\\.[0-9]+)?(ns|us|µs|μs|ms|s|m|h))+)$

The default healthCheckInterval value is 5s, which is 5 seconds. This parameter value defines how long the router waits between two consecutive health checks on the router’s configured backends. The minimum allowed value is 1s and the maximum allowed value is 2147483647ms, which is 24.85 days.

  • This value is applied globally as a default for all routes, but can be overridden per-route by the route annotation router.openshift.io/haproxy.health.check.interval.
  • Requires an unsigned duration string of decimal numbers, each with an optional fraction and unit suffix, such as 300ms, 1.5h or 2h45m. Valid time units are ns, us (or µs U+00B5 or μs U+03BC), ms, s, m, h.
  • Setting this parameter value to less than 5s can cause excess traffic due to too frequent TCP health checks and accompanying SYN packet storms.
  • Setting this parameter value too high can result in increased latency because of backend servers that are no longer available, but have not yet been detected as such.
  • An empty or 0 value means "no opinion" and the ingress controller chooses a default. Note that the default value might change in future releases.

ingress.tuningOptions.maxConnections

integer, valid values are: empty, 0, -1, and the range 2000-2000000

The default value is 0. defines the maximum number of simultaneous connections that can be established per HAProxy process. Increasing this value allows each ingress controller pod to handle more connections at the cost of additional system resources being consumed.

  • If this field is empty or 0, the IngressController uses the default value of 50000, but the default is subject to change in future releases.
  • If the value is -1, then HAProxy dynamically computes a maximum value based on the available resources set with ulimit values in the running container. Selecting -1, which means auto, results in a large value being computed, and therefore each HAProxy process incurs significant memory usage compared with the current default of 50000.
  • Setting a value that is greater than the current operating system limit prevents the HAProxy process from starting.

  • You can monitor memory usage for router containers with the following metric: 

    container_memory_working_set_bytes{container=`router`,namespace=`openshift-ingress`}`
    Copy to Clipboard Toggle word wrap

  • You can monitor memory usage of individual `HAProxy`processes in router containers with the following metric: 

    container_memory_working_set_bytes{container=`router`,namespace=`openshift-ingress`}/container_processes{container=`router`,namespace=`openshift-ingress`}
    Copy to Clipboard Toggle word wrap

ingress.tuningOptions.serverFinTimeout

string in the format duration

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 1s.

ingress.tuningOptions.serverTimeout

string in the format duration

Defines how long a connection is held open while waiting for a server or backend response. The default timeout is 30s.

ingress.tuningOptions.threadCount

integer in the form int32; minimum value is 1, maximum is 64

Defines the number of threads created per HAProxy process. The default value is 4. If this field is empty, the default value is used.

  • Setting this field is generally not recommended. Creating more threads allows each ingress controller pod to handle more connections at the cost of more system resources being used. Increasing the number of HAProxy threads allows the ingress controller pods to use more CPU time under load, potentially starving other pods if set too high. Conversely, reducing the number of threads may cause the ingress controller to perform poorly.

ingress.tuningOptions.tlsInspectDelay

string in the format duration

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.

  • The default inspect delay is 5s which is 5 seconds, which is expected to be sufficient for most cases. Increasing the value of this configuration specifically for high-latency networks can cause a delay in finishing the SSL handshake. Any configured value must be transparent to your application.

ingress.tuningOptions.tunnelTimeout

string in the format duration

Defines how long a tunnel connection, including websockets, are held open while the tunnel is idle. The default timeout is 1h, which is 1 hour.

kubelet

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.

manifests

list of paths

The locations on the file system to scan for kustomization files to use to load manifests. Set to a list of paths to scan only those paths. Set to an empty list to disable loading manifests. The entries in the list can be glob patterns to match multiple subdirectories. The default values are /usr/lib/microshift/manifests, /usr/lib/microshift/manifests.d/, /etc/microshift/manifests, and /etc/microshift/manifests.d/.

network.clusterNetwork

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 10.42.0.0/16.

network.cniPlugin

String

Deploys the Open Virtual Networking - Kubernetes (OVN-K) network plugin as the default container network interface (CNI) when empty or set to "ovnk". Supported values are empty, "" or "ovnk". Setting to "none" removes the CNI and is not recommended. Only OVN-K is managed by MicroShift.

network.multus.status

string

Controls the deployment of the Multus Container Network Interface (CNI). The default status is Disabled. If you set the value to Enabled, the Multus CNI cannot be deleted.

network.serviceNetwork

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 10.43.0.0/16.

network.serviceNodePortRange

range

The port range allowed for Kubernetes services of type NodePort. If you do not specify the range, the default range of 30000-32767 is used. Services without a NodePort specified are automatically allocated one from this range. This parameter can be updated after MicroShift starts.

node.hostnameOverride

string

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.

node.nodeIP

IPv4 address

The IPv4 address of the node. The default value is the IP address of the default route.

nodeIPv6

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.

storage.driver

none or lvms

The default value is empty. An empty value or null field defaults to LVMS deployment.

storage.optionalCsiComponents

array

The default value is null or an empty array. A null or empty array defaults to deploying snapshot-controller. Expected values are csi-snapshot-controller or none. A value of none is mutually exclusive with all other values.

telemetry.endpoint

https://infogw.api.openshift.com

The endpoint where telemetry data is sent. No user or private data is included in the metrics reported. The default value is https://infogw.api.openshift.com.

telemetry.status

Enabled

Telemetry status, which can be Enabled or Disabled. The default value is Enabled.

2.1.3. Configuring the advertise address network flag
Copiar o link

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.

Important

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.

2.1.4. Extending the port range for NodePort services
Copiar o link

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.

Important

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 nodePort selection. When an explicit nodePort is not specified, the port is assigned randomly by the kube-apiserver and 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:

    Expand
    Table 2.2. Ports to avoid.
    PortDescription

    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

Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat