The deckhouse module: configuration

Schema version: 1

• settings

  object
  • settings.allowExperimentalModules

    boolean

    Allows the use of experimental modules (modules in the Experimental lifecycle stage).

    Experimental modules can be unstable and are not supported under the Deckhouse SLA. Use them with caution.

    Example:

    allowExperimentalModules: false
    

  • settings.bundle

    string

    The Deckhouse bundle defines a set of modules enabled by default.

    • Default — the recommended set of modules for cluster operation: monitoring, authorization control, networking and other needs.
    • Managed — the bundle aimed at clusters managed by cloud providers (e.g., Google Kubernetes Engine).
    • Minimal — the minimum possible bundle option (includes a single module — this one). Note that several basic modules are not included in the set of modules Minimal (for example, the CNI module). Deckhouse with the set of modules Minimal without the basic modules will be able to work only in an already deployed cluster.

    Default: Default

    Allowed values: Default, Minimal, Managed

    Example:

    bundle: Default
    

  • settings.highAvailability

    boolean

    Manually enable the high availability mode.

    By default, Deckhouse automatically decides whether to enable the HA mode. Click here to learn more about the HA mode for modules.

    Example:

    highAvailability: true
    

  • settings.license

    object

    Edition settings of the Deckhouse Kubernetes Platform.

    • settings.license.edition

      string

      Edition of the Deckhouse Kubernetes Platform:

      • CE — Community Edition.
      • BE - Basic edition.
      • EE — Enterprise Edition.
      • SE — Standard Edition.
      • SE-plus — Standard Edition+.

      Default: CE

      Example:

      edition: CE
      

  • settings.logLevel

    string

    Deckhouse logging level.

    Default: Info

    Allowed values: Debug, Info, Error

    Example:

    logLevel: Info
    

  • settings.nodeSelector

    object

    The same as in the Pods’ spec.nodeSelector parameter in Kubernetes.

    If the parameter is omitted or false, nodeSelector will be determined automatically.

    Caution! Deckhouse will stop working if there is a nonexistent label in nodeSelector. You need to change the values to the correct ones in ModuleConfig/deckhouse and deployment/deckhouse to get Deckhouse back on track.

  • settings.registry

    object

    Settings for accessing the container registry with Deckhouse images.

    This parameter allows you to configure how Deckhouse connects to the container registry to pull its own component images. You can either rely on pre-configured access on cluster nodes (Unmanaged mode) or provide Deckhouse with direct access credentials (Direct mode).

    Examples:

    registry:
      mode: Unmanaged
    

    registry:
      mode: Direct
      direct:
        imagesRepo: registry.deckhouse.io/deckhouse/ee
        license: DECKHOUSE_LICENSE_KEY
    

    • settings.registry.direct

      object

      Parameters for the Direct access mode. These parameters are required when mode is set to Direct.

      Examples:

      direct:
        imagesRepo: registry.deckhouse.io/deckhouse/ee
        license: DECKHOUSE_LICENSE_KEY
      

      direct:
        imagesRepo: my-private-registry.com/deckhouse
        username: user
        password: password
        scheme: HTTPS
        ca: |
          -----BEGIN CERTIFICATE-----
          MIIC...
          -----END CERTIFICATE-----
      

      • settings.registry.direct.ca

        string

        The root CA certificate (in PEM format) for validating the container registry’s server certificate. This is necessary if the registry uses a self-signed certificate or a certificate issued by a private Certificate Authority. If not provided, the system’s trusted root CAs will be used.

      • settings.registry.direct.imagesRepo

        string

        Required value

        The address of the container registry repository where Deckhouse images are stored.

        In firewalled environments, this might be a private registry address that mirrors the public one.

        Pattern: ^[0-9a-zA-Z\.\-]+(\:[0-9]{1,5})?(\/[0-9a-zA-Z\.\-\_\/]+)?$

        Examples:

        imagesRepo: registry.deckhouse.io/deckhouse/ee
        

        imagesRepo: private-registry:5000/deckhouse/ce
        

      • settings.registry.direct.license

        string

        The license key for accessing the Deckhouse container registry. This key is used as a password with the username license-token. This field is mutually exclusive with username/password.

        Example:

        license: DECKHOUSE_LICENSE_KEY
        

      • settings.registry.direct.password

        string

        The password for authenticating with the container registry. This field is required if license is not provided.

        Example:

        password: registry-password
        

      • settings.registry.direct.scheme

        string

        The protocol to use for connecting to the registry.

        Use HTTP only for insecure, trusted registries (e.g., in a firewalled environment). Defaults to HTTPS for secure communication.

        Default: HTTPS

        Allowed values: HTTP, HTTPS

        Example:

        scheme: HTTPS
        

      • settings.registry.direct.username

        string

        The username for authenticating with the container registry. This field is required if license is not provided.

        Example:

        username: registry-user
        

    • settings.registry.mode

      string

      The mode for accessing the container registry with Deckhouse images.

      • Unmanaged — the default mode. In this mode, the registry module does not run an internal registry. Access to the registry is configured manually using the change-registry helper script. Note: Changing the registry in this mode will cause a full restart of all Deckhouse components.
      • Direct — a mode for direct access to the registry. It uses a “virtual” registry address that is overwritten on the fly to the real registry address. This allows for registry changes without a full component restart.

      Default: Direct

      Allowed values: Unmanaged, Direct

  • settings.releaseChannel

    string

    Desirable Deckhouse release channel (Deckhouse will switch to it when such an opportunity appears).

    The order in which the stability of the release channel increases (from less stable to more stable): Alpha, Beta, EarlyAccess, Stable, RockSolid.

    Allowed values: Alpha, Beta, EarlyAccess, Stable, RockSolid

    Example:

    releaseChannel: Stable
    

  • settings.tolerations

    array of objects

    The same as in the Pods’ spec.tolerations parameter in Kubernetes;

    If the parameter is omitted or false, tolerations will be determined automatically.

    Caution! Deckhouse will stop working if tolerations specified are incorrect. You need to change the values to the correct ones in ModuleConfig/deckhouse and deployment/deckhouse to get Deckhouse back on track.

    • settings.tolerations.effect

      string
    • settings.tolerations.key

      string
    • settings.tolerations.operator

      string
    • settings.tolerations.tolerationSeconds

      integer
    • settings.tolerations.value

      string
  • settings.update

    object

    Settings of the Deckhouse update mode and windows.

    Example:

    update:
      windows:
      - from: '8:00'
        to: '15:00'
        days:
        - Tue
        - Sat
      disruptionApprovalMode: Manual
      notification:
        webhook: https://release-webhook.mydomain.com
        minimalNotificationTime: 6h
        auth:
          basic:
            username: user
            password: password
    

    • settings.update.disruptionApprovalMode

      Deprecated

      string

      Update mode for disruptive Deckhouse releases:

      • Auto — a disruptive release is approved automatically.
      • Manual — requires a manual release confirmation (set the release.deckhouse.io/disruption-approved=true annotation on the appropriate DeckhouseRelease resource to apply the update).

      Default: Auto

      Allowed values: Auto, Manual

    • settings.update.mode

      string

      Update mode of Deckhouse on the selected release channel.

      • AutoPatch — automatic update mode for patch releases.

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

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

      • Auto — automatic update mode for all versions.

        A minor version updates (for example, from v1.69.* to v1.70.*) and patch version updates (for example, from v1.70.1 to v1.70.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.

      To confirm the version update, it is necessary to set the approved field to true in the corresponding resource DeckhouseRelease.

      Default: AutoPatch

      Allowed values: AutoPatch, Auto, Manual

    • settings.update.notification

      object

      Settings for notifications of scheduled Deckhouse updates.

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

      Example:

      notification:
        webhook: https://release-webhook.mydomain.com
        minimalNotificationTime: 8h
        retryMinTime: 2s
      

      • settings.update.notification.auth

        object

        Authentication settings for the webhook.

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

        • settings.update.notification.auth.basic

          object

          Basic authentication settings for the webhook.

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

          • settings.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.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.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.update.notification.minimalNotificationTime

        string

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

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

        The update mechanism ensures that Deckhouse will not be updated until a specified period of time has passed.

        When using update windows, the Deckhouse 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.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.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, 2m30s, 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.update.notification.tlsSkipVerify

        boolean

        Skip TLS certificate verification while webhook request.

        Default: false

      • settings.update.notification.webhook

        string

        URL for an external webhook handler.

        The POST request will be sent to the webhook URL after a new minor version of Deckhouse appears on the release channel before it is applied to the cluster.

        Caution! If you specify an invalid webhook address, Deckhouse update 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 used.

        Example of the POST request payload (Content-Type: application/json):

        {
          "subject":"Deckhouse",
          "version": "1.36.0",
          "requirements":  {"k8s": "1.20.0"},
          "changelogLink": "https://github.com/deckhouse/deckhouse/changelog/1.36.md",
          "applyTime": "2023-01-01T14:30:00Z00:00",
          "message": "New Deckhouse Release 1.36.0 is available. Release will be applied at: Friday, 01-Jan-23 14:30:00 UTC"
        }
        

        Description of POST request fields:

        • subject — string, the update event type. Possible values: Deckhouse, Module;
        • moduleName — string, the name of the module. Set only if subject: Module.
        • version - string, x.y.z (semantic versioning);
        • requirements - object, version requirements;
        • changelogLink - string, a URL to the minor version changelog;
        • applyTime - string, date and time of the scheduled update (taking into account the configured update windows) in RFC3339 format;
        • message - string, a text message about the availability of the new minor version and the scheduled update time.

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

        Example:

        webhook: https://webhook.site/#!/bc8f71ac-c182-4181-9159-6ba6950afffa
        

    • settings.update.windows

      array of objects

      List of update windows during the day.

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