Global configuration settings allow you to customize parameters that are used by default by all modules and components of the Deckhouse Platform. Some modules may override some of these parameters (this can be found in the settings section of the respective module’s documentation).

The global configuration settings are stored in the ModuleConfig global.

The publicDomainTemplate parameter specifies a DNS name template used by some Deckhouse modules to create Ingress resources. If this parameter is not specified, Ingress resources will not be created.

If you don’t have access to wildcard DNS records, you can use sslip.io or similar services for testing purposes.

The domain specified in the template must not match or be a subdomain of the domain specified in the clusterDomain parameter. We do not recommend changing the clusterDomain value unless absolutely necessary.

For the template to function correctly, you must first configure DNS services both in the networks where the cluster nodes will be located and in the networks from which clients will access the platform’s service web interfaces.

If the template matches the domain of the node network, use only A records to assign addresses of the nodes’ Frontend interfaces to the platform’s service web interfaces.
For example, if the nodes are registered under the company.my zone and the template is %s.company.my.

Example of the ModuleConfig/global:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: global
spec:
  version: 2
  settings: # <-- Module parameters from the "Parameters" section below.
    defaultClusterStorageClass: 'default-fast'
    modules:
      publicDomainTemplate: '%s.kube.company.my'
      placement:
        customTolerationKeys:
        - dedicated.example.com
      storageClass: 'default-fast'

Conversions

Global configuration settings are configured using the global ModuleConfig, the schema of which contains a version number. When you apply an old version of the ModuleConfig schema in a cluster, automatic transformations are performed. To manually update the ModuleConfig schema version, the following steps must be completed sequentially for each version :

  • Updates from version 1 to 2:

    Move storageClass to modules.storageClass. Remove modules.resourcesRequests.everyNode, modules.resourcesRequests.masterNode and modules.proxy parameters.

Parameters

