Skip to main content

Configuring KOTS RBAC

This topic describes role-based access control (RBAC) for Replicated KOTS in existing cluster installations. It includes information about how to change the default cluster-scoped RBAC permissions granted to KOTS.

About Cluster-scoped RBAC​

When a user installs your application in an existing cluster, Kubernetes RBAC resources are created to allow KOTS to install and manage the application.

By default, the following ClusterRole and ClusterRoleBinding resources are created that grant KOTS access to all resources across all namespaces in the cluster:

apiVersion: "rbac.authorization.k8s.io/v1"
kind: "ClusterRole"
metadata:
  name: "kotsadm-role"
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kotsadm-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kotsadm-role
subjects:
- kind: ServiceAccount
  name: kotsadm
  namespace: appnamespace

Alternatively, if your application does not require access to resources across all namespaces in the cluster, then you can enable namespace-scoped RBAC for KOTS. For information, see About Namespace-scoped RBAC below.

About Namespace-scoped RBAC​

Rather that use the default cluster-scoped RBAC, you can configure your application so that the RBAC permissions granted to KOTS are limited to a target namespace or namespaces.

Namespace-scoped RBAC is supported for applications that use Kubernetes Operators or multiple namespaces. During application installation, if there are additionalNamespaces specified in the Application custom resource manifest file, then Roles and RoleBindings are created to grant KOTS access to resources in all specified namespaces.

By default, for namespace-scoped installations, the following Role and RoleBinding resources are created that grant KOTS permissions to all resources in a target namespace:

apiVersion: "rbac.authorization.k8s.io/v1"
kind: "Role"
metadata:
  name: "kotsadm-role"
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kotsadm-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kotsadm-role
subjects:
- kind: ServiceAccount
  name: kotsadm
  namespace: appnamespace

For information about how to enable namespace-scoped RBAC for your application, see Enable Namespace-scoped RBAC below.

Enable Namespace-scoped RBAC​

To enable namespace-scoped RBAC permissions for KOTS, specify one of the following options in the Application custom resource manifest file:

  • supportMinimalRBACPrivileges: Set to true to make namespace-scoped RBAC optional for existing cluster installations. When supportMinimalRBACPrivileges is true, cluster-scoped RBAC is used by default and users must pass the --use-minimal-rbac flag with the installation or upgrade command to use namespace-scoped RBAC.

  • requireMinimalRBACPrivileges: Set to true to require that all installations to existing clusters use namespace-scoped access. When requireMinimalRBACPrivileges is true, all installations use namespace-scoped RBAC automatically and users do not pass the --use-minimal-rbac flag.

For more information about these options, see requireMinimalRBACPrivileges and supportMinimalRBACPrivileges in Application.

For information about limitations that apply to using namespace-scoped access, see Limitations below.

Limitations​

The following limitations apply when using the requireMinimalRBACPrivileges or supportMinimalRBACPrivileges options to enable namespace-scoped RBAC for KOTS:

  • Existing clusters only: The requireMinimalRBACPrivileges and supportMinimalRBACPrivileges options apply only to installations in existing clusters.

  • Preflight checks: When namespace-scoped access is enabled, preflight checks cannot read resources outside the namespace where KOTS is installed. The preflight checks continue to function, but return less data. For more information, see Define KOTS Preflight Checks.

  • Velero namespace access: Namespace-scoped RBAC does not grant access to the namespace where Velero is installed in the cluster. Velero is a requirement for configuring backup and restore with snapshots.

    To set up snapshots when KOTS has namespace-scoped access, users can run the kubectl kots velero ensure-permissions command. This command creates additional Roles and RoleBindings to allow the necessary cross-namespace access. For more information, see velero ensure-permissions in the kots CLI documentation.

    For more information about snapshots, see About Backup and Restore.

  • Air Gap Installations: For air gap installations, the requireMinimalRBACPrivileges and supportMinimalRBACPrivileges flags are supported only in automated, or headless, installations. In headless installations, the user passes all the required information to install both KOTS and the application with the kots install command. In non-headless installations, the user provides information to install the application through the admin console UI after KOTS is installed.

    In non-headless installations in air gap environments, KOTS does not have access to the application's .airgap package during installation. This means that KOTS does not have the information required to determine whether namespace-scoped access is needed, so it defaults to the more permissive, default cluster-scoped RBAC policy.

    For more information about how to do headless installations in air gap environments, see Installing in an Air Gap Environment in Using Automation to Install in an Existing Cluster.

  • Changing RBAC permissions for installed instances: The RBAC permissions for KOTS are set during its initial installation. KOTS runs using the assumed identity and cannot change its own authorization. When you update your application to add or remove the requireMinimalRBACPrivileges and supportMinimalRBACPrivileges flags in the Application custom resource, the RBAC permissions for KOTS are affected only for new installations. Existing KOTS installations continue to run with their current RBAC permissions.

    To expand the scope of RBAC for KOTS from namespace-scoped to cluster-scoped in new installations, Replicated recommends that you include a preflight check to ensure the permission is available in the cluster.