Available in editions:  Open/CE, BE, SE, SE+, Ultimate/EE, Core

The module lifecycle stage: General Availability

The module does not have any mandatory parameters.

The module has 9 alerts.

The module is enabled by default in the following bundles: Default, Managed. The module is disabled by default in the Minimal bundle.

How to explicitly enable the module...

You may explicitly enable or disable the module in one of the following ways:

  • Via Deckhouse web UI. In the “System” → “System Management” → “Deckhouse” → “Modules” section, open the documentation module and enable (or disable) the “Module enabled” toggle. Save changes.

    Example:

    Module enable/disable interface

  • Via Deckhouse CLI (d8).

    Use the d8 system module enable command for enabling, or d8 system module disable command for disabling the module (you need Deckhouse CLI (d8), configured to work with the cluster).

    Example of enabling the module:

    d8 system module enable documentation
    
  • Using ModuleConfig documentation.

    Set spec.enabled to true or false in ModuleConfig documentation (create it if necessary);

    Example of a manifest to enable module documentation:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: documentation
    spec:
      enabled: true
    

How to configure the module...

You can configure the module in one of the following ways:

  • Via Deckhouse web UI.

    In the “System” → “System Management” → “Deckhouse” → “Modules” section, open the documentation module and enable the “Advanced Settings” switch. Fill in the required fields in the “Configuration” tab or specify the module settings in YAML format on the “YAML” tab, excluding the settings section. Save the changes.

    Example:

    Module Setup Interface

    You can also edit the ModuleConfig object documentation on the “YAML” tab in the module settings window (“System” → “System Management” → “Deckhouse” → “Modules”, open the module documentation) by specifying the schema version in the spec.version parameter and the necessary module parameters in the spec.settings section.

  • Via Deckhouse CLI (d8) (requires Deckhouse CLI (d8) configured to work with the cluster).

    Edit the existing ModuleConfig documentation (for more details on configuring Deckhouse, see the documentation) by executing the following command:

    d8 k edit mc documentation
    

    Make the necessary changes in the spec.settings section. If necessary, specify the schema version in the spec.version parameter. Save the changes.

    You can also create a file with manifest for ModuleConfig documentation using the example below. Fill in the spec.settings section with the required module parameters. If necessary, specify the schema version in the spec.version parameter.

    Apply the manifest using the following command (indicate the manifest file name):

    d8 k apply -f <FILENAME>
    

    Example of a manifest for ModuleConfig documentation:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: documentation
    spec:
      version: 1
      enabled: true
      settings: # Module parameters from the "Parameters" section below.
    

Parameters