Schema version: 2

  • settings
    object
    • settings.applications
      object

      Common parameters of the Deckhouse ecosystem applications.

      • settings.applications.https
        object

        HTTPS access implementation method used by the Deckhouse ecosystem applications.

        Examples:

        https:
  certManager:
    clusterIssuerName: letsencrypt
  mode: CertManager

        https:
  mode: Disabled

        https:
  mode: OnlyInURI

        https:
  mode: CustomCertificate
  customCertificate:
    secretName: plainstring
        • settings.applications.https.certManager
          object
          • settings.applications.https.certManager.clusterIssuerName
            string

            ClusterIssuer name used by applications to obtain TLS certificates.

            The cert-manager module offers the following ClusterIssuer options:

            • letsencrypt
            • letsencrypt-staging
            • selfsigned
            • clouddns
            • cloudflare
            • digitalocean
            • route53

            You can use your own ClusterIssuer if necessary.

            Default: letsencrypt

        • settings.applications.https.customCertificate
          object
          • settings.applications.https.customCertificate.secretName
            string

            Name of the Secret in the d8-system namespace containing a TLS certificate for applications.

            This Secret must be in the kubernetes.io/tls format.

            Default: false

        • settings.applications.https.mode
          string

          HTTPS usage mode:

          • CertManager: Applications use HTTPS and obtain certificates automatically using the ClusterIssuer defined in the certManager.clusterIssuerName parameter.
          • CustomCertificate: Applications use HTTPS with the certificate from the d8-system namespace.
          • Disabled: Applications use HTTP only.
          • OnlyInURI: Applications use HTTP in the expectation that there is an external upstream HTTPS load balancer, which terminates HTTPS. This load balancer should be capable of redirecting requests from HTTP to HTTPS.

          Default: CertManager

          Allowed values: Disabled, CertManager, CustomCertificate, OnlyInURI

      • settings.applications.ingressClass
        string

        Default IngressClass name used by the Deckhouse ecosystem applications when creating Ingress resources.

        Some applications support their own ingressClass parameter, which lets you use a different IngressClass instead of the default one.

        Default: nginx

        Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        Example:

        ingressClass: nginx
      • settings.applications.publicDomainTemplate
        string

        DNS name template with three %s keys used as the dynamic parts of the string.

        Whenever a DNS is generated:

        • First key is replaced with the component name.
        • Second key is replaced with the application instance name.
        • Third key is replaced with the application’s namespace.

        The Deckhouse ecosystem applications use this template when creating Ingress resources.

        For example, given the template %s.%s.%s.kube.company.my, the web component of an application instance named grafana running in the monitoring namespace will get an Ingress resource at the address web.grafana.monitoring.kube.company.my.

        Usage notes:

        • If this parameter is not specified, Ingress resources will not be created.
        • The domain specified in the template must not match or be a subdomain of the domain specified in the clusterDomain parameter. Changing the clusterDomain value is not recommended unless necessary.
        • Before using the template, configure DNS services both in the networks where the cluster nodes will be located and in the networks from which clients will access the service web interfaces.
        • If the template domain matches the domain of the node network, use only A records to assign addresses of the frontend nodes to the platform service web interfaces. For example, if the nodes are registered under the company.my zone, the template must be %s.%s.%s.company.my.

        Pattern: ^(%s([-a-z0-9]*[a-z0-9])?|[a-z0-9]([-a-z0-9]*)?%s([-a-z0-9]*)?[a-z0-9]|[a-z0-9]([-a-z0-9]*)?%s)\.(%s([-a-z0-9]*[a-z0-9])?|[a-z0-9]([-a-z0-9]*)?%s([-a-z0-9]*)?[a-z0-9]|[a-z0-9]([-a-z0-9]*)?%s)\.(%s([-a-z0-9]*[a-z0-9])?|[a-z0-9]([-a-z0-9]*)?%s([-a-z0-9]*)?[a-z0-9]|[a-z0-9]([-a-z0-9]*)?%s)(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        Examples:

        publicDomainTemplate: "%s.%s.%s.company.my"

        publicDomainTemplate: "%s.%s.%s.kube.company.my"
      • settings.applications.update
        object

        Update settings of the Deckhouse ecosystem applications: the update mode, update windows, update notifications, and blocking the update on alerts.

        The settings are used by applications that do not have their own spec.update settings. The notification settings are also used by applications that have their own update settings, because notifications cannot be configured for a single application.

        If the parameter is omitted, applications use the Deckhouse update settings: the update parameter of the deckhouse module.

        Example:

        update:
  mode: AutoPatch
  windows:
  - from: '8:00'
    to: '15:00'
    days:
    - Tue
    - Sat
  notification:
    webhook: https://release-webhook.mydomain.com
    minimalNotificationTime: 6h
    auth:
      basic:
        username: user
        password: password
        • settings.applications.update.blockOnAlerts
          object

          Settings for blocking application updates while there are alerts in the cluster.

          • settings.applications.update.blockOnAlerts.enabled
            boolean

            If enabled, application updates are blocked while there are alerts in the cluster with a severity level equal to or higher than the one set in the severity parameter.

            Default: false

          • settings.applications.update.blockOnAlerts.severity
            integer

            The severity level of the alerts that block the update.

            The severity level is a number from 0 to 9, where 0 is the highest severity and 9 is the lowest severity.

            Default: 4

            Allowed values: 0 <= X <= 9

        • settings.applications.update.mode
          string

          Update mode of applications on the release channel selected for them.

          • AutoPatch: Automatic update mode for patch versions.

            To change a minor version (for example, from v1.2.* to v1.3.*), confirmation is required.

            A patch version update (for example, from v1.3.1 to v1.3.2) is applied taking into account the update windows, if they are set.

          • Auto: Automatic update mode for all versions.

            Minor version updates (for example, from v1.2.* to v1.3.*) and patch version updates (for example, from v1.3.1 to v1.3.2) are applied taking into account the update windows, if they are set.

          • Manual: Manual update mode for all versions.

            Confirmation is required for updating both minor and patch versions.

          Default: AutoPatch

          Allowed values: AutoPatch, Auto, Manual

        • settings.applications.update.notification
          object

          Settings for notifications of scheduled application updates.

          Has an effect only when an automatic update mode is set.

          Example:

          notification:
  webhook: https://release-webhook.mydomain.com
  minimalNotificationTime: 8h
  retryMinTime: 2s
          • settings.applications.update.notification.auth
            object

            Authentication settings for the webhook.

            If the parameter is omitted, the webhook will be called without authentication.

            • settings.applications.update.notification.auth.basic
              object

              Basic authentication settings for the webhook.

              • settings.applications.update.notification.auth.basic.password
                string

                Required value

                The password for the webhook.

                The username and password will be sent in the Authorization header in the format Basic <base64(username:password)>.

              • settings.applications.update.notification.auth.basic.username
                string

                Required value

                The username for the webhook.

                The username and password will be sent in the Authorization header in the format Basic <base64(username:password)>.

            • settings.applications.update.notification.auth.bearerToken
              string

              The token for the webhook.

              The token will be sent in the Authorization header in the format Bearer <token>.

          • settings.applications.update.notification.minimalNotificationTime
            string

            The minimum time that must pass before updating from the moment a new minor version of an application appears on its release channel.

            It is specified as a string containing the time unit in hours and minutes: 30m, 1h, 2h30m, 24h.

            The update mechanism ensures that an application will not be updated until the specified period of time has passed.

            When using update windows, the application update will happen at the nearest possible update window but not before the time specified in minimalNotificationTime expires.

            Pattern: ^([0-9]+h([0-9]+m)?|[0-9]+m)$

            Example:

            minimalNotificationTime: 6h
          • settings.applications.update.notification.releaseType
            string

            Defines the type of version for which the notification will be sent:

            • Minor: Only for updating the minor version.
            • All: For any updates, including updating a patch version.

            Default: Minor

            Allowed values: All, Minor

            Example:

            releaseType: All
          • settings.applications.update.notification.retryMinTime
            string

            The minimum time between webhook retry attempts when the webhook request fails.

            It is specified as a string containing the time unit in hours, minutes, or seconds: 30s, 1m, 1h, 2h30m.

            The retry mechanism uses exponential backoff: each subsequent retry attempt waits twice as long as the previous one. For example, if retryMinTime is set to 2s, the retry delays will be: 2s, 4s, 8s, 16s, 32s.

            Default value is 2 seconds if not specified.

            Pattern: ^([0-9]+h([0-9]+m)?|[0-9]+m|[0-9]+s)$

            Example:

            retryMinTime: 2s
          • settings.applications.update.notification.tlsSkipVerify
            boolean

            Skip TLS certificate verification while webhook request.

            Default: false

          • settings.applications.update.notification.webhook
            string

            URL for an external webhook handler.

            The POST request is sent to the webhook URL after a new minor version of an application appears on its release channel, before it is applied to the cluster.

            Warning. If you specify an invalid webhook address, application updates will be blocked.

            Use the minimalNotificationTime parameter if necessary to set the minimum time that must pass before updating from the moment a new minor version appears on the release channel.

            Pattern: ^https?://[^\s/$.?#].[^\s]*$

            Example:

            webhook: https://webhook.site/#!/bc8f71ac-c182-4181-9159-6ba6950afffa
        • settings.applications.update.windows
          array of objects

          List of update windows during the day.

          • settings.applications.update.windows.days
            array of strings

            The days of the week on which the update window is applied.

            Example:

            days:
- Mon
- Wed
            • Element of the array
              string

              Day of the week.

              Allowed values: Mon, Tue, Wed, Thu, Fri, Sat, Sun

              Example:

              Mon
          • settings.applications.update.windows.from
            string

            Required value

            Start time of the update window (UTC timezone).

            Should be less than the end time of the update window.

            Pattern: ^(?:\d|[01]\d|2[0-3]):[0-5]\d$

            Example:

            from: '13:00'
          • settings.applications.update.windows.to
            string

            Required value

            End time of the update window (UTC timezone).

            Should be more than the start time of the update window.

            Pattern: ^(?:\d|[01]\d|2[0-3]):[0-5]\d$

            Example:

            to: '18:30'
    • settings.defaultClusterStorageClass
      string

      The name of the StorageClass that DP will define as the default StorageClass used in the cluster.

      DP prohibits manually adding or modifying the default annotation (storageclass.kubernetes.io/is-default-class='true') for StorageClass. Use the parameter to define or change the StorageClass that is used as the default in the cluster.

      If the parameter is omitted, the default StorageClass is either:

      • A StorageClass in the cluster that has the default annotation (storageclass.kubernetes.io/is-default-class='true');
      • The first (alphabetically) StorageClass created by the cloud provider module (if any cloud provider module is used).

      Use this parameter to change the default StorageClass in the cluster, as manually adding the default annotation to a StorageClass is not allowed.

      Default:

    • settings.highAvailability
      boolean

      A global switch to enable the high availability mode for modules that support it.

      If not defined, the value is determined automatically as true for clusters with more than one master node. Otherwise, it is determined asfalse.

      Examples:

      highAvailability: true

      highAvailability: false
    • settings.modules
      object

      Common parameters of Deckhouse modules.

      • settings.modules.gatewayAPIGateway
        object

        Reference to the Gateway object (from the Gateway API) used by Deckhouse modules when creating Gateway API resources.

        If not specified, modules use the Gateway automatically discovered in the cluster (if any).

        • settings.modules.gatewayAPIGateway.name
          string

          Required value

          Name of the Gateway object.

        • settings.modules.gatewayAPIGateway.namespace
          string

          Required value

          Namespace of the Gateway object.

      • settings.modules.https
        object

        HTTPS access implementation method used by the Deckhouse ecosystem modules.

        Examples:

        https:
  certManager:
    clusterIssuerName: letsencrypt
  mode: CertManager

        https:
  mode: Disabled

        https:
  mode: OnlyInURI

        https:
  mode: CustomCertificate
  customCertificate:
    secretName: plainstring
        • settings.modules.https.certManager
          object
          • settings.modules.https.certManager.clusterIssuerName
            string

            ClusterIssuer name used by modules to obtain TLS certificates.

            The cert-manager module offers the following ClusterIssuer options:

            • letsencrypt
            • letsencrypt-staging
            • selfsigned
            • clouddns
            • cloudflare
            • digitalocean
            • route53

            You can use your own ClusterIssuer if necessary.

            Default: letsencrypt

        • settings.modules.https.customCertificate
          object
          • settings.modules.https.customCertificate.secretName
            string

            Name of the Secret in the d8-system namespace containing a TLS certificate for modules.

            This Secret must be in the kubernetes.io/tls format.

            Default: false

        • settings.modules.https.mode
          string

          HTTPS usage mode:

          • CertManager: Modules use HTTPS and obtain certificates automatically using the ClusterIssuer defined in the certManager.clusterIssuerName parameter.
          • CustomCertificate: Modules use HTTPS with the certificate from the d8-system namespace.
          • Disabled: Modules use HTTP only (some modules, such as user-authn, may not work).
          • OnlyInURI: Modules use HTTP in the expectation that there is an external upstream HTTPS load balancer, which terminates HTTPS. This load balancer should be capable of redirecting requests from HTTP to HTTPS.

          Default: CertManager

          Allowed values: Disabled, CertManager, CustomCertificate, OnlyInURI

      • settings.modules.ingressClass
        string

        Default IngressClass name used by Deckhouse modules when creating Ingress resources.

        Some modules support their own ingressClass parameter, which lets you use a different IngressClass instead of the default one.

        Default: nginx

        Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        Example:

        ingressClass: nginx
      • settings.modules.placement
        object

        Parameters regulating the layout of Deckhouse module components.

        • settings.modules.placement.customTolerationKeys
          array of strings

          A list of custom toleration keys; use them to allow the deployment of some critical add-ons (such as cni and csi) on dedicated nodes.

          Example:

          customTolerationKeys:
- dedicated.example.com
- node-dedicated.example.com/master
      • settings.modules.publicDomainTemplate
        string

        A DNS name template with the %s key used as a dynamic part of the string.

        Deckhouse modules use this template when creating Ingress resources.

        For example, given the template %s.kube.company.my, the prometheus module will create an Ingress resource at the address grafana.kube.company.my to provide access to Grafana.

        Pay attention to the following:

        • If this parameter is not specified, Ingress resources will not be created.
        • The domain specified in the template must not match or be a subdomain of the domain specified in the clusterDomain parameter. It is not recommended to change the clusterDomain value unless absolutely necessary.
        • For the template to function correctly, you must first configure DNS services both in the networks where the cluster nodes will be located and in the networks from which clients will access the platform’s service web interfaces.
        • If the template matches the domain of the node network, use only A records to assign addresses of the nodes’ Frontend interfaces to the platform’s service web interfaces. For example, if the nodes are registered under the company.my zone and the template is %s.company.my.

        Pattern: ^(%s([-a-z0-9]*[a-z0-9])?|[a-z0-9]([-a-z0-9]*)?%s([-a-z0-9]*)?[a-z0-9]|[a-z0-9]([-a-z0-9]*)?%s)(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        Examples:

        publicDomainTemplate: "%s.kube.company.my"

        publicDomainTemplate: kube-%s.company.my
      • settings.modules.resourcesRequests
        object

        The amount of resources (CPU and memory) allocated to some components.

        More info in the Kubernetes documentation.

        • settings.modules.resourcesRequests.controlPlane
          Deprecated
          object

          Deprecated. Use control-plane-manager moduleconfig parameter .spec.settings.resourcesRequests instead.

          Amount of resources (CPU and memory) allocated to control-plane components on each master node.

          These settings do not apply if the cluster control plane is managed by a cloud provider (for example, Google Kubernetes Engine or Azure Kubernetes Service).

          Example:

          controlPlane:
  cpu: 1000m
  memory: 500M
          • settings.modules.resourcesRequests.controlPlane.cpu
            Deprecated
            string or number

            Deprecated. Use controlPlaneManager.spec.settings.resourcesRequests.cpu instead.

            The combined CPU requests for control-plane components on each master node.

            Pattern: ^[0-9]+m?$

          • settings.modules.resourcesRequests.controlPlane.memory
            Deprecated
            string

            Deprecated. Use controlPlaneManager.spec.settings.resourcesRequests.memory instead.

            The combined memory requests for control-plane components on each master node.

            Pattern: ^[0-9]+(\.[0-9]+)?(E|P|T|G|M|K|Ei|Pi|Ti|Gi|Mi|Ki)?$

      • settings.modules.storageClass
        string

        The StorageClass to use with all Deckhouse Platform components (Prometheus, Grafana, OpenVPN, etc.) unless it is overridden in the module configuration.

        If the value is not specified, the default StorageClass set in the cluster is used.

        Important notes:

        • If the module’s configuration defines its own storageClass parameter, the module’s value takes precedence and the global modules.storageClass is not used.
        • If a PersistentVolumeClaim (PVC) for a module already exists, changing this parameter does not affect the existing PVC or require disk recreation. The module uses the existing PVC and its StorageClass. See the prometheus module example for more details on how this parameter is applied.
        • This parameter is applied during module activation when creating new PVCs.
        • Use this parameter only in exceptional circumstances.

        Default:

    • settings.storageClass
      Deprecated
      string

      Deprecated. Use settings.modules.storageClass instead.

      The StorageClass to use with all Deckhouse Platform components (Prometheus, Grafana, OpenVPN, etc.).

      • If the value is not specified, the default StorageClass set in the cluster is used.
      • Use this parameter only in exceptional circumstances.
      • This parameter is applied during module activation.

      Default:

Additional resources