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

How to explicitly enable the module…

Set the spec.enabled module parameter to true or false in the ModuleConfig/user-authn resource (create it, if necessary) to explicitly enable or disable the module, or use the deckhouse-controller module command in the d8-system/deckhouse pod.

Example of enabling the module:

  • by using the ModuleConfig resource:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: user-authn
    spec:
      enabled: true
    
  • by using the deckhouse-controller command (you need a kubectl, configured to work with the cluster):

    kubectl -ti -n d8-system exec deploy/deckhouse -c deckhouse -- deckhouse-controller module enable user-authn
    

Example of disabling the module:

  • by using the ModuleConfig resource:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: user-authn
    spec:
      enabled: false
    
  • by using the deckhouse-controller command (you need a kubectl, configured to work with the cluster):

    kubectl -ti -n d8-system exec deploy/deckhouse -c deckhouse -- deckhouse-controller module disable user-authn
    

The module is configured using the ModuleConfig custom resource named user-authn (learn more about setting up Deckhouse…).

Example of the ModuleConfig/user-authn resource for configuring the module:

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

Parameters

Schema version: 1

  • controlPlaneConfiguratorobject

    Parameters of the control-plane-manager module.

    • controlPlaneConfigurator.dexCAModestring

      How to determine the CA that will be used when configuring kube-apiserver.

      • Custom — use the CA explicitly set via the dexCustomCA parameter (see below). This option comes in handy if you use an external HTTPS load balancer in front of Ingresses, and this load balancer relies on a self-signed certificate.
      • DoNotNeed — a CA is not required (e.g., when using a public LE or other TLS providers).
      • FromIngressSecret — extract the CA of certificate from the Secret that is used in the Ingress. This option comes in handy if you use self-signed certificates with Ingresses.

      Default: "DoNotNeed"

      Allowed values: Custom, DoNotNeed, FromIngressSecret

    • controlPlaneConfigurator.dexCustomCAstring

      The CA to use if dexCAMode is Custom. Plain text (no base64).

    • controlPlaneConfigurator.enabledboolean

      Defines if the control-plane-manager module should be used to configure OIDC for the kube-apiserver.

      Default: true

  • highAvailabilityboolean

    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.

    Examples:

    highAvailability: true
    
    highAvailability: false
    
  • httpsobject

    What certificate type to use with Dex/kubeconfig-generator.

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

    Examples:

    https:
      mode: CustomCertificate
      customCertificate:
        secretName: foobar
    
    https:
      mode: CertManager
      certManager:
        clusterIssuerName: letsencrypt
    
    • https.certManagerobject
      • https.certManager.clusterIssuerNamestring

        What ClusterIssuer to use for Dex/kubeconfig-generator.

        Currently, letsencrypt, letsencrypt-staging, selfsigned are available. Also, you can define your own.

        Default: "letsencrypt"

    • https.customCertificateobject
      • https.customCertificate.secretNamestring

        The name of the Secret in the d8-system namespace to use with Dex/kubeconfig-generator.

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

        Default: "false"

    • https.modestring

      The HTTPS usage mode:

      • CertManager — Dex/kubeconfig-generator will use HTTPS and get a certificate from the ClusterIssuer defined in the certManager.clusterIssuerName parameter.
      • CustomCertificate — Dex/kubeconfig-generator will use HTTPS using the certificate from the d8-system namespace.
      • Disabled — Dex/kubeconfig-generator will work over HTTP only;
      • OnlyInURI — Dex/kubeconfig-generator will work over HTTP (thinking that there is an external HTTPS load balancer in front that terminates HTTPS traffic). All the links in the user-authn will be generated using the HTTPS scheme. Load balancer should provide a redirect from HTTP to HTTPS.

      Default: "Disabled"

      Allowed values: Disabled, CertManager, CustomCertificate, OnlyInURI

  • idTokenTTLstring

    The TTL of the id token (use s for seconds, m for minutes, h for hours).

    It is specified as a string containing the time unit in hours, minutes and seconds: 30m, 20s, 2h30m10s, 24h.

    Default: "10m"

    Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

  • ingressClassstring

    The class of the Ingress controller that will be used for Dex/kubeconfig-generator.

    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])?)*$

  • kubeconfigGeneratorarray of objects

    An array in which additional possible methods for accessing the API server are specified.

    This option comes in handy if you prefer not to grant access to the cluster’s API via Ingress but rather do it by other means (e.g., using a bastion host or over OpenVPN).

    • kubeconfigGenerator.descriptionstring

      A couple of words how this authentication method differs from others.

    • kubeconfigGenerator.idstring

      Required value

      The name of the method for accessing the API server (no spaces, lowercase letters).

      Pattern: ^[\@\.\:0-9a-z._-]+$

    • kubeconfigGenerator.masterCAstring

      A CA for accessing the API:

      • If the parameter is not set, Kubernetes CA is used.
      • We recommend using a self-signed certificate (and specify it as masterCA) if an HTTP proxy (that terminates HTTPS traffic) is used for exposing.
    • kubeconfigGenerator.masterURIstring

      Required value

      If you plan to use a TCP proxy, then you must configure a certificate on the API server’s side for the TCP proxy address. Suppose your API servers use three different addresses (192.168.0.10, 192.168.0.11, and 192.168.0.12) while the client uses a TCP load balancer (say, 192.168.0.15). In this case, you have to re-generate the API server certificates:

      • edit kubeadm-config: kubectl -n kube-system edit configmap kubeadm-config and add 192.168.0.15 to .apiServer.certSANs;
      • save the resulting config: kubeadm config view > kubeadmconf.yaml;
      • delete old API server certificates: mv /etc/kubernetes/pki/apiserver.* /tmp/;
      • reissue new certificates: kubeadm init phase certs apiserver --config=kubeadmconf.yaml;
      • restart the API server’s container: docker ps -a | grep 'kube-apiserver' | grep -v pause| awk '{print $1}' | xargs docker restart;
      • repeat this step for all master nodes.
  • nodeSelectorobject

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

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

  • publishAPIobject

    Settings for exposing the API server using Ingress.

    • publishAPI.enableboolean

      Setting it to true will create an Ingress resource in the d8-user-authn namespace in the cluster (it exposes the Kubernetes API).

      Default: false

    • publishAPI.httpsobject

      The HTTPS mode for the API server Ingress.

      Examples:

      https:
        mode: SelfSigned
      
      https:
        mode: Global
        global:
          kubeconfigGeneratorMasterCA: plainstring
      
      • publishAPI.https.globalobject

        An additional parameter for the Global mode.

        • publishAPI.https.global.kubeconfigGeneratorMasterCAstring

          If there is an external load balancer in front of the Ingress that terminates HTTPS traffic using non-public CA, then you need to specify the CA so it will be included in kubectl-config.

          If you are using certificates issued by the cert-manager module and Let’s Encrypt in your cluster, you should set an empty string "" as the value.

          Also, you can set the external LB’s certificate itself as a CA if you can’t get the CA that signed it for some reason. Note that after the certificate is updated on the LB, all the previously generated kubeconfigs will stop working.

      • publishAPI.https.modestring

        The mode of issuing certificates for the Ingress resource.

        In the SelfSigned mode, a CA-signed certificate will be issued for the Ingress resource.

        Use the following command to get the certificate: kubectl -n d8-user-authn get secrets kubernetes-api-ca-key-pair -oyaml.

        In the Global mode, the policies specified in the global.modules.https.mode global parameter will be applied. Thus, if the global parameter has the CertManager mode set (with letsencrypt as the ClusterIssuer), then the Let’s Encrypt certificate will be issued for the Ingress resource.

        Default: "SelfSigned"

        Allowed values: SelfSigned, Global

    • publishAPI.ingressClassstring

      The Ingress class that will be used to expose the Kubernetes API via Ingress.

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

    • publishAPI.whitelistSourceRangesarray of strings

      An array of CIDRs that are allowed to connect to the API server.

      • Element of the arraystring

        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]))?$

  • tolerationsarray of objects

    The 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
    
    • tolerations.effectstring
    • tolerations.keystring
    • tolerations.operatorstring
    • tolerations.tolerationSecondsinteger
    • tolerations.valuestring

The creation of the DexAuthenticator Custom Resource leads to the automatic deployment of oauth2-proxy to your application’s namespace and connecting it to Dex.

Caution! Since using OpenID Connect over HTTP poses a significant threat to security (the fact that Kubernetes API server doesn’t support OICD over HTTP confirms that), this module can only be installed if HTTPS is enabled (to do this, set the https.mode parameter to the value other than Disabled either at the cluster level or in the module).

Caution! When this module is enabled, authentication in all web interfaces will be switched from HTTP Basic Auth to Dex (the latter, in turn, will use the external providers that you have defined). To configure kubectl, go to https://kubeconfig.<modules.publicDomainTemplate>/, log in to your external provider’s account and copy the shell commands to your console.

Caution! The API server requires additional configuration to use authentication for dashboard and kubectl. The control-plane-manager module (enabled by default) automates this process.