Schema version: 1

  • settings
    object
    • settings.auth
      object

      Parameters to authenticate and authorize access to the documentation web interface.

      • settings.auth.allowedUserEmails
        array of strings

        Array of emails of users that can access module’s public web interfaces.

        This parameter is used if the user-authn module is enabled or the externalAuthentication parameter is set.

      • settings.auth.allowedUserGroups
        array of strings

        Array of groups whose users can browse the documentation.

        This parameter is used if the user-authn module is enabled or the externalAuthentication parameter is set.

        Caution! If the module works together with the user-authn module, add the allowed groups to the DexProvider configuration.

        Default: []

        Examples:

        allowedUserGroups:
        - admin
        - users
        
        allowedUserGroups: []
        
      • settings.auth.externalAuthentication
        object

        Parameters to enable external authentication based on the Ingress NGINX external-auth mechanism that uses the Nginx auth_request module.

        External authentication is enabled automatically if the user-authn module is enabled.

        • settings.auth.externalAuthentication.authSignInURL
          string

          URL to redirect the user for authentication (if the authentication service returned a non-200 HTTP response).

          Default:

          Example:

          authSignInURL: https://$host/dex-authenticator/sign_in
          
        • settings.auth.externalAuthentication.authURL
          string

          URL of the authentication service.

          If the user is authenticated, the service should return an HTTP 200 response code.

          Default:

          Example:

          authURL: https://documentation-dex-authenticator.d8-system.svc.cluster.local/dex-authenticator/auth
          
    • settings.highAvailability
      boolean

      Manually enable the high availability mode.

      By default, Deckhouse Platform automatically decides whether to enable the HA mode. Learn more about the high availability mode for modules.

      In the HA mode the documentation runs in two replicas on different nodes; the “High availability mode” section of the usage page of the module tells what it needs and why S3 helps.

      Examples:

      highAvailability: true
      
      highAvailability: false
      
    • 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

          Name of the Secret in the d8-system namespace to use with the documentation web UI.

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

      • settings.https.mode
        string

        HTTPS usage mode:

        • CertManager — the web UI is accessed over HTTPS using a certificate obtained from a clusterIssuer specified in the certManager.clusterIssuerName parameter.
        • CustomCertificate — the web UI is accessed over HTTPS using a certificate from the d8-system namespace.
        • Disabled — in this mode, the documentation web UI can only be accessed over HTTP.
        • OnlyInURI — HTTP access with an external HTTPS balancer. The balancer terminates HTTPS, and all links in user-authn are generated with the HTTPS scheme. The balancer must provide redirection from HTTP to HTTPS.

        Default: CertManager

        Allowed values: Disabled, CertManager, CustomCertificate, OnlyInURI

    • settings.ingressClass
      string

      Class of the Ingress controller of the documentation web UI.

      An optional parameter; 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.moduleStorage
      object

      Storage of the documentation of module versions, prepared when a version is opened for the first time.

      • settings.moduleStorage.s3
        object

        Where the prepared documentation of module versions is kept besides the cache of the documentation pod.

        • settings.moduleStorage.s3.external
          object

          S3 storage of your own for type: External. The connection and the keys are taken from a Secret; the keys it holds are listed in the “S3 storage of your own” section of the usage page of the module.

          • settings.moduleStorage.s3.external.prefix
            string

            Part of the bucket the module uses: every object it reads, writes or deletes has a key starting with this prefix. Other objects of the bucket stay untouched, so the bucket may be shared.

            Default: documentation/

            Pattern: ^([A-Za-z0-9][A-Za-z0-9._-]*/)+$

            Examples:

            prefix: documentation/
            
            prefix: clusters/main/documentation/
            
          • settings.moduleStorage.s3.external.secretRef
            object

            Required value

            Secret with the connection and the keys of the S3 storage, in any namespace.

            Deckhouse Platform copies it into the documentation-s3-connection Secret in d8-system. The documentation pod uses that Secret. After the Secret is created or changed, the documentation pod restarts within 5 minutes. Until the Secret appears, the versions are kept in the pod only.

            • settings.moduleStorage.s3.external.secretRef.name
              string

              Required value

              Name of the Secret.

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

              Maximum length: 253

              Example:

              name: documentation-s3
              
            • settings.moduleStorage.s3.external.secretRef.namespace
              string

              Required value

              Namespace of the Secret.

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

              Maximum length: 63

              Examples:

              namespace: d8-system
              
              namespace: documentation-storage
              
          • settings.moduleStorage.s3.external.size
            string

            How much of the bucket the module may take under the prefix. Above 80% of it the module deletes stored versions until 60% is left, in this order:

            1. Copies replaced after an update of the documentation template.
            2. Versions opened by readers.
            3. Versions used by the search.

            Within each group the versions stored longest ago go first.

            Default: 5Gi

            Pattern: ^[1-9][0-9]*(Mi|Gi|Ti)$

            Examples:

            size: 5Gi
            
            size: 20Gi
            
        • settings.moduleStorage.s3.type
          string
          • Disabled — only in the pod: after a restart of the pod the versions are prepared again when opened. In the high availability mode each replica prepares and keeps the versions on its own, with twice the CPU and the requests to the registry; turn S3 on for that mode.
          • System — also in the system S3 storage of the system-s3 module: after a restart of the pod the versions open from it in a fraction of a second. The module creates a 5 GiB bucket for it. Requires the system-s3 module to be enabled: without it the versions are kept in the pod only, and the D8DocumentationSystemS3Disabled alert fires.
          • External — also in an S3 storage of your own, set in the external section.

          Default: Disabled

          Allowed values: Disabled, System, External

    • settings.nodeSelector
      object

      Same as in the pods’ spec.nodeSelector parameter in Kubernetes.

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

      Example:

      nodeSelector:
        disktype: ssd
      
    • settings.tolerations
      array of objects

      Same as in the pods’ spec.tolerations parameter in Kubernetes;

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

      Example:

      tolerations:
      - key: key1
        operator: Equal
        value: value1
        effect: NoSchedule
      
      • settings.tolerations.effect
        string
      • settings.tolerations.key
        string
      • settings.tolerations.operator
        string
      • settings.tolerations.tolerationSeconds
        integer
      • settings.tolerations.value
        string