Global configuration

• 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.

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.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.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: