wip

Signed-off-by: Massimiliano Giovagnoli <me@maxgio.it>

.github/maintainers.yaml

@@ -0,0 +1,18 @@
+- name: Adriano Pezzuto
+  github: https://github.com/bsctl
+  company: Clastix
+  projects:
+    - https://github.com/clastix/capsule
+    - https://github.com/clastix/capsule-proxy
+- name: Dario Tranchitella
+  github: https://github.com/prometherion
+  company: Clastix
+  projects:
+    - https://github.com/clastix/capsule
+    - https://github.com/clastix/capsule-proxy
+- name: Maksim Fedotov
+  github: https://github.com/MaxFedotov
+  company: wargaming.net
+  projects:
+    - https://github.com/clastix/capsule
+    - https://github.com/clastix/capsule-proxy

.github/workflows/gosec.yml

@@ -0,0 +1,18 @@
+name: CI gosec
+on:
+  push:
+    branches: [ "*" ]
+  pull_request:
+    branches: [ "*" ]
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    env:
+      GO111MODULE: on
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@v2
+      - name: Run Gosec Security Scanner
+        uses: securego/gosec@master
+        with:
+          args: ./...

ADOPTERS.md

@@ -0,0 +1,5 @@
+# Adopters
+
+This is a list of companies that have adopted Capsule, feel free to open a Pull-Request to get yours listed.
+
+## Adopters list (alphabetically)

README.md

@@ -84,10 +84,18 @@ bash scripts/helm-docs.sh
 
 Join the community, share and learn from it. You can find all the resources to how to contribute code and docs, connect with people in the [community repository](https://github.com/clastix/capsule-community).
 
+## Adopters
+
+See the [ADOPTERS.md](ADOPTERS.md) file for a list of companies that are using Capsule.
+
 # Governance
 
 You can find how the Capsule project is governed [here](https://capsule.clastix.io/docs/contributing/governance).
 
+## Maintainers
+
+Please, refer to the maintainers file available [here](.github/maintainers.yaml).
+
 # FAQ
 
 - Q. How to pronounce Capsule?

api/v1beta1/owner_role.go

@@ -38,7 +38,33 @@ func (in OwnerSpec) GetRoles(tenant Tenant, index int) []string {
 		}
 	}
 
-	return []string{"admin", "capsule-namespace-deleter"}
+	roles := []string{"admin", "capsule-namespace-deleter"}
+
+	if tenant.Spec.GitOpsReady {
+		roles = append(roles, in.getGitOpsRoles(tenant)...)
+	}
+
+	return roles
+}
+
+func (in OwnerSpec) GetClusterRoles(tenant Tenant) []string {
+	if tenant.Spec.GitOpsReady {
+		return in.getGitOpsClusterRoles(tenant)
+	}
+
+	return []string{}
+}
+
+func (in OwnerSpec) getGitOpsClusterRoles(tenant Tenant) []string {
+	return []string{
+		"capsule-tenant-impersonator-" + tenant.Name + "-" + in.Name,
+	}
+}
+
+func (in OwnerSpec) getGitOpsRoles(tenant Tenant) []string {
+	return []string{
+		"cluster-admin",
+	}
 }
 
 func (in OwnerSpec) convertMap() map[string]string {

api/v1beta1/tenant_labels.go

@@ -24,6 +24,8 @@ func GetTypeLabel(t runtime.Object) (label string, err error) {
 		return "capsule.clastix.io/resource-quota", nil
 	case *rbacv1.RoleBinding:
 		return "capsule.clastix.io/role-binding", nil
+	case *rbacv1.ClusterRoleBinding:
+		return "capsule.clastix.io/cluster-role-binding", nil
 	default:
 		err = fmt.Errorf("type %T is not mapped as Capsule label recognized", v)
 	}

api/v1beta1/tenant_types.go

@@ -35,6 +35,8 @@ type TenantSpec struct {
 	ImagePullPolicies []ImagePullPolicySpec `json:"imagePullPolicies,omitempty"`
 	// Specifies the allowed priorityClasses assigned to the Tenant. Capsule assures that all Pods resources created in the Tenant can use only one of the allowed PriorityClasses. Optional.
 	PriorityClasses *AllowedListSpec `json:"priorityClasses,omitempty"`
+	// Configured RBAC for machine owners tailored for GitOps controllers.
+	GitOpsReady bool `json:"gitOpsReady,omitempty"`
 }
 
 //+kubebuilder:object:root=true

config/crd/bases/capsule.clastix.io_tenants.yaml

@@ -654,6 +654,9 @@ spec:
                   allowedRegex:
                     type: string
                 type: object
+              gitOpsReady:
+                description: Configured RBAC for machine owners tailored for GitOps controllers.
+                type: boolean
               imagePullPolicies:
                 description: Specify the allowed values for the imagePullPolicies option in Pod resources. Capsule assures that all Pod resources created in the Tenant can use only one of the allowed policy. Optional.
                 items:

controllers/tenant/clusterrolebindings.go

@@ -0,0 +1,119 @@
+package tenant
+
+import (
+	"context"
+	"fmt"
+	"hash/fnv"
+
+	"golang.org/x/sync/errgroup"
+	rbacv1 "k8s.io/api/rbac/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+
+	capsulev1beta1 "github.com/clastix/capsule/api/v1beta1"
+)
+
+// Sync the dynamic Tenant Owner specific cluster-roles and additional ClusterRole Bindings, which can be used in many ways:
+// applying Pod Security Policies or giving access to CRDs or specific API groups.
+func (r *Manager) syncClusterRoleBindings(ctx context.Context, tenant *capsulev1beta1.Tenant) (err error) {
+	// hashing the ClusterRoleBinding name due to DNS RFC-1123 applied to Kubernetes labels
+	hashFn := func(binding capsulev1beta1.AdditionalRoleBindingsSpec) string {
+		h := fnv.New64a()
+
+		_, _ = h.Write([]byte(binding.ClusterRoleName))
+
+		for _, sub := range binding.Subjects {
+			_, _ = h.Write([]byte(sub.Kind + sub.Name))
+		}
+
+		return fmt.Sprintf("%x", h.Sum64())
+	}
+	// getting requested Role Binding keys
+	keys := make([]string, 0, len(tenant.Spec.Owners))
+	// Generating for dynamic tenant owners cluster roles
+	for _, owner := range tenant.Spec.Owners {
+		for _, clusterRoleName := range owner.GetClusterRoles(*tenant) {
+
+			cr := r.ownerClusterRoleBindings(owner, clusterRoleName)
+
+			keys = append(keys, hashFn(cr))
+		}
+	}
+
+	group := new(errgroup.Group)
+
+	group.Go(func() error {
+		return r.syncClusterRoleBinding(ctx, tenant, keys, hashFn)
+	})
+
+	return group.Wait()
+}
+
+func (r *Manager) syncClusterRoleBinding(ctx context.Context, tenant *capsulev1beta1.Tenant, keys []string, hashFn func(binding capsulev1beta1.AdditionalRoleBindingsSpec) string) (err error) {
+
+	var tenantLabel string
+
+	var clusterRoleBindingLabel string
+
+	if tenantLabel, err = capsulev1beta1.GetTypeLabel(&capsulev1beta1.Tenant{}); err != nil {
+		return
+	}
+
+	if clusterRoleBindingLabel, err = capsulev1beta1.GetTypeLabel(&rbacv1.ClusterRoleBinding{}); err != nil {
+		return
+	}
+
+	if err = r.pruningClusterResources(ctx, keys, &rbacv1.ClusterRoleBinding{}); err != nil {
+		return
+	}
+
+	var clusterRoleBindings []capsulev1beta1.AdditionalRoleBindingsSpec
+
+	for _, owner := range tenant.Spec.Owners {
+		for _, clusterRoleName := range owner.GetClusterRoles(*tenant) {
+			clusterRoleBindings = append(clusterRoleBindings, r.ownerClusterRoleBindings(owner, clusterRoleName))
+		}
+	}
+
+	for i, clusterRoleBinding := range clusterRoleBindings {
+
+		clusterRoleBindingHashLabel := hashFn(clusterRoleBinding)
+
+		target := &rbacv1.ClusterRoleBinding{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: fmt.Sprintf("capsule-%s-%d-%s", tenant.Name, i, clusterRoleBinding.ClusterRoleName),
+			},
+		}
+
+		var res controllerutil.OperationResult
+		res, err = controllerutil.CreateOrUpdate(ctx, r.Client, target, func() error {
+			target.ObjectMeta.Labels = map[string]string{
+				tenantLabel:             tenant.Name,
+				clusterRoleBindingLabel: clusterRoleBindingHashLabel,
+			}
+			target.RoleRef = rbacv1.RoleRef{
+				APIGroup: rbacv1.GroupName,
+				Kind:     "ClusterRole",
+				Name:     clusterRoleBinding.ClusterRoleName,
+			}
+			target.Subjects = clusterRoleBinding.Subjects
+
+			return controllerutil.SetControllerReference(tenant, target, r.Client.Scheme())
+		})
+
+		// TODO: find appropriate event Namespace.
+		r.emitEvent(tenant, target.GetNamespace(), res, fmt.Sprintf("Ensuring ClusterRoleBinding %s", target.GetName()), err)
+
+		if err != nil {
+			r.Log.Error(err, "Cannot sync ClusterRoleBinding")
+		}
+
+		r.Log.Info(fmt.Sprintf("ClusterRoleBinding sync result: %s", string(res)), "name", target.Name, "namespace", target.Namespace)
+
+		if err != nil {
+			return
+		}
+	}
+
+	return nil
+}

