Module registry: configuration

Schema version: 1

• settings

  object
  • settings.https

    object

    What certificate type to use.

    This parameter completely overrides the global.modules.https settings.

    Examples:

    https:
      mode: Disabled
    

    https:
      mode: OnlyInURI
    

    https:
      mode: CustomCertificate
      customCertificate:
        secretName: foobar
    

    https:
      mode: CertManager
      certManager:
        clusterIssuerName: letsencrypt
    

    • settings.https.certManager

      object

      Parameters for certmanager.

      • settings.https.certManager.clusterIssuerName

        string

        What ClusterIssuer to use for getting an SSL certificate (currently, letsencrypt, letsencrypt-staging, selfsigned are available; also, you can define your own).

        Default: letsencrypt

        Example:

        clusterIssuerName: letsencrypt
        

    • settings.https.customCertificate

      object

      Parameters for custom certificate usage.

      • settings.https.customCertificate.secretName

        string

        The name of the secret in the d8-system namespace to use with the registry ingress.

        This secret must have the kubernetes.io/tls format.

    • settings.https.mode

      string

      The HTTPS usage mode:

      • CertManager: The registry ingress is accessed over HTTPS using a certificate obtained from a clusterIssuer specified in the certManager.clusterIssuerName parameter.
      • CustomCertificate: The registry ingress is accessed over HTTPS using a certificate from the d8-system namespace.
      • Disabled: In this mode, the registry ingress can only be accessed over HTTP.
      • OnlyInURI: The registry ingress will work over HTTP (thinking that there is an external HTTPS load balancer in front of it that terminates HTTPS traffic). Load balancer should provide a redirect from HTTP to HTTPS.

      Default: CertManager

      Allowed values: Disabled, CertManager, CustomCertificate, OnlyInURI

  • settings.ingressClass

    string

    The class of the Ingress controller used for the registry.

    Optional. By default, the modules.ingressClass global value is used.

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

  • settings.mode

    string

    Whether the module manages how the cluster pulls images.

    • Unmanaged — the module manages nothing. No components are created and no node configuration is written; the cluster keeps pulling from the registry it was installed with. This is the default, so enabling the module changes nothing on its own.

      Asking for Unmanaged on a cluster the module was managing does not take effect instantly: image references all over the cluster name the in-cluster registry, and they move to the upstream one only as each module’s release is rendered again. So the module stops advertising its address at once and keeps serving it until nothing names it any more, which normally takes a few minutes. On a cluster that was installed with the module already managing, it also writes the registry it was fetching from back into the cluster’s registry credentials — otherwise nothing would remember where images come from, since the installer had put the in-cluster registry there. Until then its components are still running, and D8RegistryDrainStuck reports a withdrawal that cannot finish.

    • Managed — the module owns the pull path: it configures the container runtime on every node through its node agent, and optionally runs an in-cluster cache.

    There is no choice of implementation. A cluster that has never run the previous implementation of this module always uses the current one; a cluster that has runs the previous one until it is brought to its Unmanaged state, after which the migration completes on its own.

    Default: Unmanaged

    Allowed values: Managed, Unmanaged

  • settings.primary

    object

    The single authoritative source of Deckhouse component images. Applies only when mode is Managed.

    Additional registries are declared as separate RegistryUpstream resources rather than here: a module or a user bringing their own registry must not have to edit a ModuleConfig owned by someone else.

    • settings.primary.upstream

      object

      The registry to pull Deckhouse component images from.

      If omitted, the cluster is air-gapped: the in-cluster cache becomes authoritative and is populated with d8 mirror push. Omitting it requires storage.cache: true and storage.source.

      Example:

      upstream:
        host: registry.deckhouse.io
        path: "/deckhouse/ee"
        scheme: HTTPS
        auth:
          license: DECKHOUSE_LICENSE_KEY
      

      • settings.primary.upstream.auth

        object

        Credentials for the registry.

        • settings.primary.upstream.auth.license

          string

          The Deckhouse license key.

          A shorthand for the username/password pair used with registry.deckhouse.io. Mutually exclusive with them.

          Changing the license changes the registry credentials, so it goes through the same preflight probe as an address change: the new credentials are verified before the cluster is switched over, and the last known good ones are kept if the probe fails.

        • settings.primary.upstream.auth.password

          string

          The password for basic authentication.

        • settings.primary.upstream.auth.username

          string

          The username for basic authentication.

      • settings.primary.upstream.ca

        string

        A PEM-encoded certificate authority bundle used to verify the registry when scheme is HTTPS.

        If not specified, the system trust store is used.

      • settings.primary.upstream.host

        string

        Required value

        The registry host, optionally with a port.

        Examples:

        host: registry.deckhouse.io
        

        host: my-private-registry.com:5000
        

      • settings.primary.upstream.mirrors

        array of objects

        Additional addresses serving the same content as the primary registry, used for failover and load balancing.

        Mirrors are not separate sources: the cache holds one de-duplicated set regardless of which mirror the images came from. A registry with different content is an additional upstream and belongs in a RegistryUpstream resource.

        • settings.primary.upstream.mirrors.auth

          object

          Credentials for the registry.

          • settings.primary.upstream.mirrors.auth.license

            string

            The Deckhouse license key.

            A shorthand for the username/password pair used with registry.deckhouse.io. Mutually exclusive with them.

            Changing the license changes the registry credentials, so it goes through the same preflight probe as an address change: the new credentials are verified before the cluster is switched over, and the last known good ones are kept if the probe fails.

          • settings.primary.upstream.mirrors.auth.password

            string

            The password for basic authentication.

          • settings.primary.upstream.mirrors.auth.username

            string

            The username for basic authentication.

        • settings.primary.upstream.mirrors.ca

          string

          A PEM-encoded certificate authority bundle used to verify the mirror.

        • settings.primary.upstream.mirrors.host

          string

          Required value

          The mirror host, optionally with a port.

        • settings.primary.upstream.mirrors.path

          string

          The repository prefix inside the mirror.

        • settings.primary.upstream.mirrors.scheme

          string

          The protocol used to reach the mirror.

          Default: HTTPS

          Allowed values: HTTP, HTTPS

      • settings.primary.upstream.path

        string

        The repository prefix inside the registry.

        Example:

        path: "/deckhouse/ee"
        

      • settings.primary.upstream.scheme

        string

        The protocol used to reach the registry.

        Use HTTP only for insecure, trusted registries.

        Default: HTTPS

        Allowed values: HTTP, HTTPS

  • settings.storage

    object

    The in-cluster registry cache. Applies only when mode is Managed.

    • settings.storage.cache

      boolean

      Whether pulls go through the in-cluster cache on the master nodes.

      This is one of the two configuration axes; the other is whether primary.upstream is set. Together they cover every supported layout:

      • cache: false with an upstream — nodes pull straight from the upstream, no cache is deployed.
      • cache: true with an upstream — a pass-through cache, filled from the upstream.
      • cache: true without an upstream — air-gap: the cache is the only source of images and is filled with d8 mirror push.

      Turning the cache on or off is a safe, idempotent reconfiguration. Removing the upstream while the cache is on is the one transition with a condition: it takes effect only once the cache leader holds the whole expected image set, so nodes are never cut off.

      Default: false

    • settings.storage.garbageCollection

      object

      When the cache reclaims the disk taken by releases the cluster has moved past.

      Needed because nothing else ever removes anything: every release adds a slice of the repository, so a cluster that lives for years fills its store and then stops being able to pull.

      A collection puts one replica read-only for as long as it takes. That replica keeps serving every image it holds; what it cannot do is store the result of a cache miss, or accept a d8 mirror push. Only one replica collects at a time, so the others are unaffected.

      • settings.storage.garbageCollection.enabled

        boolean

        Whether the cache reclaims its disk at all.

        Turning this off leaves the store to grow without bound, which only makes sense with a disk large enough that it never matters.

        Default: true

      • settings.storage.garbageCollection.schedule

        string

        A five-field cron expression, in the replicas’ own time zone.

        Defaults to a night hour. If the master node group has a maintenance window, the start of that window is used instead — that being a time the operator has already declared safe for disruption.

        Pattern: ^\s*\S+\s+\S+\s+\S+\s+\S+\s+\S+\s*$

        Examples:

        schedule: 17 3 * * *
        

        schedule: 0 2 * * Sun
        

    • settings.storage.size

      string

      The size of the persistent volume backing the cache.

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

      Example:

      size: 50Gi
      

    • settings.storage.source

      object

      The image set the cache is expected to hold.

      Required in an air-gapped cluster: with no upstream to fall back on, completeness must be decidable before the cache can be trusted as the only source.

      • settings.storage.source.bundleRef

        string

        The name of the image set, for example the bundle pushed with d8 mirror push.

        Example:

        bundleRef: d8-mirror-bundle
        

      • settings.storage.source.expectedDigests

        integer

        The number of distinct digests the set contains.

        Allowed values: 0 <= X

        Example:

        expectedDigests: 459
        

  • settings.whitelistSourceRanges

    array of strings

    A list of CIDR-formatted addresses allowed to connect to the registry. If not specified, connections from any address are allowed.

    Example:

    whitelistSourceRanges:
    - 10.0.0.0/10
    - 192.168.0.0/16
    

    • Element of the array

      string

      Pattern: ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))?$