The module has 1 alert.
The module is enabled by default in the Default
bundle.
The module is disabled by default in the following bundles: Managed
, Minimal
.
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: 2
enabled: true
settings: # <-- Module parameters from the "Parameters" section below.
Parameters
Schema version: 2
- controlPlaneConfigurator.dexCAMode
How to determine the CA that will be used when configuring
kube-apiserver
.Custom
— use the CA explicitly set via thedexCustomCA
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.dexCustomCA
The CA to use if
dexCAMode
isCustom
. Plain text (no base64). - controlPlaneConfigurator.enabled
Defines if the
control-plane-manager
module should be used to configure OIDC for thekube-apiserver
.Default:
true
- highAvailability
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
- https
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.certManager
- https.certManager.clusterIssuerName
What ClusterIssuer to use for Dex/kubeconfig-generator.
Currently,
letsencrypt
,letsencrypt-staging
,selfsigned
are available. Also, you can define your own.Default:
"letsencrypt"
- https.customCertificate
- https.customCertificate.secretName
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.mode
The HTTPS usage mode:
CertManager
— Dex/kubeconfig-generator will use HTTPS and get a certificate from the ClusterIssuer defined in thecertManager.clusterIssuerName
parameter.CustomCertificate
— Dex/kubeconfig-generator will use HTTPS using the certificate from thed8-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 theuser-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
- idTokenTTL
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)?$
- ingressClass
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])?)*$
- kubeconfigGenerator
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.description
A couple of words how this authentication method differs from others.
- kubeconfigGenerator.id
Required value
The name of the method for accessing the API server (no spaces, lowercase letters).
Pattern:
^[\@\.\:0-9a-z._-]+$
- kubeconfigGenerator.masterCA
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.masterURI
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
, and192.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 add192.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.
- edit
- nodeSelector
The same as in the Pods’
spec.nodeSelector
parameter in Kubernetes.If the parameter is omitted or
false
, it will be determined automatically. - publishAPI
Settings for exposing the API server using Ingress.
- publishAPI.addKubeconfigGeneratorEntry
Setting it to
false
will remove an entry in kubeconfig-generator.Default:
true
- publishAPI.enabled
Setting it to
true
will create an Ingress resource in thed8-user-authn
namespace in the cluster (it exposes the Kubernetes API).Default:
false
- publishAPI.https
The HTTPS mode for the API server Ingress.
Examples:
https: mode: SelfSigned
https: mode: Global global: kubeconfigGeneratorMasterCA: plainstring
- publishAPI.https.global
An additional parameter for the
Global
mode.- publishAPI.https.global.kubeconfigGeneratorMasterCA
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.mode
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 theglobal.modules.https.mode
global parameter will be applied. Thus, if the global parameter has theCertManager
mode set (withletsencrypt
as the ClusterIssuer), then the Let’s Encrypt certificate will be issued for the Ingress resource.Default:
"SelfSigned"
Allowed values:
SelfSigned
,Global
- publishAPI.ingressClass
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.whitelistSourceRanges
An array of CIDRs that are allowed to connect to the API server.
- Element of the array
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]))?$
- tolerations
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.effect
- tolerations.key
- tolerations.operator
- tolerations.tolerationSeconds
- tolerations.value
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.