controllers/tenant/clusterroles.go

@@ -0,0 +1,66 @@
+package tenant
+
+import (
+	"context"
+
+	rbacv1 "k8s.io/api/rbac/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+
+	capsulev1beta1 "github.com/clastix/capsule/api/v1beta1"
+)
+
+const (
+	ImpersonatorRoleName = "capsule-tenant-impersonator"
+)
+
+// Sync the Tenant Owner specific cluster-roles.
+// When the Tenant is configured GitOpsReady additional (Cluster)Roles are created, then bound.
+func (r *Manager) syncClusterRoles(ctx context.Context, tenant *capsulev1beta1.Tenant) (err error) {
+
+	// If the Tenant will be reconciled the GitOps-way,
+	// Tenant Owners might be machine GitOps reconciler identities.
+	if tenant.Spec.GitOpsReady {
+		for _, owner := range tenant.Spec.Owners {
+			if err = r.ensureOwnerClusterRole(ctx, tenant, &owner, ImpersonatorRoleName); err != nil {
+				r.Log.Error(err, "Reconciliation for ClusterRole failed", "ClusterRole", ImpersonatorRoleName)
+				return err
+			}
+		}
+	}
+
+	return
+}
+
+func (r *Manager) ensureOwnerClusterRole(ctx context.Context, tenant *capsulev1beta1.Tenant, owner *capsulev1beta1.OwnerSpec, roleName string) (err error) {
+	switch roleName {
+	case ImpersonatorRoleName:
+		clusterRole := &rbacv1.ClusterRole{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: roleName + "-" + tenant.Name + "-" + owner.Name,
+			},
+		}
+
+		resource := "users"
+		if owner.Kind == capsulev1beta1.GroupOwner {
+			resource = "groups"
+		}
+
+		resourceName := owner.Name
+
+		_, err = controllerutil.CreateOrUpdate(ctx, r.Client, clusterRole, func() error {
+			clusterRole.Rules = []rbacv1.PolicyRule{
+				{
+					APIGroups:     []string{""},
+					Resources:     []string{resource},
+					Verbs:         []string{"impersonate"},
+					ResourceNames: []string{resourceName},
+				},
+			}
+
+			return nil
+		})
+	}
+
+	return
+}

controllers/tenant/manager.go

@@ -105,6 +105,22 @@ func (r Manager) Reconcile(ctx context.Context, request ctrl.Request) (result ct
 
 		return
 	}
+	// Ensuring ClusterRoles resources
+	r.Log.Info("Ensuring ClusterRoles for Owners and Tenant")
+
+	if err = r.syncClusterRoles(ctx, instance); err != nil {
+		r.Log.Error(err, "Cannot sync ClusterRoles items")
+
+		return
+	}
+	// Ensuring ClusterRoleBindings resources
+	r.Log.Info("Ensuring ClusterRoleBindings for Owners and Tenant")
+
+	if err = r.syncClusterRoleBindings(ctx, instance); err != nil {
+		r.Log.Error(err, "Cannot sync ClusterRoleBindings items")
+
+		return
+	}
 	// Ensuring RoleBinding resources
 	r.Log.Info("Ensuring RoleBindings for Owners and Tenant")
 

controllers/tenant/utils.go

@@ -14,6 +14,47 @@ import (
 	capsulev1beta1 "github.com/clastix/capsule/api/v1beta1"
 )
 
