Role-Based Access Control

In Kubernetes, role-based access control (RBAC) regulates access to cluster resources. This page describes how to configure both the Appian operator Helm chart and Appian custom resources to customize Kubernetes RBAC to account for a variety of use cases. It is aimed at self-managed customers running Appian on Kubernetes.

Restrict cluster-wide access

By default, the Appian operator should be installed once per cluster into the appian-operator namespace. In this mode, both the operator's webhooks and controllers are configured to run in the appian-operator namespace and the controllers are configured to reconcile Appian custom resources across the entire cluster. Specifically, the Appian operator Helm chart deploys a ClusterRole and ClusterRoleBinding so that the operator can reconcile custom resources across all namespaces.

When cluster-wide access is undesirable, you can restrict the operator's controllers to the appian-operator namespace only. If you want to create Appian custom resources in other namespaces, you can also install the operator's controllers in each of those namespaces.

Restrict to one namespace

To restrict the operator's controllers to the appian-operator namespace, set controllers.rbac.clusterWideAccess to false when installing the chart:

1
2
3
4
5
helm --namespace appian-operator install appian-operator-<APPIAN_OPERATOR_VERSION>.tgz \
  --set image.repository=<REGISTRY_HOSTNAME>/appian/appian-operator:<APPIAN_OPERATOR_VERSION> \
  --set controllers.rbac.clusterWideAccess=false \
  ... \
  --wait

Expand to additional namespaces

To install the operator's controllers in a namespace where you want to create Appian custom resources, install the operator in each target namespace with controllers.rbac.clusterWideAccess, rbac.aggregatedClusterRoles.enabled, and webhooks.enabled set to false:

1
2
3
4
5
6
7
helm --namespace <NAMESPACE> install appian-operator-<APPIAN_OPERATOR_VERSION>.tgz \
  --set image.repository=<REGISTRY_HOSTNAME>/appian/appian-operator:<APPIAN_OPERATOR_VERSION> \
  --set controllers.rbac.clusterWideAccess=false \
  --set rbac.aggregatedClusterRoles.enabled=false \
  --set webhooks.enabled=false \
  ... \
  --wait

Disable aggregated cluster roles

By default, the Appian operator Helm chart deploys ClusterRoles that aggregate to the built-in view, edit, and admin ClusterRoles. Aggregation enables principals with those roles to interact with Appian custom resources.

To disable this feature, set rbac.aggregatedClusterRoles.enabled to false when installing the chart.

Bind custom roles to Appian

Both the Appian operator Helm chart and Appian CRD support binding the operator and Appian, respectively, to arbitrary roles and cluster roles. This is particularly useful when you need to make either the Appian operator or Appian use a specific pod security policy (PSP).

Bind a PSP to the Appian operator

Imagine that you need to configure the Appian operator to use a PSP that you've created called my-psp. First, define either a ClusterRole or Role that authorizes use of your PSP by creating a file named use-my-psp.yaml with the following content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
apiVersion: rbac.authorization.k8s.io/v1
# Use Role instead of ClusterRole if you'd like to disallow bindings across the entire cluster
kind: ClusterRole
metadata:
  name: use-my-psp
rules:
- apiGroups:
  - policy
  resources:
  - podsecuritypolicies
  verbs:
  - use
  resourceNames:
  - my-psp

Then, create the ClusterRole or Role. Use kubectl create for new resources, or kubectl apply to update an existing one:

1
kubectl create -f use-my-psp.yaml

1
kubectl apply -f use-my-psp.yaml

If you defined a Role instead of a ClusterRole, make sure to include the --namespace/-n flag to specify the namespace in which you've installed, or will install, the Appian operator Helm chart.

Finally, pass the name of the ClusterRole or Role, use-my-psp, via the appropriate property when installing or upgrading the chart:

The chart includes a RoleBinding that binds the use-my-psp ClusterRole or Role to one of the operator's service accounts.

You can check that the operator's controller and/or webhook pod(s) are using the my-psp PSP by checking the value of their kubernetes.io/psp annotation:

1
kubectl -n <NAMESPACE> get pod <POD> -ojsonpath={.metadata.annotations.'kubernetes\.io/psp'}

Bind a PSP to Appian

Now imagine that you need to configure Appian to use a PSP that you've created called my-psp. First, follow the steps for binding a PSP to the Appian operator to define and create either a ClusterRole or Role that authorizes use of your PSP. If you defined a Role instead of a ClusterRole, make sure to include the --namespace/-n flag when running kubectl create or kubectl apply to specify the namespace in which you've created or will create the Appian custom resource.

The Appian operator and Appian CRD support binding Appian to existing ClusterRoles and Roles via the .spec.rbac.clusterRoles and .spec.rbac.roles fields, respectively, on Appian custom resources. When specified, the fields instruct the operator to create one or more RoleBinding resources that bind the provided ClusterRole(s) and/or Role(s) to the service account associated with the custom resource.

The operator lacks access to do so by default. When installing or upgrading the Appian operator chart, pass the name(s) of the ClusterRole(s) and/or Role(s) to which you want any Appian sites to be bound via .controllers.rbac.bind.clusterRoles and/or controllers.rbac.bind.roles. The chart includes a rule that allows the operator to bind to the provided ClusterRole(s) and/or Role(s).

Therefore, to allow the operator to bind to the use-my-psp ClusterRole or Role, pass use-my-psp via either controllers.rbac.bind.clusterRoles or controllers.rbac.bind.roles when installing or upgrading the chart.

Now, you're ready to create the Appian custom resource. Add the appropriate .spec.rbac fields to your Appian CR configuration file:

1
2
3
4
5
6
7
8
9
apiVersion: crd.k8s.appian.com/v1beta1
kind: Appian
metadata:
  name: appian
spec:
  rbac:
    # Use roles instead of clusterRoles if you defined a Role instead of a ClusterRole
    clusterRoles:
    - use-my-psp

Finally, use kubectl create for new resources, or kubectl apply to update an existing one:

1
kubectl -n <NAMESPACE> create -f appian.yaml

1
kubectl -n <NAMESPACE> apply -f appian.yaml

If you defined a Role instead of a ClusterRole, make sure <NAMESPACE> matches the namespace in which you created the Role.

You can check that the pods associated with the custom resource are using the my-psp PSP by checking the value of their kubernetes.io/psp annotation:

1
kubectl -n <NAMESPACE> get pod <POD> -ojsonpath={.metadata.annotations.'kubernetes\.io/psp'}

Feedback