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 network.clusterDomain parameter of the control-plane-manager module. We do not recommend changing the cluster domain 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.

  • Updates from version 2 to 3:

    Move modules.ingressClass to modules.ingress.ingressClass, and modules.gatewayAPIGateway to modules.gatewayAPI.gateway.

Parameters

Schema version: 3

  • 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 two %s keys used as the dynamic parts of the string.

        Whenever a DNS is generated:

        • First key is replaced with the application instance name.
        • Second 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.kube.company.my, the application instance named grafana running in the monitoring namespace will get an Ingress resource at the address 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 network.clusterDomain parameter of the control-plane-manager module. Changing the cluster domain 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.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)(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        Examples:

        publicDomainTemplate: "%s.%s.company.my"
        
        publicDomainTemplate: "%s.%s.kube.company.my"
        
    • 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.gatewayAPI
        object

        Common parameters for Gateway API usage by DP modules.

        • settings.modules.gatewayAPI.enabled
          boolean

          Enables the use of Gateway API resources (Gateway, HTTPRoute, etc.) by the DP modules that support it.

          Unlike ingressClass, there is no built-in default Gateway, so Gateway API is only actually used by a module if this flag is enabled and a Gateway can be resolved for it — either from this parameter’s gateway field, a module-specific override, or a Gateway automatically discovered in the cluster.

          Modules that support Gateway API can override this setting with their own gatewayAPI.enabled parameter.

        • settings.modules.gatewayAPI.gateway
          object

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

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

          • settings.modules.gatewayAPI.gateway.name
            string

            Required value

            Name of the Gateway object.

          • settings.modules.gatewayAPI.gateway.namespace
            string

            Required value

            Namespace of the Gateway object.

      • settings.modules.gatewayAPIGateway
        Deprecated
        object

        Deprecated. Use settings.modules.gatewayAPI.gateway instead.

        Reference to the Gateway object (from the Gateway API) used by DP 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.ingress
        object

        Common parameters for Ingress usage by DP modules.

        • settings.modules.ingress.enabled
          boolean

          Enables the creation of Ingress resources by the DP modules that support it.

          Modules that support Ingress can override this setting with their own ingress.enabled parameter.

          Default: true

        • settings.modules.ingress.ingressClass
          string

          Default IngressClass name used by DP 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

      • settings.modules.ingressClass
        Deprecated
        string

        Deprecated. Use settings.modules.ingress.ingressClass instead.

        Default IngressClass name used by DP 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 network.clusterDomain parameter of the control-plane-manager module. It is not recommended to change the cluster domain 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.prefix
      string

      A prefix of the objects to be created in the cloud.

      Is used, for example, to distinguish objects created for different clusters, to configure routing, etc.

      This is the new home for the prefix that was previously set in ClusterConfiguration.cloud.prefix. If not set, the value from ClusterConfiguration.cloud.prefix is used.

      The prefix is used to name cloud objects such as disks (e.g. <prefix>-kubernetes-data-0). Cloud object names are limited to 63 characters, so the prefix is capped at 45 characters to leave room for the generated suffix. Depending on the provider and the number of master nodes, the effective limit may be lower; this is additionally enforced by a bootstrap preflight check.

      Warning. This value names existing cloud infrastructure (security groups, route tables, resource groups, instances, etc.). It must match the prefix the cluster was bootstrapped with — setting a different value will break cloud integration. It is not intended to be changed in a running cluster.

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

      Maximum length: 45

      Example:

      prefix: kube
      
    • 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