+// pruningClusterResources is taking care of removing the no more requested sub-resources as LimitRange, ResourceQuota or
+// NetworkPolicy using the "exists" and "notin" LabelSelector to perform an outer-join removal.
+func (r *Manager) pruningClusterResources(ctx context.Context, keys []string, obj client.Object) (err error) {
+	var capsuleLabel string
+
+	if capsuleLabel, err = capsulev1beta1.GetTypeLabel(obj); err != nil {
+		return
+	}
+
+	selector := labels.NewSelector()
+
+	var exists *labels.Requirement
+
+	if exists, err = labels.NewRequirement(capsuleLabel, selection.Exists, []string{}); err != nil {
+		return
+	}
+
+	selector = selector.Add(*exists)
+
+	if len(keys) > 0 {
+		var notIn *labels.Requirement
+
+		if notIn, err = labels.NewRequirement(capsuleLabel, selection.NotIn, keys); err != nil {
+			return err
+		}
+
+		selector = selector.Add(*notIn)
+	}
+
+	r.Log.Info("Pruning objects with label selector " + selector.String())
+
+	return retry.RetryOnConflict(retry.DefaultBackoff, func() error {
+		return r.DeleteAllOf(ctx, obj, &client.DeleteAllOfOptions{
+			ListOptions: client.ListOptions{
+				LabelSelector: selector,
+			},
+			DeleteOptions: client.DeleteOptions{},
+		})
+	})
+}
+
 // pruningResources is taking care of removing the no more requested sub-resources as LimitRange, ResourceQuota or
 // NetworkPolicy using the "exists" and "notin" LabelSelector to perform an outer-join removal.
 func (r *Manager) pruningResources(ctx context.Context, ns string, keys []string, obj client.Object) (err error) {

docs/content/contributing/governance.md

@@ -17,6 +17,8 @@ In the context of Capsule project, we consider the following roles:
 
 The release process will be governed by Maintainers.
 
+Please, refer to the [maintainers file](https://github.com/clastix/capsule/blob/master/.github/blob/master/maintainers.yaml) available in the source code.
+
 ## Roadmap Planning
 
 Maintainers will share roadmap and release versions as milestones in GitHub. 

docs/content/general/tutorial.md

@@ -2,108 +2,21 @@
 
 Capsule is a framework to implement multi-tenant and policy-driven scenarios in Kubernetes. In this tutorial, we'll focus on a hypothetical case covering the main features of the Capsule Operator.
 
-***Acme Corp***, our sample organization, is building a Container as a Service platform (CaaS) to serve multiple lines of business. Each line of business has its team of engineers that are responsible for the development, deployment, and operating of their digital products. We'll work with the following actors:
+***Acme Corp***, our sample organization, is building a Container as a Service platform (CaaS) to serve multiple lines of business, or departments, e.g. _Oil_, _Gas_, _Solar_, _Wind_, _Water_. Each department has its team of engineers that are responsible for the development, deployment, and operating of their digital products. We'll work with the following actors:
 
-* ***Bill***: the cluster administrator from the operations department of Acme Corp.
+* ***Bill***: the cluster administrator from the operations department of _Acme Corp_.
 
-* ***Alice***: the IT Project Leader in the Oil & Gas Business Units. She is responsible for a team made of different job responsibilities (developers, administrators, SRE engineers, etc.) working in separate multiple departments.
+* ***Alice***: the project leader in the _Oil_ & _Gas_ departments. She is responsible for a team made of different job responsibilities: e.g. developers, administrators, SRE engineers, etc.
   
-* ***Joe***:
-  He works at Acme Corp, as a lead developer of a distributed team in Alice's organization.
+* ***Joe***: works as a lead developer of a distributed team in Alice's organization.
 
-* ***Bob***:
-  He is the head of Engineering for the Water Business Unit, the main and historical line of business at Acme Corp.
+* ***Bob***: is the head of engineering for the _Water_ department, the main and historical line of business at _Acme Corp_.
 
 
 ## Assign Tenant ownership
 
-### Roles assigned to Tenant Owners
-
-By default, all Tenant Owners will be granted with two ClusterRole resources using the RoleBinding API:
-
-1. the Kubernetes default one, `admin`, that grants most of the Namespace scoped resources management operations
-2. a custom one, named `capsule-namespace-deleter`, allowing to delete the created Namespace
-
-In the example below, assuming Alice create a namespace `oil-production` in Tenant `oil`,getting the tenant owner's Alice default 
-ClusterRoles command:
-
-```
-$: kubectl get rolebindings.rbac.authorization.k8s.io -n oil-production
-NAME                                      ROLE                                    AGE
-capsule-oil-0-admin                       ClusterRole/admin                       6s
-capsule-oil-1-capsule-namespace-deleter   ClusterRole/capsule-namespace-deleter   5s
-capsule-oil-2-admin                       ClusterRole/admin                       5s
-capsule-oil-3-capsule-namespace-deleter   ClusterRole/capsule-namespace-deleter   5s
-```
-
-Capsule supports the dynamic management of the assigned ClusterRole resources for each Tenant Owner.
-
-```yaml
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  annotations:
-    clusterrolenames.capsule.clastix.io/user.alice: editor,manager
-    clusterrolenames.capsule.clastix.io/group.sre: readonly
-  name: oil
-spec:
-  owners:
-    - kind: User
-      name: alice
-    - kind: Group
-      name: sre
-```
-
-For the given configuration, the resulting RoleBinding resources are the following ones:
-
-```
-$: kubectl get rolebindings.rbac.authorization.k8s.io
-NAME                     ROLE                   AGE
-capsule-oil-0-editor     ClusterRole/editor     21s
-capsule-oil-1-manager    ClusterRole/manager    19s
-capsule-oil-2-readonly   ClusterRole/readonly   2s
-```
-
-> The pattern for the annotation is `clusterrolenames.capsule.clastix.io/${KIND}.${NAME}`.
-> The placeholders `${KIND}` and `${NAME}` are referring to the Tenant Owner specification fields, both lower-cased.
-> 
-> In the case of users that are identified using their email address, the symbol `@` wouldn't be supported by the RFC 1123.
-> For such cases, the `@` symbol can be replaced with the placeholder `__AT__`.
-> 
-> ```yaml
-> apiVersion: capsule.clastix.io/v1beta1
-> kind: Tenant
-> metadata:
->   annotations:
->     clusterrolenames.capsule.clastix.io/alice__AT__clastix.io: editor,manager
-> spec:
->   owners:
->     - kind: User
->       name: alice@org.tld
->     - kind: User
->       name: alice@clastix.io
-> ```
-> 
-> Instead, with the resulting annotation key exceeding 63 characters length, the zero-based index of the owner can be specified as follows:
-> 
-> ```yaml
-> apiVersion: capsule.clastix.io/v1beta1
-> kind: Tenant
-> metadata:
->   annotations:
->     clusterrolenames.capsule.clastix.io/1: editor,manager
-> spec:
->   owners:
->     - kind: User
->       name: alice@org.tld
->     - kind: User
->       name: very-long-user-name-that-breaks-rfc-1123@org.tld
-> ```
-> 
-> This latter example will assign the roles `editor` and `manager`, assigned to the user `very-long-user-name-that-breaks-rfc-1123@org.tld`.
-
 ### User as tenant owner
-Bill, the cluster admin, receives a new request from Acme Corp.'s CTO asking for a new tenant to be onboarded and Alice user will be the tenant owner. Bill then assigns Alice's identity of `alice` in the Acme Corp. identity management system. Since Alice is a tenant owner, Bill needs to assign `alice` the Capsule group defined by `--capsule-user-group` option, which defaults to `capsule.clastix.io`.
+Bill, the cluster admin, receives a new request from _Acme Corp_'s CTO asking for a new tenant to be onboarded and Alice user will be the tenant owner. Bill then assigns Alice's identity of `alice` in the _Acme Corp_. identity management system. Since Alice is a tenant owner, Bill needs to assign `alice` the Capsule group defined by `--capsule-user-group` option, which defaults to `capsule.clastix.io`.
 
 To keep things simple, we assume that Bill just creates a client certificate for authentication using X.509 Certificate Signing Request, so Alice's certificate has `"/CN=alice/O=capsule.clastix.io"`.
 
@@ -258,19 +171,24 @@ system:serviceaccounts:{service-account-namespace}
 
 > Please, pay attention when setting a service account acting as tenant owner. Make sure you're not using the group `system:serviceaccounts` or the group `system:serviceaccounts:{capsule-namespace}` as Capsule group, otherwise you'll create a short-circuit in the Capsule controller, being Capsule itself controlled by a serviceaccount. 
 
+### Roles assigned to Tenant Owners
 
-## Create namespaces
-Alice, once logged with her credentials, can create a new namespace in her tenant, as simply issuing:
+By default, all Tenant Owners will be granted with two ClusterRole resources using the RoleBinding API:
+
+1. the Kubernetes default one, [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles), that grants most of the namespace scoped resources
+
+2. a custom one, created by Capsule, named `capsule-namespace-deleter`, allowing to delete the created namespaces
+
+In the example below, assuming the tenant owner creates a namespace `oil-production` in Tenant `oil`, you'll see the Role Bindings giving the tenant owner full permissions on the tenant namespaces:
 
 ```
-kubectl create ns oil-production
+$: kubectl get rolebindings -n oil-production
+NAME                                      ROLE                                    AGE
+capsule-oil-0-admin                       ClusterRole/admin                       6s
+capsule-oil-1-capsule-namespace-deleter   ClusterRole/capsule-namespace-deleter   5s
 ```
 
-Alice started the name of the namespace prepended by the name of the tenant: this is not a strict requirement but it is highly suggested because it is likely that many different tenants would like to call their namespaces `production`, `test`, or `demo`, etc.
-
-The enforcement of this naming convention is optional and can be controlled by the cluster administrator with the `--force-tenant-prefix` option as an argument of the Capsule controller.
-
-When Alice creates the namespace, the Capsule controller listening for creation and deletion events assigns to Alice the following roles:
+When Alice creates the namespaces, the Capsule controller assigns to Alice the following permissions, so that Alice can act as the admin of all the tenant namespaces.
 
 ```yaml
 ---
@@ -301,28 +219,191 @@ roleRef:
   apiGroup: rbac.authorization.k8s.io
 ```
 
-So Alice is the admin of the namespaces:
+In some cases, the cluster admin needs to narrow the range of permissions assigned to tenant owners by assigning a Cluster Role with less permissions than above. Capsule supports the dynamic assignment of any ClusterRole resources for each Tenant Owner.
+
+For example, assign user `Joe` the tenant ownership with only [view](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) permissions on tenant namespaces:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+  annotations:
+    clusterrolenames.capsule.clastix.io/user.joe: view
+spec:
+  owners:
+  - name: alice
+    kind: User
+  - name: joe
+    kind: User
+EOF
+```
+
+you'll see the new Role Bindings assigned to Joe:
 
 ```
-kubectl get rolebindings -n oil-development
+kubectl -n oil-production get rolebindings
 NAME                                      ROLE                                    AGE
-capsule-oil-0-admin                       ClusterRole/admin                       5s
-capsule-oil-1-capsule-namespace-deleter   ClusterRole/capsule-namespace-deleter   4s
+capsule-oil-0-admin                       ClusterRole/admin                       8d
+capsule-oil-1-capsule-namespace-deleter   ClusterRole/capsule-namespace-deleter   8d
+capsule-oil-2-view                        ClusterRole/edit                        5s
 ```
 
-The said Role Binding resources are automatically created by Capsule controller when the tenant owner Alice creates a namespace in the tenant.
+so that Joe can only view resources in the tenant namespaces:
 
-Alice can deploy any resource in the namespace, according to the predefined
-[`admin` cluster role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles).
+```
+kubectl --as joe --as-group capsule.clastix.io auth can-i delete pods -n oil-marketing
+no
+```
+
+> Please, note that, despite created with more restricted permissions, a tenant owner can still create namespaces in the tenant because he belongs to the `capsule.clastix.io` group. If you want a user not acting as tenant owner, but still operating in the tenant, you can assign additional `RoleBindings` without assigning him the tenant ownership.
+
+Custom ClusterRoles are also supported. Assuming the cluster admin creates:
+
+```yaml
+kubectl apply -f - << EOF
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: prometheus-servicemonitors-viewer
+rules:
+- apiGroups: ["monitoring.coreos.com"]
+  resources: ["servicemonitors"]
+  verbs: ["get", "list", "watch"]
+EOF
+```
+
+These permissions can be granted to Joe
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+  annotations:
+    clusterrolenames.capsule.clastix.io/user.joe: view,prometheus-servicemonitors-viewer
+spec:
+  owners:
+  - name: alice
+    kind: User
+  - name: joe
+    kind: User
+EOF
+```
+
+For the given configuration, the resulting RoleBinding resources are the following ones:
+
+```
+kubectl -n oil-production get rolebindings
+NAME                                              ROLE                                            AGE
+capsule-oil-0-admin                               ClusterRole/admin                               8d
+capsule-oil-1-capsule-namespace-deleter           ClusterRole/capsule-namespace-deleter           8d
+capsule-oil-2-view                                ClusterRole/view                                11m
+capsule-oil-3-prometheus-servicemonitors-viewer   ClusterRole/prometheus-servicemonitors-viewer   18s
+```
+
+> The pattern for the annotation is `clusterrolenames.capsule.clastix.io/${KIND}.${NAME}`.
+> The placeholders `${KIND}` and `${NAME}` are referring to the Tenant Owner specification fields, both lower-cased.
+> 
+> In the case of users that are identified using their email address, the symbol `@` wouldn't be supported by the RFC 1123.
+> For such cases, the `@` symbol can be replaced with the placeholder `__AT__`.
+> 
+> ```yaml
+> apiVersion: capsule.clastix.io/v1beta1
+> kind: Tenant
+> metadata:
+>   annotations:
+>     clusterrolenames.capsule.clastix.io/alice__AT__clastix.io: editor,manager
+> spec:
+>   owners:
+>     - kind: User
+>       name: alice@org.tld
+>     - kind: User
+>       name: alice@clastix.io
+> ```
+> 
+> Instead, with the resulting annotation key exceeding 63 characters length, the zero-based index of the owner can be specified as follows:
+> 
+> ```yaml
+> apiVersion: capsule.clastix.io/v1beta1
+> kind: Tenant
+> metadata:
+>   annotations:
+>     clusterrolenames.capsule.clastix.io/1: editor,manager
+> spec:
+>   owners:
+>     - kind: User
+>       name: alice@org.tld
+>     - kind: User
+>       name: very-long-user-name-that-breaks-rfc-1123@org.tld
+> ```
+> 
+> This latter example will assign the roles `editor` and `manager`, assigned to the user `very-long-user-name-that-breaks-rfc-1123@org.tld`.
+
+
+### Assign additional Role Bindings
+The tenant owner acts as admin of tenant namespaces. Other users can operate inside the tenant namespaces with different levels of permissions and authorizations. 
+
+Assuming the cluster admin creates:
+
+```yaml
+kubectl apply -f - << EOF
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: prometheus-servicemonitors-viewer
+rules:
+- apiGroups: ["monitoring.coreos.com"]
+  resources: ["servicemonitors"]
+  verbs: ["get", "list", "watch"]
+EOF
+```
+
+These permissions can be granted to a user without giving the role of tenant owner:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  owners:
+  - name: alice
+    kind: User
+  additionalRoleBindings:
+  - clusterRoleName: 'prometheus-servicemonitors-viewer'
+    subjects:
+    - apiGroup: rbac.authorization.k8s.io
+      kind: User
+      name: joe
+EOF
+```
+
+## Create namespaces
+Alice, once logged with her credentials, can create a new namespace in her tenant, as simply issuing:
+
+```
+kubectl create ns oil-production
+```
+
+Alice started the name of the namespace prepended by the name of the tenant: this is not a strict requirement but it is highly suggested because it is likely that many different tenants would like to call their namespaces `production`, `test`, or `demo`, etc.
+
+The enforcement of this naming convention is optional and can be controlled by the cluster administrator with the `--force-tenant-prefix` option as an argument of the Capsule controller.
+
+Alice can deploy any resource in any of the namespaces
 
 ```
 kubectl -n oil-development run nginx --image=docker.io/nginx 
 kubectl -n oil-development get pods
 ```
 
-Bill, the cluster admin, can control how many namespaces Alice, creates by setting a quota in the tenant manifest `spec.namespaceOptions.quota`
+The cluster admin, can control how many namespaces Alice, creates by setting a quota in the tenant manifest `spec.namespaceOptions.quota`
 
 ```yaml
+kubectl apply -f - << EOF
 apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
@@ -333,6 +414,7 @@ spec:
     kind: User
   namespaceOptions:
     quota: 3
+EOF
 ```
 
 Alice can create additional namespaces according to the quota:
@@ -368,58 +450,6 @@ admission webhook "namespace.capsule.clastix.io" denied the request.
 ```
 The enforcement on the maximum number of namespaces per Tenant is the responsibility of the Capsule controller via its Dynamic Admission Webhook capability.
 
-## Assign permissions
-Alice acts as the tenant admin. Other users can operate inside the tenant with different levels of permissions and authorizations. Alice is responsible for creating additional roles and assigning these roles to other users to work in the same tenant.
-
-One of the key design principles of the Capsule is self-provisioning management from the tenant owner's perspective. Alice, the tenant owner, does not need to interact with Bill, the cluster admin, to complete her day-by-day duties. On the other side, Bill does not have to deal with multiple requests coming from multiple tenant owners that probably will overwhelm him.
-
-Capsule leaves Alice, and the other tenant owners, the freedom to create RBAC roles at the namespace level, or using the pre-defined cluster roles already available in Kubernetes. Since roles and rolebindings are limited to a namespace scope, Alice can assign the roles to the other users accessing the same tenant only after the namespace is created. This gives Alice the power to administer the tenant without the intervention of the cluster admin.
-
-From the cluster admin perspective, the only required action for Bill is to provide the other identities, eg. `joe` in the Identity Management system. This task can be done once when onboarding the tenant and the number of users accessing the tenant can be part of the tenant business profile.
-
-Alice can create Roles and RoleBindings only in the namespaces she owns
-
-```
-kubectl auth can-i get roles -n oil-development
-yes
-
-kubectl auth can-i get rolebindings -n oil-development
-yes
-```
-
-so she can assign the role of namespace `oil-development` admin to Joe, another user accessing the tenant `oil`
-
-```yaml
-kubectl --as alice --as-group capsule.clastix.io apply -f - << EOF
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  labels:
-  name: oil-development:admin
-  namespace: oil-development
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: ClusterRole
-  name: admin
-subjects:
-- apiGroup: rbac.authorization.k8s.io
-  kind: User
-  name: joe
-EOF
-```
-
-Joe now can operate on the namespace `oil-development` as admin but he has no access to the other namespaces `oil-production`, and `oil-test` that are part of the same tenant:
-
-```
-kubectl --as joe --as-group capsule.clastix.io auth can-i create pod -n oil-development
-yes
-
-kubectl --as joe --as-group capsule.clastix.io auth can-i create pod -n oil-production
-no
-```
-
-> Please, note the user `joe`, in the example above, is not acting as tenant owner. He can just operate in `oil-development` namespace as admin.
-
 ## Assign multiple tenants
 A single team is likely responsible for multiple lines of business. For example, in our sample organization Acme Corp., Alice is responsible for both the Oil and Gas lines of business. It's more likely that Alice requires two different tenants, for example, `oil` and `gas` to keep things isolated.
 
@@ -1085,7 +1115,7 @@ Also, Bill can make sure pods belonging to a tenant namespace cannot access othe
 Bill can set network policies in the tenant manifest, according to the requirements:
 
 ```yaml
-kubectl -n oil-production apply -f - << EOF
+kubectl apply -f - << EOF
 apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
@@ -1186,7 +1216,7 @@ Bob, an attacker, could try to schedule a Pod on the same node where Alice is ru
 To avoid this kind of attack, Bill, the cluster admin, can force Alice, the tenant owner, to start her Pods using only the allowed values for `ImagePullPolicy`, enforcing the `kubelet` to check the authorization first.
 
 ```yaml
-kubectl -n oil-production apply -f - << EOF
+kubectl apply -f - << EOF
 apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
@@ -1212,7 +1242,7 @@ The spec `containerRegistries` addresses this task and can provide a combination
 
 
 ```yaml
-kubectl -n oil-production apply -f - << EOF
+kubectl apply -f - << EOF
 apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
@@ -1237,95 +1267,13 @@ A Pod running `internal.registry.foo.tld/capsule:latest` as registry will be all
 
 Any attempt of Alice to use a not allowed `containerRegistries` value is denied by the Validation Webhook enforcing it.
 
-
-## Assign Pod Security Policies
-Bill, the cluster admin, can assign a dedicated Pod Security Policy (PSP) to Alice's tenant. This is likely to be a requirement in a multi-tenancy environment.
-
-The cluster admin creates a PSP:
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: psp:restricted
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  ...
-EOF
-```
-
-Then create a _ClusterRole_ using or granting the said item
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: psp:restricted
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['psp:restricted']
-  verbs: ['use']
-EOF
-```
-
-Bill can assign this role to all namespaces in the Alice's tenant by setting it in the tenant manifest:
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  additionalRoleBindings:
-  - clusterRoleName: psp:privileged
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-```
-
-With the given specification, Capsule will ensure that all Alice's namespaces will contain a _RoleBinding_ for the specified _Cluster Role_.
-
-For example, in the `oil-production` namespace, Alice will see:
-
-```yaml
-kind: RoleBinding
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: 'capsule-oil-psp:privileged'
-  namespace: oil-production
-  labels:
-    capsule.clastix.io/role-binding: a10c4c8c48474963
-    capsule.clastix.io/tenant: oil
-subjects:
-  - kind: Group
-    apiGroup: rbac.authorization.k8s.io
-    name: 'system:authenticated'
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: ClusterRole
-  name: 'psp:privileged'
-```
-
-With the above example, Capsule is forbidding any authenticated user in `oil-production` namespace to run privileged pods and to perform privilege escalation as declared by the Cluster Role `psp:privileged`.
-
 ## Create Custom Resources
 Capsule grants admin permissions to the tenant owners but is only limited to their namespaces. To achieve that, it assigns the ClusterRole [admin](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) to the tenant owner. This ClusterRole does not permit the installation of custom resources in the namespaces.
 
 In order to leave the tenant owner to create Custom Resources in their namespaces, the cluster admin defines a proper Cluster Role. For example:
 
 ```yaml
-kubectl -n oil-production apply -f - << EOF
+kubectl apply -f - << EOF
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
@@ -1350,7 +1298,7 @@ EOF
 Bill can assign this role to any namespace in the Alice's tenant by setting it in the tenant manifest:
 
 ```yaml
-kubectl -n oil-production apply -f - << EOF
+kubectl apply -f - << EOF
 apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
@@ -1448,10 +1396,10 @@ spec:
 
 > This feature is still in an alpha stage and requires a high amount of computing resources due to the dynamic client requests.
 
-## Taint namespaces
-With Capsule, Bill can _"taint"_ the namespaces created by Alice with additional labels and/or annotations. There is no specific semantic assigned to these labels and annotations: they just will be assigned to the namespaces in the tenant as they are created by Alice. This can help the cluster admin to implement specific use cases. As it can be used to implement backup as a service for namespaces in the tenant.
+## Assign Additional Metadata
+The cluster admin can _"taint"_ the namespaces created by tenant onwers with additional metadata as labels and annotations. There is no specific semantic assigned to these labels and annotations: they will be assigned to the namespaces in the tenant as they are created. This can help the cluster admin to implement specific use cases as, for example, leave only a given tenant to be backuped by a backup service.
 
-Bill assigns additional labels and annotations to all namespaces created in the `oil` tenant: 
+Assigns additional labels and annotations to all namespaces created in the `oil` tenant: 
 
 ```yaml
 kubectl apply -f - << EOF
@@ -1466,18 +1414,42 @@ spec:
   namespaceOptions:
     additionalMetadata:
       annotations:
-        capsule.clastix.io/backup: "true"
+        storagelocationtype: s3
       labels:
-        capsule.clastix.io/tenant: oil
+        capsule.clastix.io/backup: "true"
 EOF
 ```
 
-When Alice creates a namespace, this will inherit the given label and/or annotation.
+When the tenant owner creates a namespace, it inherits the given label and/or annotation:
 
-## Taint services
-With Capsule, Bill can _"taint"_ the services created by Alice with additional labels and/or annotations. There is no specific semantic assigned to these labels and annotations: they just will be assigned to the services in the tenant as they are created by Alice. This can help the cluster admin to implement specific use cases.
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  annotations:
+    storagelocationtype: s3
+  labels:
+    capsule.clastix.io/tenant: oil
+    kubernetes.io/metadata.name: oil-production
+    name: oil-production
+    capsule.clastix.io/backup: "true"
+  name: oil-production
+  ownerReferences:
+  - apiVersion: capsule.clastix.io/v1beta1
+    blockOwnerDeletion: true
+    controller: true
+    kind: Tenant
+    name: oil
+spec:
+  finalizers:
+  - kubernetes
+status:
+  phase: Active
+```
 
-Bill assigns additional labels and annotations to all services created in the `oil` tenant: 
+Additionally, the cluster admin can _"taint"_ the services created by the tenant owners with additional metadata as labels and annotations.
+
+Assigns additional labels and annotations to all services created in the `oil` tenant: 
 
 ```yaml
 kubectl apply -f - << EOF
@@ -1491,14 +1463,30 @@ spec:
     kind: User
   serviceOptions:
     additionalMetadata:
-      annotations:
-        capsule.clastix.io/backup: "true"
       labels:
-        capsule.clastix.io/tenant: oil
+        capsule.clastix.io/backup: "true"
 EOF
 ```
 
-When Alice creates a service in a namespace, this will inherit the given label and/or annotation.
+When the tenant owner creates a service in a tenant namespace, it inherits the given label and/or annotation:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx
+  namespace: oil-production
+  labels:
+    capsule.clastix.io/backup: "true"
+spec:
+  ports:
+  - protocol: TCP
+    port: 80 
+    targetPort: 8080 
+  selector:
+    run: nginx
+  type: ClusterIP 
+```
 
 ## Cordon a Tenant
 

docs/content/guides/flux2-capsule.md

@@ -37,18 +37,18 @@ spec:
 In example, the cluster admin is supposed to apply this Kustomization, during the cluster bootstrap that i.e. will reconcile also Flux itself.
 All the remaining Reconciliation resources can be children of this Kustomization.
 
-![bootstrap](./kustomization-hierarchy-root-tenants.png)
+![bootstrap](./assets/kustomization-hierarchy-root-tenants.png)
 
 ### Namespace-as-a-Service
 
 Tenants could have his own set of Namespaces to operate on but it should be prepared by higher-level roles, like platform admins: the declarations would be part of the platform space.
 They would be responsible of tenants administration, and each change (e.g. new tenant Namespace) should be a request that would pass through approval.
 
-![no-naas](./flux-tenants-reconciliation.png)
+![no-naas](./assets/flux-tenants-reconciliation.png)
 
 What if we would like to provide tenants the ability to manage also their own space the GitOps-way? Enter Capsule.
 
-![naas](./flux-tenants-capsule-reconciliation.png)
+![naas](./assets/flux-tenants-capsule-reconciliation.png)
 
 ## The ingredients of the recipe
 

docs/content/guides/pod-security.md

@@ -0,0 +1,258 @@
+# Pod Security
+In Kubernetes, by default, workloads run with administrative access, which might be acceptable if there is only a single application running in the cluster or a single user accessing it. This is seldomly required and you’ll consequently suffer a noisy neighbour effect along with large security blast radiuses.
+
+Many of these concerns were addressed initially by [PodSecurityPolicies](https://kubernetes.io/docs/concepts/security/pod-security-policy) which have been present in the Kubernetes APIs since the very early days.
+
+The Pod Security Policies are deprecated in Kubernetes 1.21 and removed entirely in 1.25. As replacement, the [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) and [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/) has been introduced. Capsule support the new standard for tenants under its control as well as the oldest approach.
+
+## Pod Security Policies
+As stated in the documentation, *"PodSecurityPolicies enable fine-grained authorization of pod creation and updates. A Pod Security Policy is a cluster-level resource that controls security sensitive aspects of the pod specification. The `PodSecurityPolicy` objects define a set of conditions that a pod must run with in order to be accepted into the system, as well as defaults for the related fields."*
+
+Using the [Pod Security Policies](https://kubernetes.io/docs/concepts/security/pod-security-policy), the cluster admin can impose limits on pod creation, for example the types of volume that can be consumed, the linux user that the process runs as in order to avoid running things as root, and more. From multi-tenancy point of view, the cluster admin has to control how users run pods in their tenants with a different level of permission on tenant basis.
+
+Assume the Kubernetes cluster has been configured with [Pod Security Policy Admission Controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy) enabled in the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
+
+The cluster admin creates a `PodSecurityPolicy`:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: policy/v1beta1
+kind: PodSecurityPolicy
+metadata:
+  name: psp:restricted
+spec:
+  privileged: false
+  # Required to prevent escalations to root.
+  allowPrivilegeEscalation: false
+EOF
+```
+
+Then create a _ClusterRole_ using or granting the said item
+
+```yaml
+kubectl apply -f - << EOF
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: psp:restricted
+rules:
+- apiGroups: ['policy']
+  resources: ['podsecuritypolicies']
+  resourceNames: ['psp:restricted']
+  verbs: ['use']
+EOF
+```
+
+He can assign this role to all namespaces in a tenant by setting the tenant manifest:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  owners:
+  - name: alice
+    kind: User
+  additionalRoleBindings:
+  - clusterRoleName: psp:privileged
+    subjects:
+    - kind: "Group"
+      apiGroup: "rbac.authorization.k8s.io"
+      name: "system:authenticated"
+EOF
+```
+
+With the given specification, Capsule will ensure that all tenant namespaces will contain a _RoleBinding_ for the specified _Cluster Role_:
+
+```yaml
+kind: RoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: 'capsule-oil-psp:privileged'
+  namespace: oil-production
+  labels:
+    capsule.clastix.io/tenant: oil
+subjects:
+  - kind: Group
+    apiGroup: rbac.authorization.k8s.io
+    name: 'system:authenticated'
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: 'psp:privileged'
+```
+
+Capsule admission controller forbids the tenant owner to run privileged pods in `oil-production` namespace and perform privilege escalation as declared by the above Cluster Role `psp:privileged`.
+
+As tenant owner, creates a namespace:
+
+```
+kubectl --kubeconfig alice-oil.kubeconfig create ns oil-production
+```
+
+and create a pod with privileged permissions:
+
+```yaml
+kubectl --kubeconfig alice-oil.kubeconfig apply -f - << EOF
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+  namespace: oil-production
+spec:
+  containers:
+  - image: nginx
+    name: nginx
+    ports:
+    - containerPort: 80
+    securityContext:
+      privileged: true
+EOF
+```
+
+Since the assigned `PodSecurityPolicy` explicitly disallows privileged containers, the tenant owner will see her request to be rejected by the Pod Security Policy Admission Controller.
+
+## Pod Security Standards
+One of the issues with Pod Secury Policies is that it is difficult to apply restrictive permissions on a granular level, increasing security risk. Also the Pod Security Policies get applied when the request is submitted and there is no way of applying them to pods that are already running. For these, and other reasons, the Kubernetes community decided to deprecate the Pod Secury Policies.
+
+As the Pod Secury Policies get deprecated and removed, the [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) is used in place. It defines three different policies to broadly cover the security spectrum. These policies are cumulative and range from highly-permissive to highly-restrictive:
+
+- **Privileged**: unrestricted policy, providing the widest possible level of permissions.
+- **Baseline**: minimally restrictive policy which prevents known privilege escalations.
+- **Restricted**: heavily restricted policy, following current Pod hardening best practices.
+
+Kubernetes provides a built-in [Admission Controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podsecurity) to enforce the Pod Security Standards at either:
+
+1. cluster level which applies a standard configuration to all namespaces in a cluster
+2. namespace level, one namespace at a time
+
+For the first case, the cluster admin has to configure the Admission Controller and pass the configuration to the `kube-apiserver` by mean of the `--admission-control-config-file` extra argument, for example:
+
+```yaml
+apiVersion: apiserver.config.k8s.io/v1
+kind: AdmissionConfiguration
+plugins:
+- name: PodSecurity
+  configuration:
+    apiVersion: pod-security.admission.config.k8s.io/v1beta1
+    kind: PodSecurityConfiguration
+    defaults:
+      enforce: "baseline"
+      enforce-version: "latest"
+      warn: "restricted"
+      warn-version: "latest"
+      audit: "restricted"
+      audit-version: "latest"
+    exemptions:
+      usernames: []
+      runtimeClasses: []
+      namespaces: [kube-system]
+```
+
+For the second case, he can just assign labels to the specific namespace he wants enforce the policy since the Pod Security Admission Controller is enabled by default starting from Kubernetes 1.23+:
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  labels:
+    pod-security.kubernetes.io/enforce: baseline
+    pod-security.kubernetes.io/warn: restricted
+    pod-security.kubernetes.io/audit: restricted
+  name: development
+```
+
+## Pod Security Standards with Capsule
+According to the regular Kubernetes segregation model, the cluster admin has to operate either at cluster level or at namespace level. Since Capsule introduces a further segregation level (the _Tenant_ abstraction), the cluster admin can implement Pod Security Standards at tenant level by simply forcing specific labels on all the namespaces created in the tenant.
+
+As cluster admin, create a tenant with additional labels:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  namespaceOptions:
+    additionalMetadata:
+      labels:
+        pod-security.kubernetes.io/enforce: baseline
+        pod-security.kubernetes.io/audit: restricted
+        pod-security.kubernetes.io/warn: restricted
+  owners:
+  - kind: User
+    name: alice
+EOF
+```
+
+All namespaces created by the tenant owner, will inherit the Pod Security labels: 
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  labels:
+    capsule.clastix.io/tenant: oil
+    kubernetes.io/metadata.name: oil-development
+    name: oil-development
+    pod-security.kubernetes.io/enforce: baseline
+    pod-security.kubernetes.io/warn: restricted
+    pod-security.kubernetes.io/audit: restricted
+  name: oil-development
+  ownerReferences:
+  - apiVersion: capsule.clastix.io/v1beta1
+    blockOwnerDeletion: true
+    controller: true
+    kind: Tenant
+    name: oil
+```
+
+and the regular Pod Security Admission Controller does the magic:
+
+```yaml
+kubectl --kubeconfig alice-oil.kubeconfig apply -f - << EOF
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+  namespace: oil-production
+spec:
+  containers:
+  - image: nginx
+    name: nginx
+    ports:
+    - containerPort: 80
+    securityContext:
+      privileged: true
+EOF
+```
+
+The request gets denied:
+
+```
+Error from server (Forbidden): error when creating "STDIN":
+pods "nginx" is forbidden: violates PodSecurity "baseline:latest": privileged
+(container "nginx" must not set securityContext.privileged=true)
+```
+
+If the tenant owner tries to change o delete the above labels, Capsule will reconcile them to the original tenant manifest set by the cluster admin.
+
+As additional security measure, the cluster admin can also prevent the tenant owner to make an improper usage of the above labels:
+
+```
+kubectl annotate tenant oil \
+  capsule.clastix.io/forbidden-namespace-labels-regexp="pod-security.kubernetes.io\/(enforce|warn|audit)"
+```
+
+In that case, the tenant owner gets denied if she tries to use the labels:
+
+```
+kubectl --kubeconfig alice-oil.kubeconfig label ns oil-production \
+    pod-security.kubernetes.io/enforce=restricted \
+    --overwrite
+
+Error from server (Label pod-security.kubernetes.io/audit is forbidden for namespaces in the current Tenant ...
+```

docs/content/guides/velero.md

@@ -1,23 +1,125 @@
 # Tenants Backup and Restore with Velero
 
-[Velero](https://velero.io) is a backup and restore solution that performs disaster recovery and migrates Kubernetes cluster resources and persistent volumes.
+[Velero](https://velero.io) is a backup and restore solution that performs data protection, disaster recovery and migrates Kubernetes cluster from on-premises to the Cloud or between different Clouds.
 
-Using Velero in a Kubernetes cluster where Capsule is installed can lead to an incomplete restore of the cluster's Tenants. This is because Velero omits the `ownerReferences` section from the tenant's namespace manifests when backup them.
+When coming to backup and restore in Kubernetes, we have two main requirements:
 
-To avoid this problem you can use the script `velero-restore.sh` under the `hack/` folder.
+- Configurations backup
+- Data backup
 
-In case of a data loss, the right thing to do is to restore the cluster with **Velero** at first. Once Velero has finished, you can proceed using the script to complete the restoration.
+The first requirement aims to backup all the resources stored into `etcd` database, for example: `namespaces`, `pods`, `services`, `deployments`, etc. The second is about how to backup stateful application data as volumes.
 
-```bash
-./velero-restore.sh --kubeconfing /path/to/your/kubeconfig restore
+The main limitation of Velero is the multi tenancy. Currently, Velero does not support multi tenancy meaning it can be only used from admin users and so it cannot provided "as a service" to the users. This means that the cluster admin needs to take care of users' backup.
+
+Assuming you have multiple tenants managed by Capsule, for example `oil` and `gas`, as cluster admin, you can to take care of scheduling backups for:
+
+- Tenant cluster resources
+- Namespaces belonging to each tenant
+
+## Create backup of a tenant
+Create a backup of the tenant `oil`. It consists in two different backups:
+
+- backup of the tenant resource
+- backup of all the resources belonging to the tenant
+
+To backup the `oil` tenant selectively, label the tenant as:
+
+```
+kubectl label tenant oil capsule.clastix.io/tenant=oil
 ```
 
-Running this command, we are going to patch the tenant's namespaces manifests that are actually `ownerReferences`-less. Once the command has finished its run, you got the cluster back.
+and create the backup
 
-Additionally, you can also specify a selected range of tenants to be restored:
-
-```bash
-./velero-restore.sh --tenant "gas oil" restore
+```
+velero create backup oil-tenant \
+    --include-cluster-resources=true \
+    --include-resources=tenants.capsule.clastix.io \
+    --selector capsule.clastix.io/tenant=oil
 ```
 
-In this way, only the tenants **gas** and **oil** will be restored.
+resulting in the following Velero object:
+
+```yaml
+apiVersion: velero.io/v1
+kind: Backup
+metadata:
+  name: oil-tenant
+spec:
+  defaultVolumesToRestic: false
+  hooks: {}
+  includeClusterResources: true
+  includedNamespaces:
+  - '*'
+  includedResources:
+  - tenants.capsule.clastix.io
+  labelSelector:
+    matchLabels:
+      capsule.clastix.io/tenant: oil
+  metadata: {}
+  storageLocation: default
+  ttl: 720h0m0s
+```
+
+Create a backup of all the resources belonging to the `oil` tenant namespaces:
+
+```
+velero create backup oil-namespaces \
+    --include-cluster-resources=false \
+    --include-namespaces oil-production,oil-development,oil-marketing
+```
+
+resulting ti the following Velero object:
+
+```yaml
+apiVersion: velero.io/v1
+kind: Backup
+metadata:
+  name: oil-namespaces
+spec:
+  defaultVolumesToRestic: false
+  hooks: {}
+  includeClusterResources: false
+  includedNamespaces:
+  - oil-production
+  - oil-development
+  - oil-marketing
+  metadata: {}
+  storageLocation: default
+  ttl: 720h0m0s
+```
+
+> Velero requires an Object Storage backend where to store backups, you should take care of this requirement before to use Velero.
+
+## Restore a tenant from the backup
+To recover the tenant after a disaster, or to migrate it to another cluster, create a restore from the previous backups:
+
+```
+velero create restore --from-backup oil-tenant
+velero create restore --from-backup oil-namespaces
+```
+
+Using Velero to restore a Capsule tenant can lead to an incomplete recovery of tenant because the namespaces restored with Velero do not have the `OwnerReference` field used to bind the namespaces to the tenant. For this reason, all restored namespaces are not bound to the tenant:
+
+```
+kubectl get tnt
+NAME   STATE    NAMESPACE QUOTA   NAMESPACE COUNT   NODE SELECTOR     AGE
+gas    active   9                 5                 {"pool":"gas"}    34m
+solar  active   9                 8                 {"pool":"solar"}  33m
+oil    active   9                 0 # <<<           {"pool":"oil"}    54m
+```
+
+To avoid this problem you can use the script `velero-restore.sh` located under the `hack/` folder:
+
+```
+./velero-restore.sh --kubeconfing /path/to/your/kubeconfig --tenant "oil" restore
+```
+
+Running this command, we are going to patch the tenant's namespaces manifests that are actually `ownerReferences`-less. Once the command has finished its run, you got the tenant back.
+
+```
+kubectl get tnt
+NAME   STATE    NAMESPACE QUOTA   NAMESPACE COUNT   NODE SELECTOR     AGE
+gas    active   9                 5                 {"pool":"gas"}    44m
+solar  active   9                 8                 {"pool":"solar"}  43m
+oil    active   9                 3 # <<<           {"pool":"oil"}    12s
+```

docs/gridsome.server.js

@@ -70,10 +70,18 @@ module.exports = function (api) {
               label: 'Upgrading Tenant version',
               path: '/docs/guides/upgrading'
             },
+            {
+              label: 'Multi-tenant GitOps with Flux',
+              path: '/docs/guides/flux2-capsule'
+            },
             {
               label: 'Install on Charmed Kubernetes',
               path: '/docs/guides/charmed'
             },
+            {
+              label: 'Control Pod Security',
+              path: '/docs/guides/pod-security'
+            },
             {
               title: 'Managed Kubernetes',
               subItems: [
@@ -90,11 +98,7 @@ module.exports = function (api) {
                   path: '/docs/guides/managed-kubernetes/coaks'
                 },
               ]
-            },
-			{
-				label: 'Flux and Capsule for multi-tenant GitOps',
-				path: '/docs/guides/flux2-capsule'
-			}
+            }
           ]
         },
         {