Skip to content

Identity And Authorization Management#

Identity and authorization are core to operating multi-cluster environments, and Mirantis k0rdent Enterprise now provides a consistent way to manage them through the ClusterAuthentication resource. This mechanism lets you define how each child cluster validates user requests, using standard Kubernetes authentication configuration while supporting multiple JWT issuers, custom claim mappings, and custom certificate authorities. By separating authentication policy from cluster templates and automating its propagation into hosted control planes, Mirantis k0rdent Enterprise removes error-prone manual steps and gives you a repeatable, auditable way to enforce identity across your fleet.

ClusterAuthentication Resource#

Mirantis k0rdent Enterprise supports configuring identity and authorization management (IAM) for child clusters through the ClusterAuthentication custom resource. A ClusterAuthentication object defines how the Kubernetes API server authenticates incoming requests. It supports multiple JWT authenticators, each configurable with an issuer URL, claim mappings, certificate authorities, and more.

Consider this example:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterAuthentication
metadata:
  name: dex-cluster-auth
  namespace: my-namespace
spec:
  authenticationConfiguration:
    jwt:
      - issuer:
          url: https://dex.example.com:5556
          audiences:
            - example-app
        claimMappings:
          username:
            claim: email
            prefix: ""
          groups:
            claim: groups
            prefix: ""
        userValidationRules:
          - expression: "!user.username.startsWith('system:')"
            message: "username cannot use reserved system: prefix"
  caSecret:
    name: dex-ca-secret
    namespace: kcm-system
    key: ca.crt

Important fields to consider include:

  • spec.authenticationConfiguration

This field includes the spec of the AuthenticationConfiguration object used by the API server. For all available configuration options, see the official Kubernetes documentation: Authentication configuration from a file.

  • spec.caSecret Contains the spec of the AuthenticationConfiguration object consumed by the Kubernetes API server. For all supported options, see the official Kubernetes documentation: Authentication configuration from a file.

This field references a Kubernetes Secret that contains one or more CA certificates for the JWT issuer endpoint. (Make sure you've already created the Secret before you start!) If the issuer uses a custom or self-signed CA, the certificate must be provided here so the API server can trust the issuer. The CA value is injected into the AuthenticationConfiguration under jwt.issuer[*].certificateAuthority.

Configuring Authentication for ClusterDeployments#

Now let's look at how to make this work in practice. To enable authentication for a ClusterDeployment, set the spec.clusterAuth field to the name of an existing ClusterAuthentication object in the same namespace. For example:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: cluster-name
  namespace: my-namespace
spec:
  template: openstack-hosted-cp-1-0-12
  credential: openstack-cluster-identity-cred
  clusterAuth: dex-cluster-auth

Note

ClusterAuthentication objects can be distributed across namespaces using the AccessManagement resource. See Access Management Resource for details.

Integration with ClusterTemplates#

When spec.clusterAuth is configured in the ClusterDeployment and the referenced ClusterAuthentication exists, the Mirantis k0rdent Enterprise KCM controller performs the following:

  1. Generates a Secret named <cluster-deployment-name>-auth-config that contains the merged AuthenticationConfiguration (including injected CA certificates).

  2. Passes required authentication values to the HelmRelease responsible for deploying the cluster:

    auth:
      configSecret:
        name: cluster-name-auth-config
        key: config
        hash: 3f7b8627
  • auth.configSecret.name - Name of the Secret containing the authentication config.
  • auth.configSecret.key - Key within the Secret where the configuration is stored.
  • auth.configSecret.hash - Hash of the configuration content; used to trigger control plane updates when changed.

The ClusterTemplate must consume these values to configure the API server correctly. If you're using built-in templates, this isn't a problem; Mirantis k0rdent Enterprise includes this information already. However, if you're creating custom ClusterTemplates you will need to make sure this information is referenced in your assets. In particular, the control plane resources (K0smotronControlPlane or K0sControlPlane) must:

The ClusterTemplate must consume these values to configure the API server correctly. Built-in templates already reference this information.

If you are creating custom ClusterTemplates, you must explicitly reference these values. In particular, the control plane resources (K0smotronControlPlane or K0sControlPlane) must:

  1. Mount the authentication Secret into control plane nodes or pods.
  2. Set the API server --authentication-configuration flag to the mounted configuration file.

Warning

Updating spec.clusterAuth changes the configuration hash and triggers a rolling recreation of control plane machines. For clusters that were initially deployed with a single control plane node, this operation may cause the cluster to lose etcd quorum during the rollout, potentially resulting in a cluster outage. For mitigation steps and additional details, see Cluster Control Plane Rollout.

Example: K0smotronControlPlane Authentication Configuration#

spec:
  k0sConfig:
    apiVersion: k0s.k0sproject.io/v1beta1
    kind: ClusterConfig
    metadata:
      name: k0s
    spec:
      mounts:
      {{- if .Values.auth.configSecret.name }}
      - path: /var/lib/k0s/auth
        secret:
          defaultMode: 420
          items:
            - key: {{ .Values.auth.configSecret.key }}
              path: config-{{ .Values.auth.configSecret.hash }}.yaml
          secretName: {{ .Values.auth.configSecret.name }}
      {{- end }}
      ...
      api:
        extraArgs:
          {{- if .Values.auth.configSecret.name }}
          authentication-config: /var/lib/k0s/auth/config-{{ .Values.auth.configSecret.hash }}.yaml
          {{- end }}
      ...

Example: K0sControlPlane Authentication Configuration#

spec:
  k0sConfigSpec:
    {{- if .Values.auth.configSecret.name }}
    files:
    - contentFrom:
        secretRef:
          name: {{ .Values.auth.configSecret.name }}
          key: {{ default "config" .Values.auth.configSecret.key }}
      permissions: "0644"
      path: /var/lib/k0s/auth/config-{{ .Values.auth.configSecret.hash }}.yaml
    {{- end }}
    ...
    k0s:
      apiVersion: k0s.k0sproject.io/v1beta1
      kind: ClusterConfig
      metadata:
        name: k0s
      spec:
        api:
          extraArgs:
            {{- if .Values.auth.configSecret.name }}
            authentication-config: /var/lib/k0s/auth/config-{{ .Values.auth.configSecret.hash }}.yaml
            {{- end }}
     ...

Warning

If spec.clusterAuth is updated with a different configuration, the hash value will change. This triggers a rolling recreation of the control plane machines.