feat(helm): add imagePullSecrets to jobs

Co-authored-by: Tom OBrien <tom.obrien@ns.nl>

.github/workflows/e2e.yml

@@ -5,8 +5,8 @@ on:
     branches: [ "*" ]
     paths:
       - '.github/workflows/e2e.yml'
-      - 'api/*'
-      - 'controllers/*'
+      - 'api/**'
+      - 'controllers/**'
       - 'e2e/*'
       - 'Dockerfile'
       - 'go.*'
@@ -16,8 +16,8 @@ on:
     branches: [ "*" ]
     paths:
       - '.github/workflows/e2e.yml'
-      - 'api/*'
-      - 'controllers/*'
+      - 'api/**'
+      - 'controllers/**'
       - 'e2e/*'
       - 'Dockerfile'
       - 'go.*'

.github/workflows/helm.yml

@@ -6,9 +6,6 @@ on:
     tags: [ "helm-v*" ]
   pull_request:
     branches: [ "*" ]
-  create:
-    branches: [ "*" ]
-    tags: [ "helm-v*" ]
 
 jobs:
   lint:

.gitignore

@@ -22,6 +22,7 @@ bin
 *.swp
 *.swo
 *~
+.vscode
 
 **/*.kubeconfig
 **/*.crt

Makefile

@@ -45,7 +45,7 @@ manager: generate fmt vet
 
 # Run against the configured Kubernetes cluster in ~/.kube/config
 run: generate manifests
-	go run ./main.go
+	go run .
 
 # Creates the single file to install Capsule without any external dependency
 installer: manifests kustomize
@@ -78,6 +78,58 @@ manifests: controller-gen
 generate: controller-gen
 	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
 
+# Setup development env
+# Usage: 
+# 	LAPTOP_HOST_IP=<YOUR_LAPTOP_IP> make dev-setup
+# For example:
+#	LAPTOP_HOST_IP=192.168.10.101 make dev-setup
+define TLS_CNF
+[ req ]
+default_bits       = 4096
+distinguished_name = req_distinguished_name
+req_extensions     = req_ext
+[ req_distinguished_name ]
+countryName                = SG
+stateOrProvinceName        = SG
+localityName               = SG
+organizationName           = CAPSULE
+commonName                 = CAPSULE
+[ req_ext ]
+subjectAltName = @alt_names
+[alt_names]
+IP.1   = $(LAPTOP_HOST_IP)
+endef
+export TLS_CNF
+dev-setup:
+	kubectl -n capsule-system scale deployment capsule-controller-manager --replicas=0
+	mkdir -p /tmp/k8s-webhook-server/serving-certs
+	echo "$${TLS_CNF}" > _tls.cnf
+	openssl req -newkey rsa:4096 -days 3650 -nodes -x509 \
+		-subj "/C=SG/ST=SG/L=SG/O=CAPSULE/CN=CAPSULE" \
+		-extensions req_ext \
+		-config _tls.cnf \
+		-keyout /tmp/k8s-webhook-server/serving-certs/tls.key \
+		-out /tmp/k8s-webhook-server/serving-certs/tls.crt
+	rm -f _tls.cnf 
+	export WEBHOOK_URL="https://$${LAPTOP_HOST_IP}:9443"; \
+	export CA_BUNDLE=`openssl base64 -in /tmp/k8s-webhook-server/serving-certs/tls.crt | tr -d '\n'`; \
+	kubectl patch MutatingWebhookConfiguration capsule-mutating-webhook-configuration \
+		--type='json' -p="[\
+			{'op': 'replace', 'path': '/webhooks/0/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/mutate-v1-namespace-owner-reference\",'caBundle':\"$${CA_BUNDLE}\"}}\
+		]" && \
+	kubectl patch ValidatingWebhookConfiguration capsule-validating-webhook-configuration \
+		--type='json' -p="[\
+			{'op': 'replace', 'path': '/webhooks/0/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/cordoning\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/1/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/ingresses\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/2/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/namespaces\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/3/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/networkpolicies\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/4/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/pods\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/5/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/persistentvolumeclaims\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/6/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/services\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/7/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/tenants\",'caBundle':\"$${CA_BUNDLE}\"}},\
+			{'op': 'replace', 'path': '/webhooks/8/clientConfig', 'value':{'url':\"$${WEBHOOK_URL}/nodes\",'caBundle':\"$${CA_BUNDLE}\"}}\
+		]";
+
 # Build the docker image
 docker-build: test
 	docker build . -t ${IMG} --build-arg GIT_HEAD_COMMIT=$(GIT_HEAD_COMMIT) \

README.md

@@ -14,161 +14,63 @@
 ---
 
 # Kubernetes multi-tenancy made easy
-**Capsule** helps to implement a multi-tenancy and policy-based environment in your Kubernetes cluster. It is not intended to be yet another _PaaS_, instead, it has been designed as a micro-services-based ecosystem with the minimalist approach, leveraging only on upstream Kubernetes.
+
+**Capsule** implements a multi-tenant and policy-based environment in your Kubernetes cluster. It is designed as a micro-services-based ecosystem with the minimalist approach, leveraging only on upstream Kubernetes.
 
 # What's the problem with the current status?
 
 Kubernetes introduces the _Namespace_ object type to create logical partitions of the cluster as isolated *slices*. However, implementing advanced multi-tenancy scenarios, it soon becomes complicated because of the flat structure of Kubernetes namespaces and the impossibility to share resources among namespaces belonging to the same tenant. To overcome this, cluster admins tend to provision a dedicated cluster for each groups of users, teams, or departments. As an organization grows, the number of clusters to manage and keep aligned becomes an operational nightmare, described as the well know phenomena of the _clusters sprawl_.
 
-
 # Entering Capsule
-Capsule takes a different approach. In a single cluster, the Capsule Controller aggregates multiple namespaces in a lightweight abstraction called _Tenant_, basically a grouping of Kubernetes Namespaces. Within each tenant, users are free to create their namespaces and share all the assigned resources while the Capsule Policy Engine keeps the different tenants isolated from each other.
 
-The _Network and Security Policies_, _Resource Quota_, _Limit Ranges_, _RBAC_, and other policies defined at the tenant level are automatically inherited by all the namespaces in the tenant. Then users are free to operate their tenants in autonomy, without the intervention of the cluster administrator. Take a look at following diagram:
+Capsule takes a different approach. In a single cluster, the Capsule Controller aggregates multiple namespaces in a lightweight abstraction called _Tenant_, basically a grouping of Kubernetes Namespaces. Within each tenant, users are free to create their namespaces and share all the assigned resources. 
 
-<p align="center" style="padding: 60px 20px">
-  <img src="assets/capsule-operator.svg" />
-</p>
+On the other side, the Capsule Policy Engine keeps the different tenants isolated from each other. _Network and Security Policies_, _Resource Quota_, _Limit Ranges_, _RBAC_, and other policies defined at the tenant level are automatically inherited by all the namespaces in the tenant. Then users are free to operate their tenants in autonomy, without the intervention of the cluster administrator. 
 
 # Features
+
 ## Self-Service
-Leave to developers the freedom to self-provision their cluster resources according to the assigned boundaries.
+
+Leave developers the freedom to self-provision their cluster resources according to the assigned boundaries.
 
 ## Preventing Clusters Sprawl
+
 Share a single cluster with multiple teams, groups of users, or departments by saving operational and management efforts.
 
 ## Governance
-Leverage Kubernetes Admission Controllers to enforce the industry security best practices and meet legal requirements.
+
+Leverage Kubernetes Admission Controllers to enforce the industry security best practices and meet policy requirements.
 
 ## Resources Control
+
 Take control of the resources consumed by users while preventing them to overtake.
 
 ## Native Experience
+
 Provide multi-tenancy with a native Kubernetes experience without introducing additional management layers, plugins, or customized binaries.
 
 ## GitOps ready
+
 Capsule is completely declarative and GitOps ready.
 
 ## Bring your own device (BYOD)
+
 Assign to tenants a dedicated set of compute, storage, and network resources and avoid the noisy neighbors' effect.
 
-# Common use cases for Capsule
-Please, refer to the corresponding [section](./docs/operator/use-cases/overview.md) in the project documentation for a detailed list of common use cases that Capsule can address.
-
-# Installation
-Make sure you have access to a Kubernetes cluster as administrator.
-
-There are two ways to install Capsule:
-
-* Use the Helm Chart available [here](./charts/capsule/README.md)
-* Use the [single YAML file installer](./config/install.yaml)
-
-## Install with the single YAML file installer
-
-Ensure you have `kubectl` installed in your `PATH`. 
-
-Clone this repository and move to the repo folder:
-
-```
-$ kubectl apply -f https://raw.githubusercontent.com/clastix/capsule/master/config/install.yaml
-```
-
-It will install the Capsule controller in a dedicated namespace `capsule-system`.
-
-## How to create Tenants
-Use the scaffold [Tenant](config/samples/capsule_v1beta1_tenant.yaml) and simply apply as cluster admin.
-
-```
-$ kubectl apply -f config/samples/capsule_v1beta1_tenant.yaml
-tenant.capsule.clastix.io/gas created
-```
-
-You can check the tenant just created as
-
-```
-$ kubectl get tenants
-NAME   STATE    NAMESPACE QUOTA   NAMESPACE COUNT   NODE SELECTOR                  AGE
-gas    Active   3                 0                 {"kubernetes.io/os":"linux"}   25s
-```
-
-## Tenant owners
-Each tenant comes with a delegated user or group of users acting as the tenant admin. In the Capsule jargon, this is called the _Tenant Owner_. Other users can operate inside a tenant with different levels of permissions and authorizations assigned directly by the Tenant Owner.
-
-Capsule does not care about the authentication strategy used in the cluster and all the Kubernetes methods of [authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/) are supported. The only requirement to use Capsule is to assign tenant users to the the group defined by `--capsule-user-group` option, which defaults to `capsule.clastix.io`.
-
-Assignment to a group depends on the authentication strategy in your cluster.
-
-For example, if you are using `capsule.clastix.io`, users authenticated through a _X.509_ certificate must have `capsule.clastix.io` as _Organization_: `-subj "/CN=${USER}/O=capsule.clastix.io"`
-
-Users authenticated through an _OIDC token_ must have in their token:
-
-```json
-...
-"users_groups": [
-  "capsule.clastix.io",
-  "other_group"
-]
-```
-
-The [hack/create-user.sh](hack/create-user.sh) can help you set up a dummy `kubeconfig` for the `bob` user acting as owner of a tenant called `gas`
-
-```bash
-./hack/create-user.sh bob gas
-...
-certificatesigningrequest.certificates.k8s.io/bob-gas created
-certificatesigningrequest.certificates.k8s.io/bob-gas approved
-kubeconfig file is: bob-gas.kubeconfig
-to use it as bob export KUBECONFIG=bob-gas.kubeconfig
-```
-
-## Working with Tenants
-Log in to the Kubernetes cluster as `bob` tenant owner
-
-```
-$ export KUBECONFIG=bob-gas.kubeconfig
-```
-
-and create a couple of new namespaces
-
-```
-$ kubectl create namespace gas-production
-$ kubectl create namespace gas-development
-```
-
-As user `bob` you can operate with fully admin permissions:
-
-```
-$ kubectl -n gas-development run nginx --image=docker.io/nginx 
-$ kubectl -n gas-development get pods
-```
-
-but limited to only your own namespaces:
-
-```
-$ kubectl -n kube-system get pods
-Error from server (Forbidden): pods is forbidden:
-User "bob" cannot list resource "pods" in API group "" in the namespace "kube-system"
-```
-
 # Documentation
-Please, check the project [documentation](./docs/index.md) for more cool things you can do with Capsule.
 
-# Removal
-Similar to `deploy`, you can get rid of Capsule using the `remove` target.
+Please, check the project [documentation](capsule.clastix.io) for the cool things you can do with Capsule.
 
-```
-$ make remove
-```
+# Contributions
+
+Capsule is Open Source with Apache 2 license and any contribution is welcome.
 
 # FAQ
+
 - Q. How to pronounce Capsule?
 
   A. It should be pronounced as `/ˈkæpsjuːl/`.
 
-- Q. Can I contribute?
-
-  A. Absolutely! Capsule is Open Source with Apache 2 license and any contribution is welcome. Please refer to the corresponding [section](./docs/operator/contributing.md) in the documentation.
-
 - Q. Is it production grade?
 
   A. Although under frequent development and improvements, Capsule is ready to be used in production environments as currently, people are using it in public and private deployments. Check out the [release](https://github.com/clastix/capsule/releases) page for a detailed list of available versions.

api/v1alpha1/capsuleconfiguration_annotations.go

@@ -0,0 +1,8 @@
+package v1alpha1
+
+const (
+	ForbiddenNodeLabelsAnnotation            = "capsule.clastix.io/forbidden-node-labels"
+	ForbiddenNodeLabelsRegexpAnnotation      = "capsule.clastix.io/forbidden-node-labels-regexp"
+	ForbiddenNodeAnnotationsAnnotation       = "capsule.clastix.io/forbidden-node-annotations"
+	ForbiddenNodeAnnotationsRegexpAnnotation = "capsule.clastix.io/forbidden-node-annotations-regexp"
+)

api/v1alpha1/conversion_hub.go

@@ -200,17 +200,17 @@ func (t *Tenant) ConvertTo(dstRaw conversion.Hub) error {
 		}
 	}
 	if len(t.Spec.NetworkPolicies) > 0 {
-		dst.Spec.NetworkPolicies = &capsulev1beta1.NetworkPolicySpec{
+		dst.Spec.NetworkPolicies = capsulev1beta1.NetworkPolicySpec{
 			Items: t.Spec.NetworkPolicies,
 		}
 	}
 	if len(t.Spec.LimitRanges) > 0 {
-		dst.Spec.LimitRanges = &capsulev1beta1.LimitRangesSpec{
+		dst.Spec.LimitRanges = capsulev1beta1.LimitRangesSpec{
 			Items: t.Spec.LimitRanges,
 		}
 	}
 	if len(t.Spec.ResourceQuota) > 0 {
-		dst.Spec.ResourceQuota = &capsulev1beta1.ResourceQuotaSpec{
+		dst.Spec.ResourceQuota = capsulev1beta1.ResourceQuotaSpec{
 			Scope: func() capsulev1beta1.ResourceQuotaScope {
 				if v, ok := t.GetAnnotations()[resourceQuotaScopeAnnotation]; ok {
 					switch v {
@@ -500,13 +500,13 @@ func (t *Tenant) ConvertFrom(srcRaw conversion.Hub) error {
 			Regex: src.Spec.ContainerRegistries.Regex,
 		}
 	}
-	if src.Spec.NetworkPolicies != nil {
+	if len(src.Spec.NetworkPolicies.Items) > 0 {
 		t.Spec.NetworkPolicies = src.Spec.NetworkPolicies.Items
 	}
-	if src.Spec.LimitRanges != nil {
+	if len(src.Spec.LimitRanges.Items) > 0 {
 		t.Spec.LimitRanges = src.Spec.LimitRanges.Items
 	}
-	if src.Spec.ResourceQuota != nil {
+	if len(src.Spec.ResourceQuota.Items) > 0 {
 		t.Annotations[resourceQuotaScopeAnnotation] = string(src.Spec.ResourceQuota.Scope)
 		t.Spec.ResourceQuota = src.Spec.ResourceQuota.Items
 	}
@@ -545,9 +545,15 @@ func (t *Tenant) ConvertFrom(srcRaw conversion.Hub) error {
 	}
 
 	if src.Spec.ServiceOptions != nil && src.Spec.ServiceOptions.AllowedServices != nil {
-		t.Annotations[enableNodePortsAnnotation] = strconv.FormatBool(*src.Spec.ServiceOptions.AllowedServices.NodePort)
-		t.Annotations[enableExternalNameAnnotation] = strconv.FormatBool(*src.Spec.ServiceOptions.AllowedServices.ExternalName)
-		t.Annotations[enableLoadBalancerAnnotation] = strconv.FormatBool(*src.Spec.ServiceOptions.AllowedServices.LoadBalancer)
+		if src.Spec.ServiceOptions.AllowedServices.NodePort != nil {
+			t.Annotations[enableNodePortsAnnotation] = strconv.FormatBool(*src.Spec.ServiceOptions.AllowedServices.NodePort)
+		}
+		if src.Spec.ServiceOptions.AllowedServices.ExternalName != nil {
+			t.Annotations[enableExternalNameAnnotation] = strconv.FormatBool(*src.Spec.ServiceOptions.AllowedServices.ExternalName)
+		}
+		if src.Spec.ServiceOptions.AllowedServices.LoadBalancer != nil {
+			t.Annotations[enableLoadBalancerAnnotation] = strconv.FormatBool(*src.Spec.ServiceOptions.AllowedServices.LoadBalancer)
+		}
 	}
 
 	// Status

api/v1alpha1/conversion_hub_test.go

@@ -240,13 +240,13 @@ func generateTenantsSpecs() (Tenant, capsulev1beta1.Tenant) {
 			},
 			ContainerRegistries: v1beta1AllowedListSpec,
 			NodeSelector:        nodeSelector,
-			NetworkPolicies: &capsulev1beta1.NetworkPolicySpec{
+			NetworkPolicies: capsulev1beta1.NetworkPolicySpec{
 				Items: networkPolicies,
 			},
-			LimitRanges: &capsulev1beta1.LimitRangesSpec{
+			LimitRanges: capsulev1beta1.LimitRangesSpec{
 				Items: limitRanges,
 			},
-			ResourceQuota: &capsulev1beta1.ResourceQuotaSpec{
+			ResourceQuota: capsulev1beta1.ResourceQuotaSpec{
 				Scope: capsulev1beta1.ResourceQuotaScopeNamespace,
 				Items: resourceQuotas,
 			},

api/v1alpha1/zz_generated.deepcopy.go

@@ -1,3 +1,4 @@
+//go:build !ignore_autogenerated
 // +build !ignore_autogenerated
 
 // Copyright 2020-2021 Clastix Labs

api/v1beta1/tenant_types.go

@@ -24,11 +24,11 @@ type TenantSpec struct {
 	// Specifies the label to control the placement of pods on a given pool of worker nodes. All namesapces created within the Tenant will have the node selector annotation. This annotation tells the Kubernetes scheduler to place pods on the nodes having the selector label. Optional.
 	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
 	// Specifies the NetworkPolicies assigned to the Tenant. The assigned NetworkPolicies are inherited by any namespace created in the Tenant. Optional.
-	NetworkPolicies *NetworkPolicySpec `json:"networkPolicies,omitempty"`
+	NetworkPolicies NetworkPolicySpec `json:"networkPolicies,omitempty"`
 	// Specifies the NetworkPolicies assigned to the Tenant. The assigned NetworkPolicies are inherited by any namespace created in the Tenant. Optional.
-	LimitRanges *LimitRangesSpec `json:"limitRanges,omitempty"`
+	LimitRanges LimitRangesSpec `json:"limitRanges,omitempty"`
 	// Specifies a list of ResourceQuota resources assigned to the Tenant. The assigned values are inherited by any namespace created in the Tenant. The Capsule operator aggregates ResourceQuota at Tenant level, so that the hard quota is never crossed for the given Tenant. This permits the Tenant owner to consume resources in the Tenant regardless of the namespace. Optional.
-	ResourceQuota *ResourceQuotaSpec `json:"resourceQuotas,omitempty"`
+	ResourceQuota ResourceQuotaSpec `json:"resourceQuotas,omitempty"`
 	// Specifies additional RoleBindings assigned to the Tenant. Capsule will ensure that all namespaces in the Tenant always contain the RoleBinding for the given ClusterRole. Optional.
 	AdditionalRoleBindings []AdditionalRoleBindingsSpec `json:"additionalRoleBindings,omitempty"`
 	// 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.

api/v1beta1/zz_generated.deepcopy.go

@@ -1,3 +1,4 @@
+//go:build !ignore_autogenerated
 // +build !ignore_autogenerated
 
 // Copyright 2020-2021 Clastix Labs
@@ -480,21 +481,9 @@ func (in *TenantSpec) DeepCopyInto(out *TenantSpec) {
 			(*out)[key] = val
 		}
 	}
-	if in.NetworkPolicies != nil {
-		in, out := &in.NetworkPolicies, &out.NetworkPolicies
-		*out = new(NetworkPolicySpec)
-		(*in).DeepCopyInto(*out)
-	}
-	if in.LimitRanges != nil {
-		in, out := &in.LimitRanges, &out.LimitRanges
-		*out = new(LimitRangesSpec)
-		(*in).DeepCopyInto(*out)
-	}
-	if in.ResourceQuota != nil {
-		in, out := &in.ResourceQuota, &out.ResourceQuota
-		*out = new(ResourceQuotaSpec)
-		(*in).DeepCopyInto(*out)
-	}
+	in.NetworkPolicies.DeepCopyInto(&out.NetworkPolicies)
+	in.LimitRanges.DeepCopyInto(&out.LimitRanges)
+	in.ResourceQuota.DeepCopyInto(&out.ResourceQuota)
 	if in.AdditionalRoleBindings != nil {
 		in, out := &in.AdditionalRoleBindings, &out.AdditionalRoleBindings
 		*out = make([]AdditionalRoleBindingsSpec, len(*in))

charts/capsule/Chart.yaml

@@ -21,7 +21,7 @@ sources:
 
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
-version: 0.1.2
+version: 0.1.4
 
 # This is the version number of the application being deployed.
 # This version number should be incremented each time you make changes to the application.

charts/capsule/README.md

@@ -80,6 +80,7 @@ Parameter | Description | Default
 `manager.resources.limits/cpu` | Set the memory limits assigned to the controller. | `128Mi`
 `mutatingWebhooksTimeoutSeconds` | Timeout in seconds for mutating webhooks. | `30`
 `validatingWebhooksTimeoutSeconds` | Timeout in seconds for validating webhooks. | `30`
+`webhooks` | Additional configuration for capsule webhooks. |
 `imagePullSecrets` | Configuration for `imagePullSecrets` so that you can use a private images registry. | `[]`
 `serviceAccount.create` | Specifies whether a service account should be created. | `true`
 `serviceAccount.annotations` | Annotations to add to the service account. | `{}`

charts/capsule/templates/post-install-job.yaml

@@ -25,6 +25,10 @@ spec:
         app.kubernetes.io/instance: {{ .Release.Name | quote }}
         helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
     spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
       restartPolicy: Never
       containers:
       - name: post-install-job

charts/capsule/templates/pre-delete-job.yaml

@@ -26,6 +26,10 @@ spec:
         app.kubernetes.io/instance: {{ .Release.Name | quote }}
         helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
     spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
       restartPolicy: Never
       containers:
         - name: pre-delete-job

charts/capsule/templates/validatingwebhookconfiguration.yaml

@@ -163,7 +163,7 @@ webhooks:
     caBundle: Cg==
     service:
       name: {{ include "capsule.fullname" . }}-webhook-service
-      namespace: capsule-system
+      namespace: {{ .Release.Namespace }}
       path: /persistentvolumeclaims
   failurePolicy: {{ .Values.webhooks.persistentvolumeclaims.failurePolicy }}
   name: pvc.capsule.clastix.io
@@ -240,3 +240,29 @@ webhooks:
       scope: '*'
   sideEffects: None
   timeoutSeconds: {{ .Values.validatingWebhooksTimeoutSeconds }}
+- admissionReviewVersions:
+    - v1
+    - v1beta1
+  clientConfig:
+    caBundle: Cg==
+    service:
+      name: {{ include "capsule.fullname" . }}-webhook-service
+      namespace: {{ .Release.Namespace }}
+      path: /nodes
+      port: 443
+  failurePolicy: {{ .Values.webhooks.nodes.failurePolicy }}
+  name: nodes.capsule.clastix.io
+  matchPolicy: Exact
+  namespaceSelector: {}
+  objectSelector: {}
+  rules:
+    - apiGroups:
+        - ""
+      apiVersions:
+        - v1
+      operations:
+        - UPDATE
+      resources:
+        - nodes
+  sideEffects: None
+  timeoutSeconds: {{ .Values.validatingWebhooksTimeoutSeconds }}

charts/capsule/values.yaml

@@ -123,5 +123,7 @@ webhooks:
       matchExpressions:
         - key: capsule.clastix.io/tenant
           operator: Exists
+  nodes:
+    failurePolicy: Fail
 mutatingWebhooksTimeoutSeconds: 30
 validatingWebhooksTimeoutSeconds: 30

config/install.yaml

@@ -1411,7 +1411,7 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
-        image: quay.io/clastix/capsule:v0.1.1-rc0
+        image: quay.io/clastix/capsule:v0.1.1-rc1
         imagePullPolicy: IfNotPresent
         name: manager
         ports:
@@ -1582,6 +1582,29 @@ webhooks:
     - networkpolicies
     scope: Namespaced
   sideEffects: None
+- admissionReviewVersions:
+  - v1
+  clientConfig:
+    service:
+      name: capsule-webhook-service
+      namespace: capsule-system
+      path: /nodes
+  failurePolicy: Fail
+  name: nodes.capsule.clastix.io
+  namespaceSelector:
+    matchExpressions:
+    - key: capsule.clastix.io/tenant
+      operator: Exists
+  rules:
+  - apiGroups:
+    - ""
+    apiVersions:
+    - v1
+    operations:
+    - UPDATE
+    resources:
+    - nodes
+  sideEffects: None
 - admissionReviewVersions:
   - v1
   clientConfig:

config/manager/kustomization.yaml

@@ -7,4 +7,4 @@ kind: Kustomization
 images:
 - name: controller
   newName: quay.io/clastix/capsule
-  newTag: v0.1.1-rc0
+  newTag: v0.1.1-rc1

config/webhook/manifests.yaml

@@ -118,6 +118,25 @@ webhooks:
     resources:
     - networkpolicies
   sideEffects: None
+- admissionReviewVersions:
+  - v1
+  clientConfig:
+    service:
+      name: webhook-service
+      namespace: system
+      path: /nodes
+  failurePolicy: Fail
+  name: nodes.capsule.clastix.io
+  rules:
+  - apiGroups:
+    - ""
+    apiVersions:
+    - v1
+    operations:
+    - UPDATE
+    resources:
+    - nodes
+  sideEffects: None
 - admissionReviewVersions:
   - v1
   clientConfig:

config/webhook/patch_ns_selector.yaml

@@ -34,6 +34,12 @@
     matchExpressions:
       - key: capsule.clastix.io/tenant
         operator: Exists
+- op: add
+  path: /webhooks/7/namespaceSelector
+  value:
+    matchExpressions:
+      - key: capsule.clastix.io/tenant
+        operator: Exists
 - op: add
   path: /webhooks/0/rules/0/scope
   value: Namespaced
@@ -43,12 +49,12 @@
 - op: add
   path: /webhooks/3/rules/0/scope
   value: Namespaced
-- op: add
-  path: /webhooks/4/rules/0/scope
-  value: Namespaced
 - op: add
   path: /webhooks/5/rules/0/scope
   value: Namespaced
 - op: add
   path: /webhooks/6/rules/0/scope
   value: Namespaced
+- op: add
+  path: /webhooks/7/rules/0/scope
+  value: Namespaced

controllers/secret/ca.go

@@ -35,7 +35,7 @@ type CAReconciler struct {
 
 func (r *CAReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
-		For(&corev1.Secret{}, forOptionPerInstanceName(caSecretName)).
+		For(&corev1.Secret{}, forOptionPerInstanceName(CASecretName)).
 		Complete(r)
 }
 

controllers/secret/const.go

@@ -7,6 +7,6 @@ const (
 	certSecretKey       = "tls.crt"
 	privateKeySecretKey = "tls.key"
 
-	caSecretName  = "capsule-ca"
+	CASecretName  = "capsule-ca"
 	tlsSecretName = "capsule-tls"
 )

controllers/secret/reconciler.go

@@ -22,10 +22,10 @@ func getCertificateAuthority(client client.Client, namespace string) (ca cert.CA
 
 	err = client.Get(context.TODO(), types.NamespacedName{
 		Namespace: namespace,
-		Name:      caSecretName,
+		Name:      CASecretName,
 	}, instance)
 	if err != nil {
-		return nil, fmt.Errorf("missing secret %s, cannot reconcile", caSecretName)
+		return nil, fmt.Errorf("missing secret %s, cannot reconcile", CASecretName)
 	}
 
 	if instance.Data == nil {

controllers/servicelabels/endpoint_slices.go

@@ -14,8 +14,8 @@ type EndpointSlicesLabelsReconciler struct {
 	abstractServiceLabelsReconciler
 
 	Log          logr.Logger
-	VersionMinor int
-	VersionMajor int
+	VersionMinor uint
+	VersionMajor uint
 }
 
 func (r *EndpointSlicesLabelsReconciler) SetupWithManager(mgr ctrl.Manager) error {

controllers/tenant/manager.go

@@ -68,28 +68,22 @@ func (r Manager) Reconcile(ctx context.Context, request ctrl.Request) (result ct
 		return
 	}
 
-	if instance.Spec.NetworkPolicies != nil {
-		r.Log.Info("Starting processing of Network Policies", "items", len(instance.Spec.NetworkPolicies.Items))
-		if err = r.syncNetworkPolicies(instance); err != nil {
-			r.Log.Error(err, "Cannot sync NetworkPolicy items")
-			return
-		}
+	r.Log.Info("Starting processing of Network Policies")
+	if err = r.syncNetworkPolicies(instance); err != nil {
+		r.Log.Error(err, "Cannot sync NetworkPolicy items")
+		return
 	}
 
-	if instance.Spec.LimitRanges != nil {
-		r.Log.Info("Starting processing of Limit Ranges", "items", len(instance.Spec.LimitRanges.Items))
-		if err = r.syncLimitRanges(instance); err != nil {
-			r.Log.Error(err, "Cannot sync LimitRange items")
-			return
-		}
+	r.Log.Info("Starting processing of Limit Ranges", "items", len(instance.Spec.LimitRanges.Items))
+	if err = r.syncLimitRanges(instance); err != nil {
+		r.Log.Error(err, "Cannot sync LimitRange items")
+		return
 	}
 
-	if instance.Spec.ResourceQuota != nil {
-		r.Log.Info("Starting processing of Resource Quotas", "items", len(instance.Spec.ResourceQuota.Items))
-		if err = r.syncResourceQuotas(instance); err != nil {
-			r.Log.Error(err, "Cannot sync ResourceQuota items")
-			return
-		}
+	r.Log.Info("Starting processing of Resource Quotas", "items", len(instance.Spec.ResourceQuota.Items))
+	if err = r.syncResourceQuotas(instance); err != nil {
+		r.Log.Error(err, "Cannot sync ResourceQuota items")
+		return
 	}
 
 	r.Log.Info("Ensuring additional RoleBindings for owner")

docs/.gitignore

@@ -0,0 +1,8 @@
+*.log
+.cache
+.DS_Store
+src/.temp
+node_modules
+dist
+.env
+.env.*

docs/README.md

@@ -0,0 +1,12 @@
+# Capsule Documentation
+
+1. Ensure to have [`yarn`](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) installed in your path.
+2. `yarn install`
+
+## Local development
+
+```shell
+yarn develop
+```
+
+This will create a local webserver listening on `localhost:8080` with hot-reload of your local changes.

docs/content/contributing/development.md

@@ -0,0 +1,394 @@
+# Capsule Development
+
+## Prerequisites
+
+Make sure you have these tools installed:
+
+- [Go 1.16+](https://golang.org/dl/)
+- [Operator SDK 1.7.2+](https://github.com/operator-framework/operator-sdk), or [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder)
+- [KinD](https://github.com/kubernetes-sigs/kind) or [k3d](https://k3d.io/), with `kubectl`
+- [ngrok](https://ngrok.com/) (if you want to run locally with remote Kubernetes)
+- [golangci-lint](https://github.com/golangci/golangci-lint)
+- OpenSSL
+
+## Setup a Kubernetes Cluster
+
+A lightweight Kubernetes within your laptop can be very handy for Kubernetes-native development like Capsule.
+
+### By `k3d`
+
+```shell
+# Install K3d cli by brew in Mac, or your preferred way
+$ brew install k3d
+
+# Export your laptop's IP, e.g. retrieving it by: ifconfig
+# Do change this IP to yours
+$ export LAPTOP_HOST_IP=192.168.10.101
+
+# Spin up a bare minimum cluster
+# Refer to here for more options: https://k3d.io/v4.4.8/usage/commands/k3d_cluster_create/
+$ k3d cluster create k3s-capsule --servers 1 --agents 1 --no-lb --k3s-server-arg --tls-san=${LAPTOP_HOST_IP}
+
+# Get Kubeconfig 
+$ k3d kubeconfig get k3s-capsule > /tmp/k3s-capsule && export KUBECONFIG="/tmp/k3s-capsule"
+
+# This will create a cluster with 1 server and 1 worker node
+$ kubectl get nodes
+NAME                       STATUS   ROLES                  AGE     VERSION
+k3d-k3s-capsule-server-0   Ready    control-plane,master   2m13s   v1.21.2+k3s1
+k3d-k3s-capsule-agent-0    Ready    <none>                 2m3s    v1.21.2+k3s1
+
+# Or 2 Docker containers if you view it from Docker perspective
+$ docker ps
+CONTAINER ID   IMAGE                      COMMAND                  CREATED          STATUS          PORTS                     NAMES
+5c26ad840c62   rancher/k3s:v1.21.2-k3s1   "/bin/k3s agent"         53 seconds ago   Up 45 seconds                             k3d-k3s-capsule-agent-0
+753998879b28   rancher/k3s:v1.21.2-k3s1   "/bin/k3s server --t…"   53 seconds ago   Up 51 seconds   0.0.0.0:49708->6443/tcp   k3d-k3s-capsule-server-0
+```
+
+### By `kind`
+
+```shell
+# # Install kind cli by brew in Mac, or your preferred way
+$ brew install kind
+
+# Prepare a kind config file with necessary customization
+$ cat > kind.yaml <<EOF
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+networking:
+  apiServerAddress: "0.0.0.0"
+nodes:
+- role: control-plane
+  kubeadmConfigPatches:
+  - |
+    kind: ClusterConfiguration
+    metadata:
+      name: config
+    apiServer:
+      certSANs:
+      - localhost
+      - 127.0.0.1
+      - kubernetes
+      - kubernetes.default.svc
+      - kubernetes.default.svc.cluster.local
+      - kind
+      - 0.0.0.0
+      - ${LAPTOP_HOST_IP}
+- role: worker
+EOF
+
+# Spin up a bare minimum cluster with 1 master 1 worker node
+$ kind create cluster --name kind-capsule --config kind.yaml
+
+# This will create a cluster with 1 server and 1 worker node
+$ kubectl get nodes
+NAME                         STATUS   ROLES                  AGE   VERSION
+kind-capsule-control-plane   Ready    control-plane,master   84s   v1.21.1
+kind-capsule-worker          Ready    <none>                 56s   v1.21.1
+
+# Or 2 Docker containers if you view it from Docker perspective
+$ docker ps
+CONTAINER ID   IMAGE                  COMMAND                  CREATED              STATUS              PORTS                     NAMES
+7b329fd3a838   kindest/node:v1.21.1   "/usr/local/bin/entr…"   About a minute ago   Up About a minute   0.0.0.0:54894->6443/tcp   kind-capsule-control-plane
+7d50f1633555   kindest/node:v1.21.1   "/usr/local/bin/entr…"   About a minute ago   Up About a minute                             kind-capsule-worker
+```
+
+## Fork, build, and deploy Capsule
+
+The `fork-clone-contribute-pr` flow is common for contributing to OSS projects like Kubernetes and Capsule.
+
+Let's assume you've forked it into your GitHub namespace, say `myuser`, and then you can clone it with Git protocol.
+Do remember to change the `myuser` to yours.
+
+```shell
+$ git clone git@github.com:myuser/capsule.git && cd capsule
+```
+
+It's a good practice to add the upsteam as the remote too so we can easily fetch and merge the upstream to our fork:
+
+```shell
+$ git remote add upstream https://github.com/clastix/capsule.git
+$ git remote -vv
+origin	git@github.com:myuser/capsule.git (fetch)
+origin	git@github.com:myuser/capsule.git (push)
+upstream	https://github.com/clastix/capsule.git (fetch)
+upstream	https://github.com/clastix/capsule.git (push)
+```
+
+Build and deploy:
+
+```shell
+# Download the project dependencies
+$ go mod download
+
+# Build the Capsule image
+$ make docker-build
+
+# Retrieve the built image version
+$ export CAPSULE_IMAGE_VESION=`docker images --format '{{.Tag}}' quay.io/clastix/capsule`
+
+# If k3s, load the image into cluster by
+$ k3d image import --cluster k3s-capsule capsule quay.io/clastix/capsule:${CAPSULE_IMAGE_VESION}
+# If Kind, load the image into cluster by
+$ kind load docker-image --name kind-capsule quay.io/clastix/capsule:${CAPSULE_IMAGE_VESION}
+
+# deploy all the required manifests
+# Note: 1) please retry if you saw errors; 2) if you want to clean it up first, run: make remove
+$ make deploy
+
+# Make sure the controller is running
+$ kubectl get pod -n capsule-system
+NAME                                          READY   STATUS    RESTARTS   AGE
+capsule-controller-manager-5c6b8445cf-566dc   1/1     Running   0          23s
+
+# Check the logs if needed
+$ kubectl -n capsule-system logs --all-containers -l control-plane=controller-manager
+
+# You may have a try to deploy a Tenant too to make sure it works end to end
+$ kubectl apply -f - <<EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  owners:
+  - name: alice
+    kind: User
+  - name: system:serviceaccount:capsule-system:default
+    kind: ServiceAccount
+EOF
+
+# There shouldn't be any errors and you should see the newly created tenant
+$ kubectl get tenants
+NAME   STATE    NAMESPACE QUOTA   NAMESPACE COUNT   NODE SELECTOR   AGE
+oil    Active                     0                                 14s
+```
+
+If you want to test namespace creation or such stuff, make sure to use impersonation:
+
+```sh
+$ kubectl ... --as system:serviceaccount:capsule-system:default --as-group capsule.clastix.io
+```
+
+As of now, a complete Capsule environment has been set up in `kind`- or `k3d`-powered cluster, and the `capsule-controller-manager` is running as a deployment serving as:
+
+- The reconcilers for CRDs and;
+- A series of webhooks
+
+## Setup the development environment
+
+During development, we prefer that the code is running within our IDE locally, instead of running as the normal Pod(s) within the Kubernetes cluster.
+
+Such a setup can be illustrated as below diagram:
+
+![Development Env](./assets/dev-env.png)
+
+To achieve that, there are some necessary steps we need to walk through, which have been made as a `make` target within our `Makefile`.
+
+So the TL;DR answer is:
+
+```shell
+# If you haven't installed or run `make deploy` before, do it first
+# Note: please retry if you saw errors
+$ make deploy
+
+# To retrieve your laptop's IP and execute `make dev-setup` to setup dev env
+# For example: LAPTOP_HOST_IP=192.168.10.101 make dev-setup
+$ LAPTOP_HOST_IP="<YOUR_LAPTOP_IP>" make dev-setup
+```
+
+This is a very common setup for typical Kubernetes Operator development so we'd better walk them through with more details here.
+
+1. Scaling down the deployed Pod(s) to 0
+
+We need to scale the existing replicas of `capsule-controller-manager` to 0 to avoid reconciliation competition between the Pod(s) and the code running outside of the cluster, in our preferred IDE for example.
+
+```shell
+$ kubectl -n capsule-system scale deployment capsule-controller-manager --replicas=0
+deployment.apps/capsule-controller-manager scaled
+```
+
+2. Preparing TLS certificate for the webhooks
+
+Running webhooks requires TLS, we can prepare the TLS key pair in our development env to handle HTTPS requests.
+
+```shell
+# Prepare a simple OpenSSL config file
+# Do remember to export LAPTOP_HOST_IP before running this command
+$ cat > _tls.cnf <<EOF
+[ req ]
+default_bits       = 4096
+distinguished_name = req_distinguished_name
+req_extensions     = req_ext
+[ req_distinguished_name ]
+countryName                = SG
+stateOrProvinceName        = SG
+localityName               = SG
+organizationName           = CAPSULE
+commonName                 = CAPSULE
+[ req_ext ]
+subjectAltName = @alt_names
+[alt_names]
+IP.1   = ${LAPTOP_HOST_IP}
+EOF
+
+# Create this dir to mimic the Pod mount point
+$ mkdir -p /tmp/k8s-webhook-server/serving-certs
+
+# Generate the TLS cert/key under /tmp/k8s-webhook-server/serving-certs
+$ openssl req -newkey rsa:4096 -days 3650 -nodes -x509 \
+  -subj "/C=SG/ST=SG/L=SG/O=CAPSULE/CN=CAPSULE" \
+  -extensions req_ext \
+  -config _tls.cnf \
+  -keyout /tmp/k8s-webhook-server/serving-certs/tls.key \
+  -out /tmp/k8s-webhook-server/serving-certs/tls.crt
+
+# Clean it up
+$ rm -f _tls.cnf
+```
+
+3. Patching the Webhooks
+
+By default, the webhooks will be registered with the services, which will route to the Pods, inside the cluster.
+
+We need to _delegate_ the controllers' and webbooks' services to the code running in our IDE by patching the `MutatingWebhookConfiguration` and `ValidatingWebhookConfiguration`.
+
+```shell
+# Export your laptop's IP with the 9443 port exposed by controllers/webhooks' services
+$ export WEBHOOK_URL="https://${LAPTOP_HOST_IP}:9443"
+
+# Export the cert we just generated as the CA bundle for webhook TLS
+$ export CA_BUNDLE=`openssl base64 -in /tmp/k8s-webhook-server/serving-certs/tls.crt | tr -d '\n'`
+
+# Patch the MutatingWebhookConfiguration webhook
+$ kubectl patch MutatingWebhookConfiguration capsule-mutating-webhook-configuration \
+    --type='json' -p="[\
+      {'op': 'replace', 'path': '/webhooks/0/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/mutate-v1-namespace-owner-reference\",'caBundle':\"${CA_BUNDLE}\"}}\
+    ]"
+
+# Verify it if you want
+$ kubectl get MutatingWebhookConfiguration capsule-mutating-webhook-configuration -o yaml
+
+# Patch the ValidatingWebhookConfiguration webhooks
+# Note: there is a list of validating webhook endpoints, not just one
+$ kubectl patch ValidatingWebhookConfiguration capsule-validating-webhook-configuration \
+    --type='json' -p="[\
+      {'op': 'replace', 'path': '/webhooks/0/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/cordoning\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/1/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/ingresses\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/2/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/namespaces\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/3/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/networkpolicies\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/4/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/pods\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/5/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/persistentvolumeclaims\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/6/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/services\",'caBundle':\"${CA_BUNDLE}\"}},\
+      {'op': 'replace', 'path': '/webhooks/7/clientConfig', 'value':{'url':\"${WEBHOOK_URL}/tenants\",'caBundle':\"${CA_BUNDLE}\"}}\
+    ]"
+
+# Verify it if you want
+$ kubectl get ValidatingWebhookConfiguration capsule-validating-webhook-configuration -o yaml
+```
+
+## Run Capsule outside the cluster
+
+Now we can run Capsule controllers with webhooks outside of the Kubernetes cluster:
+
+```shell
+$ export NAMESPACE=capsule-system && export TMPDIR=/tmp/
+$ go run .
+```
+
+To verify that, we can open a new console and create a new Tenant:
+
+```shell
+$ kubectl apply -f - <<EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: gas
+spec:
+  owners:
+  - name: alice
+    kind: User
+EOF
+```
+
+We should see output and logs in the `make run` console.
+
+Now it's time to work through our familiar inner loop for development in our preferred IDE. For example, if you're using [Visual Studio Code](https://code.visualstudio.com), this `launch.json` file can be a good start.
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}",
+            "args": [
+                "--zap-encoder=console",
+                "--zap-log-level=debug",
+                "--configuration-name=capsule-default"
+            ],
+            "env": {
+                "NAMESPACE": "capsule-system",
+                "TMPDIR": "/tmp/"
+            }
+        }
+    ]
+}
+```
+
+## Debug Capsule Proxy locally
+
+This section helps new contributors to locally run and debug `capsule-proxy` in _out or cluster_ mode:
+
+1. You need to run a kind cluster and find the endpoint port of `kind-control-plane` using `docker ps`:
+
+```bash
+❯ docker ps
+CONTAINER ID   IMAGE                  COMMAND                  CREATED          STATUS          PORTS                       NAMES
+88432e392adb   kindest/node:v1.20.2   "/usr/local/bin/entr…"   32 seconds ago   Up 28 seconds   127.0.0.1:64582->6443/tcp   kind-control-plane
+```
+
+2. You need to generate TLS cert keys for localhost, you can use [mkcert](https://github.com/FiloSottile/mkcert):
+
+```bash
+> cd /tmp
+> mkcert localhost
+> ls
+localhost-key.pem localhost.pem
+```
+
+3. Run the proxy with the following options
+
+```bash
+go run main.go \
+    --ssl-cert-path=/tmp/localhost.pem \
+    --ssl-key-path=/tmp/localhost-key.pem \
+    --enable-ssl=true \
+    --kubeconfig=<YOUR KUBERNETES CONFIGURATION FILE>
+```
+
+5. Edit the `KUBECONFIG` file (you should make a copy and work on it) as follows:
+- Find the section of your cluster
+- replace the server path with `https://127.0.0.1:9001`
+- replace the certificate-authority-data path with the content of your rootCA.pem file. (if you use mkcert, you'll find with `cat "$(mkcert -CAROOT)/rootCA.pem"|base64|tr -d '\n'`)
+
+6. Now you should be able to run kubectl using the proxy!
+
+## Debug Capsule Proxy remotely
+
+In some cases, you would need to debug the in-cluster mode and [`delve`](https://github.com/go-delve/delve) plays a big role here.
+
+1. build the Docker image with `delve` issuing `make dlv-build`
+2. with the `quay.io/clastix/capsule-proxy:dlv` produced Docker image, publish it or load it to your [KinD](https://github.com/kubernetes-sigs/kind) instance (`kind load docker-image --name capsule --nodes capsule-control-plane quay.io/clastix/capsule-proxy:dlv`)
+3. change the Deployment image using `kubectl edit` or `kubectl set image deployment/capsule-proxy capsule-proxy=quay.io/clastix/capsule-proxy:dlv`
+4. wait for the image rollout (`kubectl -n capsule-system rollout status deployment/capsule-proxy`)
+5. perform the port-forwarding with `kubectl -n capsule-system port-forward $(kubectl -n capsule-system get pods -l app.kubernetes.io/name=capsule-proxy --output name) 2345:2345`
+6. connect using your `delve` options
+
+> _Nota Bene_: the application could be killed by the Liveness Probe since delve will wait for the debugger connection before starting it.
+> Feel free to edit and remove the probes to avoid this kind of issue.
+
+Please refer to [contributing](/docs/contributing) for more details while contributing.

docs/content/contributing/governance.md

@@ -0,0 +1,22 @@
+# Project Governance
+
+This document lays out the guidelines under which the Capsule project will be governed.
+The goal is to make sure that the roles and responsibilities are well defined and clarify how decisions are made.
+
+## Roles
+
+In the context of Capsule project, we consider the following roles:
+
+* __Users__: everyone using Capsule, typically willing to provide feedback by proposing features and/or filing issues.
+
+* __Contributors__: everyone contributing code, documentation, examples, tests, and participating in feature proposals as well as design discussions.
+
+* __Maintainers__: are responsible for engaging with and assisting contributors to iterate on the contributions until it reaches acceptable quality. Maintainers can decide whether the contributions can be accepted into the project or rejected.
+
+## Release Management
+
+The release process will be governed by Maintainers.
+
+## Roadmap Planning
+
+Maintainers will share roadmap and release versions as milestones in GitHub. 

docs/content/contributing/guidelines.md

@@ -0,0 +1,111 @@
+# Contributing Guidelines
+
+Thank you for your interest in contributing to Capsule. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
+
+Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.
+
+## Pull Requests
+
+Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
+
+1. You are working against the latest source on the *master* branch.
+1. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
+1. You open an issue to discuss any significant work: we would hate for your time to be wasted.
+
+To send us a pull request, please:
+
+1. Fork the repository.
+1. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it
+   will be hard for us to focus on your change.
+1. Ensure local tests pass.
+1. Commit to your fork using clear commit messages.
+1. Send us a pull request, answering any default questions in the pull request interface.
+1. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+
+GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
+[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+Make sure to keep Pull Requests small and functional to make them easier to review, understand, and look up in commit history. This repository uses "Squash and Commit" to keep our history clean and make it easier to revert changes based on PR.
+
+Adding the appropriate documentation, unit tests and e2e tests as part of a feature is the responsibility of the
+feature owner, whether it is done in the same Pull Request or not.
+
+All the Pull Requests must refer to an already open issue: this is the first phase to contribute also for informing maintainers about the issue.
+
+## Commits
+
+Commit's first line should not exceed 50 columns.
+
+A commit description is welcomed to explain more the changes: just ensure
+to put a blank line and an arbitrary number of maximum 72 characters long
+lines, at most one blank line between them.
+
+Please, split changes into several and documented small commits: this will help us to perform a better review. Commits must follow the Conventional Commits Specification, a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with Semantic Versioning, by describing the features, fixes, and breaking changes made in commit messages. See [Conventional Commits Specification](https://www.conventionalcommits.org) to learn about Conventional Commits.
+
+> In case of errors or need of changes to previous commits,
+> fix them squashing to make changes atomic.
+
+## Code convention
+
+Capsule is written in Golang. The changes must follow the Pull Request method where a _GitHub Action_ will
+check the `golangci-lint`, so ensure your changes respect the coding standard.
+
+### golint
+
+You can easily check them issuing the _Make_ recipe `golint`.
+
+```
+# make golint
+golangci-lint run -c .golangci.yml
+```
+
+> Enabled linters and related options are defined in the [.golanci.yml file](https://github.com/clastix/capsule/blob/master/.golangci.yml)
+
+### goimports
+
+Also, the Go import statements must be sorted following the best practice:
+
+```
+<STANDARD LIBRARY>
+
+<EXTERNAL PACKAGES>
+
+<LOCAL PACKAGES>
+```
+
+To help you out you can use the _Make_ recipe `goimports`
+
+```
+# make goimports
+goimports -w -l -local "github.com/clastix/capsule" .
+```
+
+## Finding contributions to work on
+Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the
+default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted'
+and 'good first issue' issues are a great place to start.
+
+## Design Docs
+
+A contributor proposes a design with a PR on the repository to allow for revisions and discussions.
+If a design needs to be discussed before formulating a document for it, make use of GitHub Discussions to
+involve the community on the discussion.
+
+## GitHub Issues
+
+GitHub Issues are used to file bugs, work items, and feature requests with actionable items/issues.
+
+When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
+
+* A reproducible test case or series of steps
+* The version of the code being used
+* Any modifications you've made relevant to the bug
+* Anything unusual about your environment or deployment
+
+## Miscellanea
+
+Please, add a new single line at end of any file as the current coding style.
+
+## Licensing
+
+See the [LICENSE](https://github.com/clastix/capsule/blob/master/LICENSE) file for our project's licensing. We can ask you to confirm the licensing of your contribution.

docs/content/contributing/index.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Guidelines for community contribution.

docs/content/general/getting-started.md

@@ -1,7 +1,9 @@
 # Getting started
+
 Thanks for giving Capsule a try.
 
 ## Installation
+
 Make sure you have access to a Kubernetes cluster as administrator.
 
 There are two ways to install Capsule:
@@ -10,6 +12,7 @@ There are two ways to install Capsule:
 * Use the [Capsule Helm Chart](https://github.com/clastix/capsule/blob/master/charts/capsule/README.md)
 
 ### Install with the single YAML file installer
+
 Ensure you have `kubectl` installed in your `PATH`. Clone this repository and move to the repo folder:
 
 ```
@@ -19,9 +22,11 @@ $ kubectl apply -f https://raw.githubusercontent.com/clastix/capsule/master/conf
 It will install the Capsule controller in a dedicated namespace `capsule-system`.
 
 ### Install with Helm Chart
+
 Please, refer to the instructions reported in the Capsule Helm Chart [README](https://github.com/clastix/capsule/blob/master/charts/capsule/README.md). 
 
-# Create your first Tenant
+## Create your first Tenant
+
 In Capsule, a _Tenant_ is an abstraction to group multiple namespaces in a single entity within a set of boundaries defined by the Cluster Administrator. The tenant is then assigned to a user or group of users who is called _Tenant Owner_.
 
 Capsule defines a Tenant as Custom Resource with cluster scope.
@@ -49,7 +54,8 @@ NAME   STATE    NAMESPACE QUOTA   NAMESPACE COUNT   NODE SELECTOR   AGE
 oil    Active                     0                                 10s
 ```
 
-## Tenant owners
+## Login as Tenant Owner
+
 Each tenant comes with a delegated user or group of users acting as the tenant admin. In the Capsule jargon, this is called the _Tenant Owner_. Other users can operate inside a tenant with different levels of permissions and authorizations assigned directly by the Tenant Owner.
 
 Capsule does not care about the authentication strategy used in the cluster and all the Kubernetes methods of [authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/) are supported. The only requirement to use Capsule is to assign tenant users to the group defined by `--capsule-user-group` option, which defaults to `capsule.clastix.io`.
@@ -68,7 +74,7 @@ Users authenticated through an _OIDC token_ must have in their token:
 ]
 ```
 
-The [hack/create-user.sh](../../hack/create-user.sh) can help you set up a dummy `kubeconfig` for the `alice` user acting as owner of a tenant called `oil`
+The [hack/create-user.sh](https://github.com/clastix/capsule/blob/master/hack/create-user.sh) can help you set up a dummy `kubeconfig` for the `alice` user acting as owner of a tenant called `oil`
 
 ```bash
 ./hack/create-user.sh alice oil
@@ -79,32 +85,36 @@ kubeconfig file is: alice-oil.kubeconfig
 to use it as alice export KUBECONFIG=alice-oil.kubeconfig
 ```
 
-Log as tenant owner
+Login as tenant owner
 
 ```
 $ export KUBECONFIG=alice-oil.kubeconfig
 ```
 
-and create a couple of new namespaces
+## Create namespaces
+
+As tenant owner, you can create namespaces:
 
 ```
 $ kubectl create namespace oil-production
 $ kubectl create namespace oil-development
 ```
 
-As user `alice` you can operate with fully admin permissions:
+And operate with fully admin permissions:
 
 ```
 $ kubectl -n oil-development run nginx --image=docker.io/nginx 
 $ kubectl -n oil-development get pods
 ```
 
-but limited to only your namespaces:
+## Limiting access
+
+Tenant Owners have full administrative permissions limited to only the namespaces in the assigned tenant. They can create any namespaced resource in their namespaces but they do not have access to cluster resources or resources belonging to other tenants they do not own:
 
 ```
 $ kubectl -n kube-system get pods
-Error from server (Forbidden): pods is forbidden: User "alice" cannot list resource "pods" in API group "" in the namespace "kube-system"
+Error from server (Forbidden): pods is forbidden:
+User "alice" cannot list resource "pods" in API group "" in the namespace "kube-system"
 ```
 
-# What’s next
-The Tenant Owners have full administrative permissions limited to only the namespaces in the assigned tenant. However, their permissions can be controlled by the Cluster Admin by setting rules and policies on the assigned tenant. See the [use cases](./use-cases/overview.md) page for more getting more cool things you can do with Capsule.
+See the [tutorial](/docs/general/tutorial) for getting more cool things you can do with Capsule.

docs/content/general/index.md

@@ -0,0 +1,2 @@
+# Documentation
+General documentation for Capsule Operator

docs/content/general/proxy.md

@@ -1,10 +1,8 @@
 # Capsule Proxy
 
-Capsule Proxy is an add-on for [Capsule](https://github.com/clastix/capsule), the operator providing multi-tenancy in Kubernetes.
+Capsule Proxy is an add-on for Capsule Operator addressing some RBAC issues when enabling multi-tenacy in Kubernetes since users cannot list the owned cluster-scoped resources.
 
-## The problem
-
-Kubernetes RBAC cannot list only the owned cluster-scoped resources since there are no ACL-filtered APIs. For example:
+For example:
 
 ```
 $ kubectl get namespaces
@@ -27,9 +25,6 @@ With **Capsule**, we took a different approach. As one of the key goals, we want
 
 ## How it works
 
-This project is an add-on of the main [Capsule](https://github.com/clastix/capsule) operator, so make sure you have a working instance of Caspule before attempting to install it.
-Use the `capsule-proxy` only if you want Tenant Owners to list their own Cluster-Scope resources.
-
 The `capsule-proxy` implements a simple reverse proxy that intercepts only specific requests to the APIs server and Capsule does all the magic behind the scenes.
 
 Current implementation filters the following requests:
@@ -44,19 +39,42 @@ All other requestes are proxied transparently to the APIs server, so no side-eff
 
 ## Installation
 
-The `capsule-proxy` can be deployed in standalone mode, e.g. running as a pod bridging any Kubernetes client to the APIs server.
-Optionally, it can be deployed as a sidecar container in the backend of a dashboard.
-Running outside a Kubernetes cluster is also viable, although a valid `KUBECONFIG` file must be provided, using the environment variable `KUBECONFIG` or the default file in `$HOME/.kube/config`.
+Capsule Proxy is an optional add-on of the main Capsule Operator, so make sure you have a working instance of Caspule before attempting to install it. Use the `capsule-proxy` only if you want Tenant Owners to list their own Cluster-Scope resources.
 
-An Helm Chart is available [here](./charts/capsule-proxy/README.md).
+The `capsule-proxy` can be deployed in standalone mode, e.g. running as a pod bridging any Kubernetes client to the APIs server. Optionally, it can be deployed as a sidecar container in the backend of a dashboard.
 
-## Does it work with kubectl?
+Running outside of a Kubernetes cluster is also viable, although a valid `KUBECONFIG` file must be provided, using the environment variable `KUBECONFIG` or the default file in `$HOME/.kube/config`.
 
-Yes, it works by intercepting all the requests from the `kubectl` client directed to the APIs server. It works with both users who use the TLS certificate authentication and those who use OIDC.
+A Helm Chart is available [here](https://github.com/clastix/capsule/blob/master/charts/capsule/README.md).
 
-## How RBAC is put in place?
+Depending on your environment, you can expose the `capsule-proxy` by:
 
-Each Tenant owner can have their capabilities managed pretty similar to a standard RBAC.
+- Ingress
+- NodePort Service
+- LoadBalance Service
+- HostPort
+- HostNetwork
+
+Here how it looks like when exposed through an Ingress Controller:
+
+```
+                +-----------+          +-----------+         +-----------+
+ kubectl ------>|:443       |--------->|:9001      |-------->|:6443      |
+                +-----------+          +-----------+         +-----------+
+                ingress-controller     capsule-proxy         kube-apiserver
+``` 
+
+## User Authentication
+
+The `capsule-proxy` intercepts all the requests from the `kubectl` client directed to the APIs Server. Users using a TLS client based authentication with certificate and key are able to talks with APIs Server since it is able to forward client certificates to the Kubernetes APIs server.
+
+It is possible to protect the `capsule-proxy` using a certificate provided by Let's Encrypt. Keep in mind that, in this way, the TLS termination will be executed by the Ingress Controller, meaning that the authentication based on client certificate will be withdrawn and not reversed to the upstream.
+
+If your prerequisite is exposing `capsule-proxy` using an Ingress, you must rely on the token-based authentication, for example OIDC or Bearer tokens. Users providing tokens are always able to reach the APIs Server.
+
+## Tenant Owner Authorization
+
+Each Tenant owner can have their capabilities managed pretty similar to a standard Kubernetes RBAC.
 
 ```yaml
 apiVersion: capsule.clastix.io/v1beta1
@@ -179,6 +197,19 @@ custom               custom.tls/provisioner   Delete          WaitForFirstConsum
 glusterfs            rook.io/glusterfs        Delete          WaitForFirstConsumer   false                  54m
 ```
 
+> The `name` label reflecting the resource name is mandatory, otherwise filtering of resources cannot be put in place
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  labels:
+    name: cephfs
+  name: cephfs
+provisioner: cephfs
+
+```
+
 ### Ingress Classes
 
 As for Storage Class, also Ingress Class can be enforced.
@@ -225,9 +256,26 @@ external-lb       example.com/external       IngressParameters.k8s.example.com/e
 internal-lb       example.com/internal       IngressParameters.k8s.example.com/internal-lb   15m
 ```
 
+> The `name` label reflecting the resource name is mandatory, otherwise filtering of resources cannot be put in place
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  labels:
+    name: external-lb
+  name: external-lb
+spec:
+  controller: example.com/ingress-controller
+  parameters:
+    apiGroup: k8s.example.com
+    kind: IngressParameters
+    name: external-lb
+```
+
 ### Priority Classes
 
-Allowed PriorityClasses assigned to a Tenant Owner can be enforced as follows.
+Allowed PriorityClasses assigned to a Tenant Owner can be enforced as follows:
 
 ```yaml
 apiVersion: capsule.clastix.io/v1beta1
@@ -239,12 +287,12 @@ spec:
   - kind: User
     name: alice
     proxySettings:
-    - kind: IngressClasses
+    - kind: PriorityClasses
       operations:
       - List
   priorityClasses:
     allowed:
-      - best-effort
+      - custom
     allowedRegex: "\\w+priority"
 ```
 
@@ -271,67 +319,30 @@ maxpriority               1000         false            18s
 minpriority               1000         false            18s
 ```
 
-### Storage/Ingress class and PriorityClass required label
-
-For Storage Class, Ingress Class and Priority Class resources, the `name` label reflecting the resource name is mandatory, otherwise filtering of resources cannot be put in place.
+> The `name` label reflecting the resource name is mandatory, otherwise filtering of resources cannot be put in place
 
 ```yaml
----
-apiVersion: storage.k8s.io/v1
-kind: StorageClass
-metadata:
-  labels:
-    name: my-storage-class
-  name: my-storage-class
-provisioner: org.tld/my-storage-class
----
-apiVersion: networking.k8s.io/v1
-kind: IngressClass
-metadata:
-  labels:
-    name: external-lb
-  name: external-lb
-spec:
-  controller: example.com/ingress-controller
-  parameters:
-    apiGroup: k8s.example.com
-    kind: IngressParameters
-    name: external-lb
----
 apiVersion: scheduling.k8s.io/v1
 kind: PriorityClass
 metadata:
   labels:
-    name: best-effort
-  name: best-effort
+    name: custom
+  name: custom
 value: 1000
 globalDefault: false
-description: "Priority class for best-effort Tenants"
+description: "Priority class for Tenants"
 ```
 
-## Does it work with kubectl?
-Yes, it works by intercepting all the requests from the `kubectl` client directed to the APIs server. It works with both users who use the TLS certificate authentication and those who use OIDC.
+## HTTP support
+Capsule proxy supports `https` and `http`, although the latter is not recommended, we understand that it can be useful for some use cases (i.e. development, working behind a TLS-terminated reverse proxy and so on). As the default behaviour is to work with `https`, we need to use the flag `--enable-ssl=false` if we really want to work under `http`.
 
-As tenant owner `alice`, you are able to use `kubectl` to create some namespaces:
-```
-$ kubectl --context alice-oidc@mycluster create namespace oil-production
-$ kubectl --context alice-oidc@mycluster create namespace oil-development
-$ kubectl --context alice-oidc@mycluster create namespace gas-marketing
+After having the `capsule-proxy` working under `http`, requests must provide authentication using an allowed Bearer Token.
+
+For example:
+
+```bash
+$ TOKEN=<type your TOKEN>
+$ curl -H "Authorization: Bearer $TOKEN" http://localhost:9001/api/v1/namespaces
 ```
 
-and list only those namespaces:
-```
-$ kubectl --context alice-oidc@mycluster get namespaces
-NAME                STATUS   AGE
-gas-marketing       Active   2m
-oil-development     Active   2m
-oil-production      Active   2m
-```
-
-# What’s next
-Have a fun with `capsule-proxy`:
-
-* [Standalone Installation](./standalone.md)
-* [Sidecar Installation](./sidecar.md)
-* [OIDC Authentication](./oidc-auth.md)
-* [Contributing](./contributing.md)
+> NOTE: `kubectl` will not work against a `http` server.

docs/content/general/references.md

@@ -1,19 +1,12 @@
 # Reference
 
-* [Custom Resource Definition](#customer-resource-definition)
-* [Capsule Configuration](#capsule-configuration)
-* [Capsule Permissions](#capsule-permissions)
-* [Admission Controllers](#admission-controller)
-* [Command Options](#command-options)
-* [Created Resources](#created-resources)
+Reference document for Capsule Operator configuration
 
 ## Custom Resource Definition
 
-Capsule operator uses a Custom Resources Definition (CRD) for _Tenants_. In Capsule, Tenants are cluster wide resources. You need cluster level permissions to work with tenants.
+Capsule operator uses a Custom Resources Definition (CRD) for _Tenants_. Tenants are cluster wide resources, so you need cluster level permissions to work with tenants. You can learn about tenant CRD by the `kubectl explain` command:
 
-You can learn about tenant CRD by the `kubectl explain` command:
-
-```command
+```
 kubectl explain tenant
 
 KIND:     Tenant
@@ -24,11 +17,15 @@ DESCRIPTION:
 
 FIELDS:
    apiVersion   <string>
-     APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info:
+     APIVersion defines the versioned schema of this representation of an object.
+     Servers should convert recognized schemas to the latest internal value,
+     and may reject unrecognized values. More info:
      https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
 
    kind <string>
-     Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info:
+     Kind is a string value representing the REST resource this object represents.
+     Servers may infer this from the endpoint the client submits requests to.
+     Cannot be updated. In CamelCase. More info:
      https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
 
    metadata     <Object>
@@ -44,7 +41,7 @@ FIELDS:
 
 For Tenant spec:
 
-```command
+```
 kubectl explain tenant.spec
 
 KIND:     Tenant
@@ -124,7 +121,7 @@ FIELDS:
 
 and Tenant status:
 
-```command
+```
 kubectl explain tenant.status
 KIND:     Tenant
 VERSION:  capsule.clastix.io/v1beta1
@@ -171,6 +168,7 @@ Upon installation using Kustomize or Helm, a `capsule-default` resource will be
 The reference to this configuration is managed by the CLI flag `--configuration-name`.  
 
 ## Capsule Permissions
+
 In the current implementation, the Capsule operator requires cluster admin permissions to fully operate. Make sure you deploy Capsule having access to the default `cluster-admin` ClusterRole.
 
 ## Admission Controllers
@@ -213,6 +211,7 @@ Option | Description | Default
 
 
 ## Created Resources
+
 Once installed, the Capsule operator creates the following resources in your cluster:
 
 ```

docs/content/guides/index.md

@@ -0,0 +1,2 @@
+# Guides
+Guides and tutorials on how to integrate Capsule in your Kubernetes environment. 

docs/content/guides/managed-kubernetes/aws-eks.md

@@ -1,8 +1,6 @@
 # Capsule on AWS EKS
 This is an example of how to install AWS EKS cluster and one user
-manged by Capsule.
-
-It is based on [Using IAM Groups to manage Kubernetes access](https://www.eksworkshop.com/beginner/091_iam-groups/intro/)
+manged by Capsule. It is based on [Using IAM Groups to manage Kubernetes access](https://www.eksworkshop.com/beginner/091_iam-groups/intro/)
 
 Create EKS cluster:
 
@@ -23,7 +21,7 @@ Create AWS User `alice` using CloudFormation, create AWS access files and
 kubeconfig for such user:
 
 ```bash
-cat > cf.yml << \EOF
+cat > cf.yml << EOF
 Parameters:
   ClusterName:
     Type: String
@@ -112,8 +110,6 @@ cat >> kubeconfig-alice.conf << EOF
 EOF
 ```
 
-----
-
 Export "admin" kubeconfig to be able to install Capsule:
 
 ```bash
@@ -134,15 +130,11 @@ kubectl apply -f https://raw.githubusercontent.com/clastix/capsule/master/config
 ```
 
 Based on the tenant configuration above the user `alice` should be able
-to create namespace...
-
-Switch to new terminal tab and try to create namespace as user `alice`:
+to create namespace. Switch to a new terminal and try to create a namespace as user `alice`:
 
 ```bash
 # Unset AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY if defined
 unset AWS_ACCESS_KEY_ID
 unset AWS_SECRET_ACCESS_KEY
 kubectl create namespace test --kubeconfig="kubeconfig-alice.conf"
-
-... do other commands allowed by Tenant configuration ...
-```
+```

docs/content/guides/managed-kubernetes/coaks.md

@@ -0,0 +1,3 @@
+# Capsule on Azure Kubernetes Service
+
+This reference implementation introduces the recommended starting (baseline) infrastructure architecture for implementing a multi-tenancy Azure AKS cluster using Capsule. See [CoAKS](https://github.com/clastix/coaks-baseline-architecture).

docs/content/guides/managed-kubernetes/overview.md

@@ -1,5 +1,5 @@
-# Capsule over Managed Kubernetes
-Capsule Operator can be easily installed on a Managed Kubernetes Service. Since in these services, you do not have access to the Kubernetes APIs Server, you should check with your service provider following pre-requisites:
+# Capsule on Managed Kubernetes
+Capsule Operator can be easily installed on a Managed Kubernetes Service. Since you do not have access to the Kubernetes APIs Server, you should check with the provider of the service:
 
 - the default `cluster-admin` ClusterRole is accessible 
 - the following Admission Webhooks are enabled on the APIs Server:
@@ -8,9 +8,3 @@ Capsule Operator can be easily installed on a Managed Kubernetes Service. Since
     - ResourceQuota
     - MutatingAdmissionWebhook
     - ValidatingAdmissionWebhook
-
-* [AWS EKS](./aws-eks.md)
-* CoAKS - Capsule over Azure Kubernetes Service
-* Google Cloud GKE
-* IBM Cloud
-* OVH

docs/content/guides/monitoring.md

@@ -1,8 +1,6 @@
 # Monitoring Capsule
 
-The Capsule dashboard allows you to track the health and performance of Capsule manager and tenants, with particular attention to resources saturation, server responses, and latencies.
-
-## Requirements
+The Capsule dashboard allows you to track the health and performance of Capsule manager and tenants, with particular attention to resources saturation, server responses, and latencies. Prometheus and Grafana are requirements for monitoring Capsule.
 
 ### Prometheus
 
@@ -18,8 +16,6 @@ Grafana is an open-source monitoring solution that offers a flexible way to gene
 
 To fastly deploy this monitoring stack, consider installing the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator).
 
----
-
 ## Quick Start
 
 The Capsule Helm [charts](https://github.com/clastix/capsule/tree/master/charts/capsule) allow you to automatically create Kubernetes minimum resources needed for the proper functioning of the dashboard:
@@ -48,31 +44,29 @@ Take a look at the Helm charts [README.md](https://github.com/clastix/capsule/bl
 
 Verify that the service monitor is working correctly through the Prometheus "targets" page :
 
-![Prometheus Targets](../assets/prometheus_targets.png)
+![Prometheus Targets](./assets/prometheus_targets.png)
 
 ### Deploy dashboard
 
 Simply upload [dashboard.json](https://github.com/clastix/capsule/blob/master/config/grafana/dashboard.json) file to Grafana through _Create_ -> _Import_,
 making sure to select the correct Prometheus data source:
 
-![Grafana Import](../assets/upload_json.png)
+![Grafana Import](./assets/upload_json.png)
 
 ## In-depth view
 
 ### Features
-* [Manager controllers](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#manager-controllers)
-* [Webhook error rate](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#webhook-error-rate)
-* [Webhook latency](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#webhook-latency)
-* [REST client latency](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#rest-client-latency)
-* [REST client error rate](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#rest-client-error-rate)
-* [Saturation](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#saturation)
-* [Workqueue](https://github.com/clastix/capsule/blob/master/docs/operator/monitoring.md#workqueue)
-
----
+* [Manager controllers](#manager-controllers)
+* [Webhook error rate](#webhook-error-rate)
+* [Webhook latency](#webhook-latency)
+* [REST client latency](#rest-client-latency)
+* [REST client error rate](#rest-client-error-rate)
+* [Saturation](#saturation)
+* [Workqueue](#workqueue)
 
 #### Manager controllers
 
-![Manager controllers](../assets/manager-controllers.png)
+![Manager controllers](./assets/manager-controllers.png)
 
 ##### Description
 
@@ -92,7 +86,7 @@ This section provides information about the medium time delay between manager cl
 
 #### Webhook error rate
 
-![Webhook error rate](../assets/webhook-error-rate.png)
+![Webhook error rate](./assets/webhook-error-rate.png)
 
 ##### Description
 
@@ -113,7 +107,7 @@ This section provides information about webhook requests response, mainly focusi
 
 #### Webhook latency
 
-![Webhook latency](../assets/webhook-latency.png)
+![Webhook latency](./assets/webhook-latency.png)
 
 ##### Description
 
@@ -134,7 +128,7 @@ This section provides information about the medium time delay between webhook tr
 
 #### REST client latency
 
-![REST client latency](../assets/rest-client-latency.png)
+![REST client latency](./assets/rest-client-latency.png)
 
 ##### Description
 
@@ -155,7 +149,7 @@ YMMV
 
 #### REST client error rate
 
-![REST client error rate](../assets/rest-client-error-rate.png)
+![REST client error rate](./assets/rest-client-error-rate.png)
 
 ##### Description
 
@@ -163,7 +157,7 @@ This section provides information about client total rest requests response per
 
 #### Saturation
 
-![Saturation](../assets/saturation.png)
+![Saturation](./assets/saturation.png)
 
 ##### Description
 
@@ -171,7 +165,7 @@ This section provides information about resources, giving a detailed picture of
 
 #### Workqueue
 
-![Workqueue](../assets/workqueue.png)
+![Workqueue](./assets/workqueue.png)
 
 ##### Description
 

docs/content/guides/oidc-auth.md

@@ -1,7 +1,9 @@
 # OIDC Authentication
-The `capsule-proxy` works with `kubectl` users with a token-based authentication, e.g. OIDC or Bearer Token. In the following example, we'll use Keycloak as OIDC server capable to provides JWT tokens.
+Capsule does not care about the authentication strategy used in the cluster and all the Kubernetes methods of authentication are supported. The only requirement to use Capsule is to assign tenant users to the the group defined by `userGroups` option in the `CapsuleConfiguration`, which defaults to `capsule.clastix.io`.
 
-### Configuring Keycloak
+In the following guide, we'll use [Keycloak](https://www.keycloak.org/) an Open Source Identity and Access Management server capable to authenticate users via OIDC and release JWT tokens as proof of authentication.
+
+## Configuring OIDC Server
 Configure Keycloak as OIDC server:
 
 - Add a realm called `caas`, or use any existing realm instead
@@ -67,7 +69,7 @@ The result will be like the following:
 }
 ```
 
-### Configuring Kubernetes API Server
+## Configuring Kubernetes API Server
 Configuring Kubernetes for OIDC Authentication requires adding several parameters to the API Server. Please, refer to the [documentation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) for details and examples. Most likely, your `kube-apiserver.yaml` manifest will looks like the following:
 
 ```yaml
@@ -84,7 +86,7 @@ spec:
     - --oidc-username-prefix=-
 ```
 
-### Configuring kubectl
+## Configuring kubectl
 There are two options to use `kubectl` with OIDC:
 
 - OIDC Authenticator
@@ -103,18 +105,20 @@ $ kubectl config set-credentials oidc \
     --auth-provider-arg=extra-scopes=groups
 ```
 
-To use the --token option:
+To use the `--token` option:
 ```
 $ kubectl config set-credentials oidc --token=${ID_TOKEN}
 ```
 
-Point the kubectl to the URL where the `capsule-proxy` service is reachable:
+Point the `kubectl` to the URL where the Kubernetes APIs Server is reachable:
 ```
 $ kubectl config set-cluster mycluster \
-    --server=https://kube.clastix.io \
+    --server=https://kube.clastix.io:6443 \
     --certificate-authority=~/.kube/ca.crt
 ```
 
+> If your APIs Server is reachable through the `capsule-proxy`, make sure to use the URL of the `capsule-proxy`.
+
 Create a new context for the OIDC authenticated users:
 ```
 $ kubectl config set-context alice-oidc@mycluster \
@@ -129,26 +133,4 @@ $ kubectl --context alice-oidc@mycluster create namespace oil-development
 $ kubectl --context alice-oidc@mycluster create namespace gas-marketing
 ```
 
-and list only those namespaces:
-```
-$ kubectl --context alice-oidc@mycluster get namespaces
-NAME                STATUS   AGE
-gas-marketing       Active   2m
-oil-development     Active   2m
-oil-production      Active   2m
-```
-
-When logged as cluster-admin power user you should be able to see all namespaces:
-```
-$ kubectl get namespaces
-NAME                STATUS   AGE
-default             Active   78d
-kube-node-lease     Active   78d
-kube-public         Active   78d
-kube-system         Active   78d
-gas-marketing       Active   2m
-oil-development     Active   2m
-oil-production      Active   2m
-```
-
-_Nota Bene_: once your `ID_TOKEN` expires, the `kubectl` OIDC Authenticator will attempt to refresh automatically your `ID_TOKEN` using the `REFRESH_TOKEN`, the `OIDC_CLIENT_ID` and the `OIDC_CLIENT_SECRET` storing the new values for the `REFRESH_TOKEN` and `ID_TOKEN` in your `kubeconfig` file. In case the OIDC uses a self signed CA certificate, make sure to specify it with the `idp-certificate-authority` option in your `kubeconfig` file, otherwise you'll not able to refresh the tokens. Once the `REFRESH_TOKEN` is expired, you will need to refresh tokens manually.
+> _Warning_: once your `ID_TOKEN` expires, the `kubectl` OIDC Authenticator will attempt to refresh automatically your `ID_TOKEN` using the `REFRESH_TOKEN`. In case the OIDC uses a self signed CA certificate, make sure to specify it with the `idp-certificate-authority` option in your `kubeconfig` file, otherwise you'll not able to refresh the tokens.

docs/content/guides/velero.md

@@ -1,8 +1,8 @@
-# Velero Backup Restoration
+# Tenants Backup and Restore with Velero
 
-Velero is a backup system that performs disaster recovery and migrates Kubernetes cluster resources and persistent volumes.
+[Velero](https://velero.io) is a backup and restore solution that performs disaster recovery and migrates Kubernetes cluster resources and persistent volumes.
 
-Using this 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.
+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.
 
 To avoid this problem you can use the script `velero-restore.sh` under the `hack/` folder.
 
@@ -20,8 +20,4 @@ Additionally, you can also specify a selected range of tenants to be restored:
 ./velero-restore.sh --tenant "gas oil" restore
 ```
 
-In this way, only the tenants **gas** and **oil** will be restored.
-
-# What's next
-
-See how Bill, the cluster admin, can deny wildcard hostnames to a Tenant. [Deny Wildcard Hostnames](./deny-wildcard-hostnames.md)
+In this way, only the tenants **gas** and **oil** will be restored.

docs/content/index.md

@@ -0,0 +1,17 @@
+# Capsule Overview
+
+## Kubernetes multi-tenancy made easy
+**Capsule** implements a multi-tenant and policy-based environment in your Kubernetes cluster. It is designed as a micro-services-based ecosystem with the minimalist approach, leveraging only on upstream Kubernetes.
+
+## What's the problem with the current status?
+
+Kubernetes introduces the _Namespace_ object type to create logical partitions of the cluster as isolated *slices*. However, implementing advanced multi-tenancy scenarios, it soon becomes complicated because of the flat structure of Kubernetes namespaces and the impossibility to share resources among namespaces belonging to the same tenant. To overcome this, cluster admins tend to provision a dedicated cluster for each groups of users, teams, or departments. As an organization grows, the number of clusters to manage and keep aligned becomes an operational nightmare, described as the well know phenomena of the _clusters sprawl_.
+
+## Entering Capsule
+
+Capsule takes a different approach. In a single cluster, the Capsule Controller aggregates multiple namespaces in a lightweight abstraction called _Tenant_, basically a grouping of Kubernetes Namespaces. Within each tenant, users are free to create their namespaces and share all the assigned resources. 
+
+On the other side, the Capsule Policy Engine keeps the different tenants isolated from each other. _Network and Security Policies_, _Resource Quota_, _Limit Ranges_, _RBAC_, and other policies defined at the tenant level are automatically inherited by all the namespaces in the tenant. Then users are free to operate their tenants in autonomy, without the intervention of the cluster administrator. 
+
+
+![capsule-operator](./assets/capsule-operator.svg)

docs/gridsome.config.js

@@ -0,0 +1,49 @@
+// This is where project configuration and plugin options are located.
+// Learn more: https://gridsome.org/docs/config
+
+// Changes here require a server restart.
+// To restart press CTRL + C in terminal and run `gridsome develop`
+
+module.exports = {
+  siteName: 'Capsule Documentation',
+  titleTemplate: 'Capsule Documentation | %s',
+  siteDescription: 'Documentation of Capsule, multi-tenant Operator for Kubernetes',
+  icon: {
+    favicon: './src/assets/favicon.png',
+  },
+  plugins: [
+    {
+      use: "gridsome-plugin-tailwindcss",
+
+      options: {
+        tailwindConfig: './tailwind.config.js',
+        // presetEnvConfig: {},
+        // shouldImport: false,
+        // shouldTimeTravel: false
+      }
+    },
+    {
+      use: '@gridsome/source-filesystem',
+      options: {
+        baseDir: './content',
+        path: '**/*.md',
+        pathPrefix: '/docs',
+        typeName: 'MarkdownPage',
+        remark: {
+          externalLinksTarget: '_blank',
+          externalLinksRel: ['noopener', 'noreferrer'],
+          plugins: [
+            '@gridsome/remark-prismjs'
+          ]
+        }
+      }
+    },
+  ],
+  chainWebpack: config => {
+    const svgRule = config.module.rule('svg')
+    svgRule.uses.clear()
+    svgRule
+      .use('vue-svg-loader')
+      .loader('vue-svg-loader')
+  }
+}

docs/gridsome.server.js

@@ -0,0 +1,109 @@
+// Server API makes it possible to hook into various parts of Gridsome
+// on server-side and add custom data to the GraphQL data layer.
+// Learn more: https://gridsome.org/docs/server-api/
+
+// Changes here require a server restart.
+// To restart press CTRL + C in terminal and run `gridsome develop`
+
+module.exports = function (api) {
+  api.loadSource(actions => {
+    // Use the Data Store API here: https://gridsome.org/docs/data-store-api/
+    const sidebar = actions.addCollection({
+      typeName: 'Sidebar'
+    })
+
+    sidebar.addNode({
+      sections: [
+        {
+          items: [
+            {
+              label: 'Overview',
+              path: '/docs/'
+            }
+          ]
+        },
+        {
+          title: 'Documentation',
+          items: [
+            {
+              label: 'Getting Started',
+              path: '/docs/general/getting-started'
+            },
+            {
+              label: 'Tutorial',
+              path: '/docs/general/tutorial'
+            },
+            {
+              label: 'References',
+              path: '/docs/general/references'
+            },
+            {
+              label: 'Capsule Proxy',
+              path: '/docs/general/proxy'
+            },
+            {
+              label: 'Dashboard',
+              path: '/docs/general/lens'
+            },
+          ]
+        },
+        {
+          title: 'Guides',
+          items: [
+            {
+              label: 'OIDC Authentication',
+              path: '/docs/guides/oidc-auth'
+            },
+            {
+              label: 'Monitoring Capsule',
+              path: '/docs/guides/monitoring'
+            },
+            {
+              label: 'Backup & Restore with Velero',
+              path: '/docs/guides/velero'
+            },
+            {
+              title: 'Managed Kubernetes',
+              subItems: [
+                {
+                  label: 'Overview',
+                  path: '/docs/guides/managed-kubernetes/overview'
+                },
+                {
+                  label: 'EKS',
+                  path: '/docs/guides/managed-kubernetes/aws-eks'
+                },
+                {
+                  label: 'CoAKS',
+                  path: '/docs/guides/managed-kubernetes/coaks'
+                },
+              ]
+            }
+          ]
+        },
+        {
+          title: 'Contributing',
+          items: [
+            {
+              label: 'Guidelines',
+              path: '/docs/contributing/guidelines'
+            },
+            {
+              label: 'Development',
+              path: '/docs/contributing/development'
+            },
+            {
+              label: 'Governance',
+              path: '/docs/contributing/governance'
+            }            
+          ]
+        }
+      ]
+    })
+  })
+
+
+  api.createPages(({ createPage }) => {
+    // Use the Pages API here: https://gridsome.org/docs/pages-api/
+  })
+}

docs/index.md

@@ -1,8 +0,0 @@
-# Capsule Documentation
-**Capsule** helps to implement a multi-tenancy and policy-based environment in your Kubernetes cluster. It has been designed as a micro-services based ecosystem with the minimalist approach, leveraging only on upstream Kubernetes. 
-
-Currently, the Capsule ecosystem comprises the following:
-
-* [Capsule Operator](./operator/overview.md)
-* [Capsule Proxy](./proxy/overview.md)
-* [Capsule Lens extension](./lens-extension/overview.md)

docs/operator/contributing.md

@@ -1,251 +0,0 @@
-# How to contribute to Capsule
-First, thanks for your interest in Capsule, any contribution is welcome!
-
-The first step is to set up your local development environment as stated below:
-
-## Setting up the development environment
-The following dependencies are mandatory:
-
-- [Go 1.16](https://golang.org/dl/)
-- [OperatorSDK 1.7.2](https://github.com/operator-framework/operator-sdk)
-- [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder)
-- [KinD](https://github.com/kubernetes-sigs/kind)
-- [ngrok](https://ngrok.com/) (if you want to run locally)
-- [golangci-lint](https://github.com/golangci/golangci-lint)
-
-### Installing Go dependencies
-After cloning Capsule on any folder, access it and issue the following command
-to ensure all dependencies are properly downloaded.
-
-```
-go mod download
-```
-
-### Installing Operator SDK
-Some operations, like the Docker image build process or the code-generation of
-the CRDs manifests, as well the deep copy functions, require _Operator SDK_:
-the binary has to be installed into your `PATH`.
-
-### Installing Kubebuilder
-With the latest release of OperatorSDK there's a more tighten integration with
-Kubebuilder and its opinionated testing suite: ensure to download the latest
-binaries available from the _Releases_ GitHub page and place them into the
-`/usr/local/kubebuilder/bin` folder, ensuring this is also in your `PATH`.
-
-### Installing KinD
-Capsule can run on any certified Kubernetes installation and locally
-the whole development is performed on _KinD_, also knows as
-[Kubernetes in Docker](https://github.com/kubernetes-sigs/kind).
-
-> N.B.: Docker is a hard requirement since it's based on it
-
-According to your operative system and architecture, download the right binary
-and place it on your `PATH`.
-
-Once done, you're ready to bootstrap in a glance of seconds, a fully functional
-Kubernetes cluster.
-
-```
-# kind create cluster --name capsule
-Creating cluster "capsule" ...
- ✓ Ensuring node image (kindest/node:v1.18.2) 🖼
- ✓ Preparing nodes 📦  
- ✓ Writing configuration 📜 
- ✓ Starting control-plane 🕹️ 
- ✓ Installing CNI 🔌 
- ✓ Installing StorageClass 💾 
-Set kubectl context to "kind-capsule"
-You can now use your cluster with:
-
-kubectl cluster-info --context kind-capsule
-
-Thanks for using kind! 😊
-```
-
-The current `KUBECONFIG` will be populated with the `cluster-admin`
-certificates and the context changed to the just born Kubernetes cluster.
-
-### Build the Docker image and push it to KinD
-From the root path, issue the _make_ recipe:
-
-```
-# make docker-build
-```
-
-The image `quay.io/clastix/capsule:<tag>` will be available locally. Built image `<tag>` is resulting last one available [release](https://github.com/clastix/capsule/releases).
-
-Push it to _KinD_ with the following command:
-
-```
-# kind load docker-image --nodes capsule-control-plane --name capsule quay.io/clastix/capsule:<tag>
-```
-
-### Deploy the Kubernetes manifests
-With the current `kind-capsule` context enabled, deploy all the required
-manifests issuing the following command:
-
-```
-make deploy
-```
-
-This will install all the required Kubernetes resources, automatically.
-
-You can check if Capsule is running tailing the logs:
-
-```
-# kubectl -n capsule-system logs --all-containers -f -l control-plane=controller-manager
-```
-
-Since Capsule is built using _OperatorSDK_, logging is handled by the zap
-module: log verbosity of the Capsule controller can be increased passing
-the `--zap-log-level` option with a value from `1` to `10` or the
-[basic keywords](https://godoc.org/go.uber.org/zap/zapcore#Level) although
-it is suggested to use the `--zap-devel` flag to get also stack traces.
-
-> CA generation
->
-> You could notice a restart of the Capsule pod upon installation, that's ok:
-> Capsule is generating the CA and populating the Secret containing the TLS
-> certificate to handle the webhooks and there's the need the reload the whole
-> application to serve properly HTTPS requests.
-
-### Run Capsule locally
-Debugging remote applications is always struggling but Operators just need
-access to the Kubernetes API Server.
-
-#### Scaling down the remote Pod
-First, ensure the Capsule pod is not running scaling down the Deployment.
-
-```
-# kubectl -n capsule-system scale deployment capsule-controller-manager --replicas=0
-deployment.apps/capsule-controller-manager scaled
-```
-
-> This is mandatory since Capsule uses Leader Election
-
-#### Providing TLS certificate for webhooks
-The next step is to replicate the same environment Capsule is expecting in the Pod,
-it means creating a fake certificate to handle HTTP requests.
-
-``` bash
-mkdir -p /tmp/k8s-webhook-server/serving-certs
-kubectl -n capsule-system get secret capsule-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > /tmp/k8s-webhook-server/serving-certs/tls.crt
-kubectl -n capsule-system get secret capsule-tls -o jsonpath='{.data.tls\.key}' | base64 -d > /tmp/k8s-webhook-server/serving-certs/tls.key
-```
-
-> We're using the certificates generate upon the first installation of Capsule:
-> it means the Secret will be populated at the first start-up.
-> If you plan to run it locally since the beginning, it means you will require
-> to provide a self-signed certificate in the said directory.
-
-#### Starting NGROK
-In another session, we need a `ngrok` session, mandatory to debug also webhooks
-(YMMV).
-
-```
-# ngrok http https://localhost:9443
-ngrok by @inconshreveable
-
-Session Status                online
-Account                       Dario Tranchitella (Plan: Free)
-Version                       2.3.35
-Region                        United States (us)
-Web Interface                 http://127.0.01:4040
-Forwarding                    http://cdb72b99348c.ngrok.io -> https://localhost:9443
-Forwarding                    https://cdb72b99348c.ngrok.io -> https://localhost:9443
-Connections                   ttl     opn     rt1     rt5     p50     p90 
-                              0       0       0.00    0.00    0.00    0.00
-```
-
-What we need is the _ngrok_ URL (in this case, `https://cdb72b99348c.ngrok.io`)
-since we're going to use this default URL as the `url` parameter for the
-_Dynamic Admissions Control Webhooks_.
-
-#### Patching the MutatingWebhookConfiguration
-Now it's time to patch the _MutatingWebhookConfiguration_ and the
-_ValidatingWebhookConfiguration_ too, adding the said `ngrok` URL as base for
-each defined webhook, as following:
-
-```diff
-apiVersion: admissionregistration.k8s.io/v1
-kind: MutatingWebhookConfiguration
-metadata:
-
-  name: capsule-mutating-webhook-configuration
-webhooks:
-  - name: owner.namespace.capsule.clastix.io
-    failurePolicy: Fail
-    rules:
-      - apiGroups: [""]
-        apiVersions: ["v1"]
-        operations: ["CREATE"]
-        resources: ["namespaces"]
-    clientConfig:
-+     url: https://cdb72b99348c.ngrok.io/mutate-v1-namespace-owner-reference
--     caBundle:
--     service:
--       namespace: system
--       name: capsule
--       path: /mutate-v1-namespace-owner-reference
-...
-```
-
-#### Run Capsule
-Finally, it's time to run locally Capsule using your preferred IDE (or not):
-from the project root path, you can issue the following command.
-
-```
-make run
-```
-
-All the logs will start to flow in your standard output, feel free to attach
-your debugger to set breakpoints as well!
-
-## Code convention
-The changes must follow the Pull Request method where a _GitHub Action_ will
-check the `golangci-lint`, so ensure your changes respect the coding standard.
-
-### golint
-You can easily check them issuing the _Make_ recipe `golint`.
-
-```
-# make golint
-golangci-lint run -c .golangci.yml
-```
-
-> Enabled linters and related options are defined in the [.golanci.yml file](../../.golangci.yml)
-
-### goimports
-Also, the Go import statements must be sorted following the best practice:
-
-```
-<STANDARD LIBRARY>
-
-<EXTERNAL PACKAGES>
-
-<LOCAL PACKAGES>
-```
-
-To help you out you can use the _Make_ recipe `goimports`
-
-```
-# make goimports
-goimports -w -l -local "github.com/clastix/capsule" .
-```
-
-### Commits
-All the Pull Requests must refer to an already open issue: this is the first phase to contribute also for informing maintainers about the issue.
-
-Commit's first line should not exceed 50 columns.
-
-A commit description is welcomed to explain more the changes: just ensure
-to put a blank line and an arbitrary number of maximum 72 characters long
-lines, at most one blank line between them.
-
-Please, split changes into several and documented small commits: this will help us to perform a better review. Commits must follow the Conventional Commits Specification, a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with Semantic Versioning, by describing the features, fixes, and breaking changes made in commit messages. See [Conventional Commits Specification](https://www.conventionalcommits.org) to learn about Conventional Commits.
-
-> In case of errors or need of changes to previous commits,
-> fix them squashing to make changes atomic.
-
-### Miscellanea
-Please, add a new single line at end of any file as the current coding style.

docs/operator/mtb/allow-self-service-management-of-network-policies.md

@@ -1,77 +0,0 @@
-# Allow self-service management of Network Policies
-
-**Profile Applicability:** L2
-
-**Type:** Behavioral
-
-**Category:** Self-Service Operations
-
-**Description:** Tenants should be able to perform self-service operations by creating their own network policies in their namespaces.
-
-**Rationale:** Enables self-service management of network-policies.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  networkPolicies:
-    items:
-    - ingress:
-      - from:
-        - namespaceSelector:
-            matchLabels:
-              capsule.clastix.io/tenant: oil
-      podSelector: {}
-      policyTypes:
-      - Egress
-      - Ingress
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, retrieve the networkpolicies resources in the tenant namespace
-
-```bash 
-kubectl --kubeconfig alice get networkpolicies 
-NAME            POD-SELECTOR   AGE
-capsule-oil-0   <none>         7m5s
-```
-
-As a tenant, checks for permissions to manage networkpolicy for each verb
-
-```bash 
-kubectl --kubeconfig alice auth can-i get networkpolicies
-kubectl --kubeconfig alice auth can-i create networkpolicies
-kubectl --kubeconfig alice auth can-i update networkpolicies
-kubectl --kubeconfig alice auth can-i patch networkpolicies
-kubectl --kubeconfig alice auth can-i delete networkpolicies
-kubectl --kubeconfig alice auth can-i deletecollection networkpolicies
-```
-
-Each command must return 'yes'
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/allow-self-service-management-of-rolebindings.md

@@ -1,58 +0,0 @@
-# Allow self-service management of Role Bindings
-
-**Profile Applicability:** L2
-
-**Type:** Behavioral
-
-**Category:** Self-Service Operations
-
-**Description:** Tenants should be able to perform self-service operations by creating their rolebindings in their namespaces.
-
-**Rationale:** Enables self-service management of roles.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner check for permissions to manage rolebindings for each verb
-
-```bash 
-kubectl --kubeconfig alice auth can-i get rolebindings
-kubectl --kubeconfig alice auth can-i create rolebindings
-kubectl --kubeconfig alice auth can-i update rolebindings
-kubectl --kubeconfig alice auth can-i patch rolebindings
-kubectl --kubeconfig alice auth can-i delete rolebindings
-kubectl --kubeconfig alice auth can-i deletecollection rolebindings
-```
-
-Each command must return 'yes'
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/allow-self-service-management-of-roles.md

@@ -1,58 +0,0 @@
-# Allow self-service management of Roles
-
-**Profile Applicability:** L2
-
-**Type:** Behavioral
-
-**Category:** Self-Service Operations
-
-**Description:** Tenants should be able to perform self-service operations by creating their own roles in their namespaces.
-
-**Rationale:** Enables self-service management of roles.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, check for permissions to manage roles for each verb
-
-```bash 
-kubectl --kubeconfig alice auth can-i get roles
-kubectl --kubeconfig alice auth can-i create roles
-kubectl --kubeconfig alice auth can-i update roles
-kubectl --kubeconfig alice auth can-i patch roles
-kubectl --kubeconfig alice auth can-i delete roles
-kubectl --kubeconfig alice auth can-i deletecollection roles
-```
-
-Each command must return 'yes'
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/block-access-to-cluster-resources.md

@@ -1,113 +0,0 @@
-# Block access to cluster resources
-
-**Profile Applicability:** L1
-
-**Type:** Configuration Check
-
-**Category:** Control Plane Isolation
-
-**Description:** Tenants should not be able to view, edit, create or delete cluster (non-namespaced) resources such Node, ClusterRole, ClusterRoleBinding, etc.
-
-**Rationale:** Access controls should be configured for tenants so that a tenant cannot list, create, modify or delete cluster resources
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-```
-
-As cluster admin, run the following command to retrieve the list of non-namespaced resources
-```bash 
-kubectl --kubeconfig cluster-admin api-resources --namespaced=false
-```
-For all non-namespaced resources, and each verb (get, list, create, update, patch, watch, delete, and deletecollection) issue the following command:
-
-```bash 
-kubectl --kubeconfig alice auth can-i <verb> <resource>
-```
-Each command must return `no`
-
-**Exception:**
-
-It should, but it does not:
-
-```bash 
-kubectl --kubeconfig alice auth can-i create selfsubjectaccessreviews
-yes
-kubectl --kubeconfig alice auth can-i create selfsubjectrulesreviews
-yes
-kubectl --kubeconfig alice auth can-i create namespaces
-yes
-```
-
-Any kubernetes user can create `SelfSubjectAccessReview` and `SelfSubjectRulesReviews` to checks whether he/she can act. First, two exceptions are not an issue.
-
-```bash 
-kubectl --anyuser auth can-i --list
-Resources                                       Non-Resource URLs   Resource Names   Verbs
-selfsubjectaccessreviews.authorization.k8s.io   []                  []               [create]
-selfsubjectrulesreviews.authorization.k8s.io    []                  []               [create]
-                                                [/api/*]            []               [get]
-                                                [/api]              []               [get]
-                                                [/apis/*]           []               [get]
-                                                [/apis]             []               [get]
-                                                [/healthz]          []               [get]
-                                                [/healthz]          []               [get]
-                                                [/livez]            []               [get]
-                                                [/livez]            []               [get]
-                                                [/openapi/*]        []               [get]
-                                                [/openapi]          []               [get]
-                                                [/readyz]           []               [get]
-                                                [/readyz]           []               [get]
-                                                [/version/]         []               [get]
-                                                [/version/]         []               [get]
-                                                [/version]          []               [get]
-                                                [/version]          []               [get]
-```
-
-To enable namespace self-service provisioning, Capsule intentionally gives permissions to create namespaces to all users belonging to the Capsule group:
-
-```bash
-kubectl describe clusterrolebindings capsule-namespace-provisioner
-Name:         capsule-namespace-provisioner
-Labels:       <none>
-Annotations:  <none>
-Role:
-  Kind:  ClusterRole
-  Name:  capsule-namespace-provisioner
-Subjects:
-  Kind   Name                Namespace
-  ----   ----                ---------
-  Group  capsule.clastix.io  
-
-kubectl describe clusterrole capsule-namespace-provisioner
-Name:         capsule-namespace-provisioner
-Labels:       <none>
-Annotations:  <none>
-PolicyRule:
-  Resources   Non-Resource URLs  Resource Names  Verbs
-  ---------   -----------------  --------------  -----
-  namespaces  []                 []              [create]
-```
-
-Capsule controls self-service namespace creation by limiting the number of namespaces the user can create by the `tenant.spec.namespaceQuota option`. 
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/block-access-to-multitenant-resources.md

@@ -1,155 +0,0 @@
-# Block access to multitenant resources
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral
-
-**Category:** Tenant Isolation
-
-**Description:** Each tenant namespace may contain resources set up by the cluster administrator for multi-tenancy, such as role bindings, and network policies. Tenants should not be allowed to modify the namespaced resources created by the cluster administrator for multi-tenancy. However, for some resources such as network policies, tenants can configure additional instances of the resource for their workloads.
-
-**Rationale:** Tenants can escalate privileges and impact other tenants if they can delete or modify required multi-tenancy resources such as namespace resource quotas or default network policy.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  networkPolicies:
-    items:
-    - podSelector: {}
-      policyTypes:
-      - Ingress
-      - Egress
-    - egress:
-      - to:
-        - namespaceSelector:
-            matchLabels:
-              capsule.clastix.io/tenant: oil
-      ingress:
-      - from:
-        - namespaceSelector:
-            matchLabels:
-              capsule.clastix.io/tenant: oil
-      podSelector: {}
-      policyTypes:
-      - Egress
-      - Ingress
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, retrieve the networkpolicies resources in the tenant namespace
-
-```bash 
-kubectl --kubeconfig alice get networkpolicies 
-NAME            POD-SELECTOR   AGE
-capsule-oil-0   <none>         7m5s
-capsule-oil-1   <none>         7m5s
-```
-
-As tenant owner try to modify or delete one of the networkpolicies
-
-```bash 
-kubectl --kubeconfig alice delete networkpolicies capsule-oil-0
-```
-
-You should receive an error message denying the edit/delete request
-
-```bash 
-Error from server (Forbidden): networkpolicies.networking.k8s.io "capsule-oil-0" is forbidden:
-User "oil" cannot delete resource "networkpolicies" in API group "networking.k8s.io" in the namespace "oil-production"
-```
-
-As tenant owner, you can create an additional networkpolicy inside the namespace
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: networking.k8s.io/v1
-kind: NetworkPolicy
-metadata:
-  name: hijacking
-  namespace: oil-production
-spec:
-  egress: 
-    - to:
-      - ipBlock:
-          cidr: 0.0.0.0/0
-  podSelector: {}
-  policyTypes:
-  - Egress
-EOF
-```
-
-However, due to the additive nature of networkpolicies, the `DENY ALL` policy set by the cluster admin, prevents hijacking.
-
-As tenant owner list RBAC permissions set by Capsule
-
-```bash 
-kubectl --kubeconfig alice get rolebindings
-NAME                ROLE                                    AGE
-namespace-deleter   ClusterRole/capsule-namespace-deleter   11h
-namespace:admin     ClusterRole/admin                       11h
-```
-
-As tenant owner, try to change/delete  the rolebinding to escalate permissions
-
-```bash 
-kubectl --kubeconfig alice edit/delete rolebinding namespace:admin
-```
-
-The rolebinding is immediately recreated by Capsule:
-
-```
-kubectl --kubeconfig alice get rolebindings
-NAME                ROLE                                    AGE
-namespace-deleter   ClusterRole/capsule-namespace-deleter   11h
-namespace:admin     ClusterRole/admin                       2s
-```
-
-However, the tenant owner can create and assign permissions inside the namespace she owns
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  labels:
-  name: oil-robot:admin
-  namespace: oil-production
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: ClusterRole
-  name: admin
-subjects:
-- kind: ServiceAccount
-  name: default
-  namespace: oil-production
-EOF
-```
-
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/block-access-to-other-tenant-resources.md

@@ -1,97 +0,0 @@
-# Block access to other tenant resources
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral
-
-**Category:** Tenant Isolation
-
-**Description:** Each tenant has its own set of resources, such as namespaces, service accounts, secrets, pods, services, etc. Tenants should not be allowed to access each other's resources.
-
-**Rationale:** Tenant's resources must be not accessible by other tenants.
-
-**Audit:**
-
-As cluster admin, create a couple of tenants
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-
-```
-
-and
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: gas
-spec:
-  owners:
-  - kind: User
-    name: joe
-EOF
-
-./create-user.sh joe gas
-
-```
-
-As `oil` tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As `gas` tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig joe create ns gas-production
-kubectl --kubeconfig joe config set-context --current --namespace gas-production
-```
-
-
-As `oil` tenant owner, try to retrieve the resources in the `gas` tenant namespaces
-
-```bash 
-kubectl --kubeconfig alice get serviceaccounts --namespace  gas-production 
-```
-
-You must receive an error message:
-
-```
-Error from server (Forbidden): serviceaccount is forbidden:
-User "oil" cannot list resource "serviceaccounts" in API group "" in the namespace "gas-production"
-```
-
-As `gas` tenant owner, try to retrieve the resources in the `oil` tenant namespaces
-
-```bash 
-kubectl --kubeconfig joe get serviceaccounts --namespace  oil-production 
-```
-
-You must receive an error message:
-
-```
-Error from server (Forbidden): serviceaccount is forbidden:
-User "joe" cannot list resource "serviceaccounts" in API group "" in the namespace "oil-production"
-```
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenants oil gas
-```

docs/operator/mtb/block-add-capabilities.md

@@ -1,121 +0,0 @@
-# Block add capabilities
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Control Plane Isolation
-
-**Description:** Control Linux capabilities.
-
-**Rationale:** Linux allows defining fine-grained permissions using capabilities. With Kubernetes, it is possible to add capabilities for pods that escalate the level of kernel access and allow other potentially dangerous behaviors.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` with `allowedCapabilities` and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  # The default set of capabilities are implicitly allowed
-  # The empty set means that no additional capabilities may be added beyond the default set
-  allowedCapabilities: []
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod and see new capabilities cannot be added in the tenant namespaces
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-settime-cap
-  namespace:
-  labels:
-spec:
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-    securityContext:
-      capabilities:
-        add:
-        - SYS_TIME
-EOF
-```
-
-You must have the pod blocked by PodSecurityPolicy.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-modification-of-resource-quotas.md

@@ -1,69 +0,0 @@
-# Block modification of resource quotas
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Tenant Isolation
-
-**Description:** Tenants should not be able to modify the resource quotas defined in their namespaces
-
-**Rationale:** Resource quotas must be configured for isolation and fairness between tenants. Tenants should not be able to modify existing resource quotas as they may exhaust cluster resources and impact other tenants.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  resourceQuotas:
-    items:
-    - hard:
-        limits.cpu: "8"
-        limits.memory: 16Gi
-        requests.cpu: "8"
-        requests.memory: 16Gi
-    - hard:
-        pods: "10"
-        services: "50"
-    - hard:
-        requests.storage: 100Gi
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, check the permissions to modify/delete the quota in the tenant namespace:
-
-```bash 
-kubectl --kubeconfig alice auth can-i create quota
-kubectl --kubeconfig alice auth can-i update quota
-kubectl --kubeconfig alice auth can-i patch quota
-kubectl --kubeconfig alice auth can-i delete quota
-kubectl --kubeconfig alice auth can-i deletecollection quota
-```
-
-Each command must return 'no'
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/block-network-access-across-tenant-namespaces.md

@@ -1,107 +0,0 @@
-# Block access to multitenant resources
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral
-
-**Category:** Tenant Isolation
-
-**Description:** Block network traffic among namespaces from different tenants.
-
-**Rationale:** Tenants cannot access services and pods in another tenant's namespaces.
-
-**Audit:**
-
-As cluster admin, create a couple of tenants 
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  networkPolicies:
-    items:
-    - ingress:
-      - from:
-        - namespaceSelector:
-            matchLabels:
-              capsule.clastix.io/tenant: oil
-      podSelector: {}
-      policyTypes:
-      - Ingress
-EOF
-
-./create-user.sh alice oil
-```
-
-and
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: gas
-spec:
-  owners:
-  - kind: User
-    name: joe
-  networkPolicies:
-    items:
-    - ingress:
-      - from:
-        - namespaceSelector:
-            matchLabels:
-              capsule.clastix.io/tenant: gas
-      podSelector: {}
-      policyTypes:
-      - Ingress
-EOF
-
-./create-user.sh joe gas
-```
-
-As `oil` tenant owner, run the following commands to create a namespace and resources in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-kubectl --kubeconfig alice run webserver --image nginx:latest
-kubectl --kubeconfig alice expose pod webserver --port 80
-```
-
-As `gas` tenant owner, run the following commands to create a namespace and resources in the given tenant
-
-```bash 
-kubectl --kubeconfig joe create ns gas-production
-kubectl --kubeconfig joe config set-context --current --namespace gas-production
-kubectl --kubeconfig joe run webserver --image nginx:latest
-kubectl --kubeconfig joe expose pod webserver --port 80
-```
-
-As `oil` tenant owner, verify you can access the service in `oil` tenant namespace but not in the `gas` tenant namespace
-
-```bash 
-kubectl --kubeconfig alice exec webserver -- curl http://webserver.oil-production.svc.cluster.local
-kubectl --kubeconfig alice exec webserver -- curl http://webserver.gas-production.svc.cluster.local
-```
-
-Viceversa, as `gas` tenant owner, verify you can access the service in `gas` tenant namespace but not in the `oil` tenant namespace
-
-```bash 
-kubectl --kubeconfig alice exec webserver -- curl http://webserver.oil-production.svc.cluster.local
-kubectl --kubeconfig alice exec webserver -- curl http://webserver.gas-production.svc.cluster.local
-```
-
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenants oil gas
-```

docs/operator/mtb/block-privilege-escalation.md

@@ -1,115 +0,0 @@
-# Block privilege escalation
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Control Plane Isolation
-
-**Description:** Control container permissions.
-
-**Rationale:** The security `allowPrivilegeEscalation` setting allows a process to gain more privileges from its parent process. Processes in tenant containers should not be allowed to gain additional privileges.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` that sets `allowPrivilegeEscalation=false` and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod or container that sets `allowPrivilegeEscalation=true` in its `securityContext`. 
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-priviliged-mode
-  namespace: oil-production
-  labels:
-spec:
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-    securityContext:
-      allowPrivilegeEscalation: true
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-privileged-containers.md

@@ -1,116 +0,0 @@
-# Block privileged containers
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Control Plane Isolation
-
-**Description:** Control container permissions.
-
-**Rationale:** By default a container is not allowed to access any devices on the host, but a “privileged” container can access all devices on the host. A process within a privileged container can also get unrestricted host access. Hence, tenants should not be allowed to run privileged containers.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` that sets `privileged=false` and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod or container that sets privileges in its `securityContext`. 
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-priviliged-mode
-  namespace:
-  labels:
-spec:
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-    securityContext:
-      privileged: true
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-use-of-existing-persistent-volumes.md

@@ -1,40 +0,0 @@
-# Block use of existing PVs
-
-**Profile Applicability:** L1
-
-**Type:** Configuration Check
-
-**Category:** Data Isolation
-
-**Description:** Avoid a tenant to mount existing volumes`.
-
-**Rationale:** Tenants have to be assured that their Persistent Volumes cannot be reclaimed by other tenants.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, check if you can access the persistent volumes
-
-```bash 
-kubectl --kubeconfig alice auth can-i get persistentvolumes
-kubectl --kubeconfig alice auth can-i list persistentvolumes
-kubectl --kubeconfig alice auth can-i watch persistentvolumes
-```
-
-You must receive for all the requests 'no'.

docs/operator/mtb/block-use-of-host-ipc.md

@@ -1,115 +0,0 @@
-# Block use of host IPC
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Host Isolation
-
-**Description:** Tenants should not be allowed to share the host's inter-process communication (IPC) namespace.
-
-**Rationale:** The `hostIPC` setting allows pods to share the host's inter-process communication (IPC) namespace allowing potential access to host processes or processes belonging to other tenants.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` that restricts `hostIPC` usage and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  hostIPC: false
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod mounting the host IPC namespace. 
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-host-ipc
-  namespace: oil-production
-spec:
-  hostIPC: true
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-use-of-host-networking-and-ports.md

@@ -1,136 +0,0 @@
-# Block use of host networking and ports
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Host Isolation
-
-**Description:** Tenants should not be allowed to use host networking and host ports for their workloads.
-
-**Rationale:** Using `hostPort` and `hostNetwork` allows tenants workloads to share the host networking stack allowing potential snooping of network traffic across application pods.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` that restricts `hostPort` and `hostNetwork` and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  hostNetwork: false
-  hostPorts: [] # empty means no allowed host ports
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod using `hostNetwork`
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-hostnetwork
-  namespace: oil-production
-spec:
-  hostNetwork: true
-  containers:
-  - name: nginx
-    image: nginx:latest
-    ports:
-    - containerPort: 80
-EOF
-```
-
-As tenant owner, create a pod defining a container using `hostPort`
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-hostport
-  namespace: oil-production
-spec:
-  containers:
-  - name: nginx
-    image: nginx:latest
-    ports:
-    - containerPort: 80
-      hostPort: 9090
-EOF
-```
-
-In both the cases above, you must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-use-of-host-path-volumes.md

@@ -1,129 +0,0 @@
-# Block use of host path volumes
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Host Protection
-
-**Description:** Tenants should not be able to mount host volumes and directories.
-
-**Rationale:** The use of host volumes and directories can be used to access shared data or escalate privileges and also creates a tight coupling between a tenant workload and a host.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` that restricts `hostPath` volumes and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  volumes: # hostPath is not permitted
-    - 'configMap'
-    - 'emptyDir'
-    - 'projected'
-    - 'secret'
-    - 'downwardAPI'
-    - 'persistentVolumeClaim'
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod defining a volume of type `hostpath`. 
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-hostpath-volume
-  namespace: oil-production
-spec:
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-    volumeMounts:
-    - mountPath: /tmp
-      name: volume
-  volumes:
-  - name: volume
-    hostPath:
-      # directory location on host
-      path: /data
-      type: Directory
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-use-of-host-pid.md

@@ -1,115 +0,0 @@
-# Block use of host PID
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Host Isolation
-
-**Description:** Tenants should not be allowed to share the host process ID (PID) namespace.
-
-**Rationale:** The `hostPID` setting allows pods to share the host process ID namespace allowing potential privilege escalation. Tenant pods should not be allowed to share the host PID namespace.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` that restricts `hostPID` usage and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  hostPID: false
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod mounting the host PID namespace. 
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-host-pid
-  namespace: oil-production
-spec:
-  hostPID: true
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/block-use-of-nodeport-services.md

@@ -1,75 +0,0 @@
-# Block use of NodePort services
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Host Isolation
-
-**Description:** Tenants should not be able to create services of type NodePort.
-
-**Rationale:** the service type `NodePorts` configures host ports that cannot be secured using Kubernetes network policies and require upstream firewalls. Also, multiple tenants cannot use the same host port numbers.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  enableNodePorts: false
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, creates a service in the tenant namespace having service type of `NodePort` 
-
-```yaml
-kubectl --kubeconfig alice apply -f - << EOF
-apiVersion: v1
-kind: Service
-metadata:
-  name: nginx
-  labels:
-  namespace: oil-production
-spec:
-  ports:
-  - protocol: TCP
-    port: 8080
-    targetPort: 80
-  selector:
-    run: nginx
-  type: NodePort
-EOF
-```
-
-You must receive an error message denying the request:
-
-```
-Error from server
-Error from server (NodePort service types are forbidden for the tenant:
-error when creating "STDIN": admission webhook "services.capsule.clastix.io" denied the request:
-NodePort service types are forbidden for the tenant: please, reach out to the system administrators
-```
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/configure-namespace-object-limits.md

@@ -1,66 +0,0 @@
-# Configure namespace object limits
-
-**Profile Applicability:** L1
-
-**Type:** Configuration
-
-**Category:** Fairness
-
-**Description:** Namespace resource quotas should be used to allocate, track and limit the number of objects, of a particular type, that can be created within a namespace.
-
-**Rationale:** Resource quotas must be configured for each tenant namespace, to guarantee isolation and fairness across tenants.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  resourceQuotas:
-    items:
-    - hard:
-        pods: 100
-        services: 50
-        services.loadbalancers: 3
-        services.nodeports: 20
-        persistentvolumeclaims: 100
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, retrieve the configured quotas in the tenant namespace:
-
-```bash 
-kubectl --kubeconfig alice get quota
-NAME            AGE   REQUEST                 LIMIT
-capsule-oil-0   23s   persistentvolumeclaims: 0/100,
-                      pods: 0/100, services: 0/50,
-                      services.loadbalancers: 0/3,
-                      services.nodeports: 0/20  
-```
-
-Make sure that a quota is configured for API objects: `PersistentVolumeClaim`, `LoadBalancer`, `NodePort`, `Pods`, etc
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/configure-namespace-resource-quotas.md

@@ -1,65 +0,0 @@
-# Configure namespace resource quotas
-
-**Profile Applicability:** L1
-
-**Type:** Configuration
-
-**Category:** Fairness
-
-**Description:** Namespace resource quotas should be used to allocate, track, and limit a tenant's use of shared resources.
-
-**Rationale:** Resource quotas must be configured for each tenant namespace, to guarantee isolation and fairness across tenants.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - <<EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  resourceQuotas:
-    items:
-    - hard:
-        limits.cpu: "8"
-        limits.memory: 16Gi
-        requests.cpu: "8"
-        requests.memory: 16Gi
-    - hard:
-        requests.storage: 100Gi
-EOF
-
-./create-user.sh alice oil
-
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, retrieve the configured quotas in the tenant namespace:
-
-```bash 
-kubectl --kubeconfig alice get quota
-NAME            AGE   REQUEST                                      LIMIT
-capsule-oil-0   24s   requests.cpu: 0/8, requests.memory: 0/16Gi   limits.cpu: 0/8, limits.memory: 0/16Gi                 
-capsule-oil-1   24s   requests.storage: 0/10Gi                     
-```
-
-Make sure that a quota is configured for CPU, memory, and storage resources.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/require-always-imagepullpolicy.md

@@ -1,71 +0,0 @@
-# Require always imagePullPolicy
-
-**Profile Applicability:** L1
-
-**Type:** Configuration Check
-
-**Category:** Data Isolation
-
-**Description:** Set the image pull policy to Always for tenant workloads.
-
-**Rationale:** Tenants have to be assured that their private images can only be used by those who have the credentials to pull them.
-
-**Audit:**
-
-As cluster admin, create a tenant
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  imagePullPolicies:
-  - Always
-  owners:
-  - kind: User
-    name: alice
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, creates a pod in the tenant namespace having `imagePullPolicies=IfNotPresent` 
-
-```yaml
-kubectl --kubeconfig alice apply -f - << EOF
-apiVersion: v1
-kind: Pod
-metadata:
-  name: nginx
-  namespace: oil-production
-spec:
-  containers:
-  - name: nginx
-    image: nginx:latest
-    imagePullPolicy: IfNotPresent
-EOF
-```
-
-You must receive an error message denying the request:
-
-```
-Error from server
-(ImagePullPolicy IfNotPresent for container nginx is forbidden, use one of the followings: Always): error when creating "STDIN": admission webhook "pods.capsule.clastix.io" denied the request:
-ImagePullPolicy IfNotPresent for container nginx is forbidden, use one of the followings: Always
-```
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-```

docs/operator/mtb/require-persistentvolumeclaim-for-storage.md

@@ -1,124 +0,0 @@
-# Require PersistentVolumeClaim for storage
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** na
-
-**Description:** Tenants should not be able to use all volume types except `PersistentVolumeClaims`.
-
-**Rationale:** In some scenarios, it would be required to disallow usage of any core volume types except PVCs.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` allowing only `PersistentVolumeClaim` volumes and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  volumes: 
-    - 'persistentVolumeClaim'
-  runAsUser:
-    rule: RunAsAny
-  seLinux:
-    rule: RunAsAny
-  supplementalGroups:
-    rule: RunAsAny
-  fsGroup:
-    rule: RunAsAny
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  namespace: oil-production
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod defining a volume of any of the core type except `PersistentVolumeClaim`. For example:
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-with-hostpath-volume
-  namespace: oil-production
-spec:
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-    volumeMounts:
-    - mountPath: /tmp
-      name: volume
-  volumes:
-  - name: volume
-    hostPath:
-      # directory location on host
-      path: /data
-      type: Directory
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/require-reclaim-policy-of-delete.md

@@ -1,87 +0,0 @@
-# Require PV reclaim policy of delete
-
-**Profile Applicability:** L1
-
-**Type:** Configuration Check
-
-**Category:** Data Isolation
-
-**Description:** Force a tenant to use a Storage Class with `reclaimPolicy=Delete`.
-
-**Rationale:** Tenants have to be assured that their Persistent Volumes cannot be reclaimed by other tenants.
-
-**Audit:**
-
-As cluster admin, create a Storage Class with `reclaimPolicy=Delete`
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: storage.k8s.io/v1
-kind: StorageClass
-metadata:
-  name: delete-policy
-reclaimPolicy: Delete
-provisioner: clastix.io/nfs
-EOF
-```
-
-As cluster admin, create a tenant and assign the above Storage Class
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  storageClasses:
-    allowed:
-    - delete-policy
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, creates a Persistent Volum Claim in the tenant namespace missing the Storage Class or using any other Storage Class: 
-
-```yaml
-kubectl --kubeconfig alice apply -f - << EOF
-kind: PersistentVolumeClaim
-apiVersion: v1
-metadata:
-  name: pvc
-  namespace: oil-production
-spec:
-  accessModes:
-    - ReadWriteOnce
-  resources:
-    requests:
-      storage: 12Gi
-EOF
-```
-
-You must receive an error message denying the request:
-
-```
-Error from server (A valid Storage Class must be used, one of the following (delete-policy)):
-error when creating "STDIN": admission webhook "pvc.capsule.clastix.io" denied the request:
-A valid Storage Class must be used, one of the following (delete-policy)
-```
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete storageclass delete-policy
-```

docs/operator/mtb/require-run-as-non-root-user.md

@@ -1,119 +0,0 @@
-# Require run as non-root user
-
-**Profile Applicability:** L1
-
-**Type:** Behavioral Check
-
-**Category:** Control Plane Isolation
-
-**Description:** Control container permissions.
-
-**Rationale:** Processes in containers run as the root user (uid 0), by default. To prevent potential compromise of container hosts, specify a least-privileged user ID when building the container image and require that application containers run as non-root users.
-
-**Audit:**
-
-As cluster admin, define a `PodSecurityPolicy` with `runAsUser=MustRunAsNonRoot` and map the policy to a tenant:
-
-```yaml
-kubectl create -f - << EOF
-apiVersion: policy/v1beta1
-kind: PodSecurityPolicy
-metadata:
-  name: tenant
-spec:
-  privileged: false
-  # Required to prevent escalations to root.
-  allowPrivilegeEscalation: false
-  runAsUser:
-    # Require the container to run without root privileges.
-    rule: MustRunAsNonRoot
-  supplementalGroups:
-    rule: MustRunAs
-    ranges:
-      # Forbid adding the root group.
-      - min: 1
-        max: 65535
-  fsGroup:
-    rule: MustRunAs
-    ranges:
-      # Forbid adding the root group.
-      - min: 1
-        max: 65535
-EOF
-```
-
-> Note: make sure `PodSecurityPolicy` Admission Control is enabled on the APIs server: `--enable-admission-plugins=PodSecurityPolicy`
-
-Then create a ClusterRole using or granting the said item
-
-```yaml
-kubectl create -f - << EOF
-kind: ClusterRole
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: tenant:psp
-rules:
-- apiGroups: ['policy']
-  resources: ['podsecuritypolicies']
-  resourceNames: ['tenant']
-  verbs: ['use']
-EOF
-```
-
-And assign it to the tenant
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - kind: User
-    name: alice
-  additionalRoleBindings:
-  - clusterRoleName: tenant:psp
-    subjects:
-    - kind: "Group"
-      apiGroup: "rbac.authorization.k8s.io"
-      name: "system:authenticated"
-EOF
-
-./create-user.sh alice oil
-```
-
-As tenant owner, run the following command to create a namespace in the given tenant
-
-```bash 
-kubectl --kubeconfig alice create ns oil-production
-kubectl --kubeconfig alice config set-context --current --namespace oil-production
-```
-
-As tenant owner, create a pod or container that does not set `runAsNonRoot` to `true` in its `securityContext`, and `runAsUser` must not be set to 0. 
-
-```yaml 
-kubectl --kubeconfig alice apply -f - << EOF 
-apiVersion: v1
-kind: Pod
-metadata:
-  name: pod-run-as-root
-  namespace: oil-production
-spec:
-  containers:
-  - name: busybox
-    image: busybox:latest
-    command: ["/bin/sleep", "3600"]
-EOF
-```
-
-You must have the pod blocked by `PodSecurityPolicy`.
-
-**Cleanup:**
-As cluster admin, delete all the created resources
-
-```bash 
-kubectl --kubeconfig cluster-admin delete tenant oil
-kubectl --kubeconfig cluster-admin delete PodSecurityPolicy tenant
-kubectl --kubeconfig cluster-admin delete ClusterRole tenant:psp
-```

docs/operator/mtb/sig-multitenancy-bench.md

@@ -1,30 +0,0 @@
-# Meet the multi-tenancy benchmark MTB
-Actually, there's no yet a real standard for the multi-tenancy model in Kubernetes, although the [SIG multi-tenancy group](https://github.com/kubernetes-sigs/multi-tenancy) is working on that. SIG multi-tenancy drafted a generic validation schema appliable to generic multi-tenancy projects. Multi-Tenancy Benchmarks [MTB](https://github.com/kubernetes-sigs/multi-tenancy/tree/master/benchmarks) are guidelines for multi-tenant configuration of Kubernetes clusters. Capsule is an open source multi-tenancy operator and we decided to meet the requirements of MTB.
-
-> N.B. At the time of writing, the MTB is in development and not ready for usage. Strictly speaking, we do not claim official conformance to MTB, but just to adhere to the multi-tenancy requirements and best practices promoted by MTB.
-
-|MTB Benchmark |MTB Profile|Capsule Version|Conformance|Notes  |
-|--------------|-----------|---------------|-----------|-------|
-|[Block access to cluster resources](block-access-to-cluster-resources.md)|L1|v0.1.0|✓|---|
-|[Block access to multitenant resources](block-access-to-multitenant-resources.md)|L1|v0.1.0|✓|---|
-|[Block access to other tenant resources](block-access-to-other-tenant-resources.md)|L1|v0.1.0|✓|MTB draft|
-|[Block add capabilities](block-add-capabilities.md)|L1|v0.1.0|✓|---|
-|[Require always imagePullPolicy](require-always-imagepullpolicy.md)|L1|v0.1.0|✓|---|
-|[Require run as non-root user](require-run-as-non-root-user.md)|L1|v0.1.0|✓|---|
-|[Block privileged containers](block-privileged-containers.md)|L1|v0.1.0|✓|---|
-|[Block privilege escalation](block-privilege-escalation.md)|L1|v0.1.0|✓|---|
-|[Configure namespace resource quotas](configure-namespace-resource-quotas.md)|L1|v0.1.0|✓|---|
-|[Block modification of resource quotas](block-modification-of-resource-quotas.md)|L1|v0.1.0|✓|---|
-|[Configure namespace object limits](configure-namespace-object-limits.md)|L1|v0.1.0|✓|---|
-|[Block use of host path volumes](block-use-of-host-path-volumes.md)|L1|v0.1.0|✓|---|
-|[Block use of host networking and ports](block-use-of-host-networking-and-ports.md)|L1|v0.1.0|✓|---|
-|[Block use of host PID](block-use-of-host-pid.md)|L1|v0.1.0|✓|---|
-|[Block use of host IPC](block-use-of-host-ipc.md)|L1|v0.1.0|✓|---|
-|[Block use of NodePort services](block-use-of-nodeport-services.md)|L1|v0.1.0|✓|---|
-|[Require PersistentVolumeClaim for storage](require-persistentvolumeclaim-for-storage.md)|L1|v0.1.0|✓|MTB draft|
-|[Require PV reclaim policy of delete](require-reclaim-policy-of-delete.md)|L1|v0.1.0|✓|MTB draft|
-|[Block use of existing PVs](block-use-of-existing-persistent-volumes.md)|L1|v0.1.0|✓|MTB draft|
-|[Block network access across tenant namespaces](block-network-access-across-tenant-namespaces.md)|L1|v0.1.0|✓|MTB draft|
-|[Allow self-service management of Network Policies](allow-self-service-management-of-network-policies.md)|L2|v0.1.0|✓|---|
-|[Allow self-service management of Roles](allow-self-service-management-of-roles.md)|L2|v0.1.0|✓|MTB draft|
-|[Allow self-service management of Role Bindings](allow-self-service-management-of-rolebindings.md)|L2|v0.1.0|✓|MTB draft|

docs/operator/overview.md

@@ -1,10 +0,0 @@
-# Kubernetes Operator
-
-* [Getting Started](./getting-started.md)
-* [Use Cases](./use-cases/overview.md)
-* [SIG Multi-tenancy benchmark](./mtb/sig-multitenancy-bench.md)
-* [Run on Managed Kubernetes Services](./managed-kubernetes/overview.md)
-* [Monitoring Capsule](./monitoring.md)
-* [References](./references.md)
-* [Contributing](./contributing.md)
-

docs/operator/use-cases/cordoning-tenant.md

@@ -1,52 +0,0 @@
-# Cordoning a Tenant
-
-Bill needs to cordon a Tenant and its Namespaces for several reasons:
-
-- Avoid accidental resource modification(s) including deletion during a Production Freeze Window
-- During the Kubernetes upgrade, to prevent any workload updates
-- During incidents or outages
-- During planned maintenance of a dedicated nodes pool in a BYOD scenario
-
-With this said, the Tenant Owner and the related Service Account living into managed Namespaces, cannot proceed to any update, create or delete action.
-
-This is possible just labeling the Tenant as follows:
-
-```shell
-kubectl label tenant oil capsule.clastix.io/cordon=enabled
-tenant oil labeled
-```
-
-Any operation performed by Alice, the Tenant Owner, will be rejected.
-
-```shell
-$ kubectl --as alice --as-group capsule.clastix.io -n oil-dev create deployment nginx --image nginx
-error: failed to create deployment: admission webhook "cordoning.tenant.capsule.clastix.io" denied the request: tenant oil is frozen: please, reach out to the system administrator
-
-$ kubectl --as alice --as-group capsule.clastix.io -n oil-dev delete ingress,deployment,serviceaccount --all
-error: failed to create deployment: admission webhook "cordoning.tenant.capsule.clastix.io" denied the request: tenant oil is frozen: please, reach out to the system administrator
-```
-
-Uncordoning can be done by removing the said label:
-
-```shell
-$ kubectl label tenant oil capsule.clastix.io/cordon-
-tenant.capsule.clastix.io/oil labeled
-
-$ kubectl --as alice --as-group capsule.clastix.io -n oil-dev create deployment nginx --image nginx
-deployment.apps/nginx created
-```
-
-Status of cordoning is also reported in the `state` of the tenant:
-
-```shell
-kubectl get tenants
-NAME     STATE    NAMESPACE QUOTA   NAMESPACE COUNT   NODE SELECTOR    AGE
-bronze   Active                     2                                  3d13h
-gold     Active                     2                                  3d13h
-oil      Cordoned                   4                                  2d11h
-silver   Active                     2                                  3d13h
-```
-
-# What’s next
-
-See how Bill, the cluster admin, can prevent creating services with specific service types. [Disabling Service Types](./service-type.md).

docs/operator/use-cases/create-namespaces.md

@@ -1,110 +0,0 @@
-# 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.
-
-When Alice creates the namespace, the Capsule controller listening for creation and deletion events assigns to Alice the following roles:
-
-```yaml
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  name: namespace:admin
-  namespace: oil-production
-subjects:
-- kind: User
-  name: alice
-roleRef:
-  kind: ClusterRole
-  name: admin
-  apiGroup: rbac.authorization.k8s.io
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  name: namespace-deleter
-  namespace: oil-production
-subjects:
-- kind: User
-  name: alice
-roleRef:
-  kind: ClusterRole
-  name: capsule-namespace-deleter
-  apiGroup: rbac.authorization.k8s.io
-```
-
-So Alice is the admin of the namespaces:
-
-```
-kubectl get rolebindings -n oil-development
-NAME                ROLE                                    AGE
-namespace:admin     ClusterRole/admin                       12s
-namespace-deleter   ClusterRole/capsule-namespace-deleter   12s
-```
-
-The said Role Binding resources are automatically created by Capsule controller when the tenant owner Alice creates a namespace in the tenant.
-
-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 -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`
-
-```yaml
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  namespaceOptions:
-    quota: 3
-```
-
-Alice can create additional namespaces according to the quota:
-
-```
-kubectl create ns oil-development
-kubectl create ns oil-test
-```
-
-While Alice creates namespaces, the Capsule controller updates the status of the tenant so Bill, the cluster admin, can check the status:
-
-```
-kubectl describe tenant oil
-```
-
-```yaml
-...
-status:
-  Namespaces:
-    oil-development
-    oil-production
-    oil-test
-  size:  3 # current namespace count
-...
-```
-
-Once the namespace quota assigned to the tenant has been reached, Alice cannot create further namespaces
-
-```
-kubectl create ns oil-training
-Error from server (Cannot exceed Namespace quota: please, reach out to the system administrators): 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.
-
-# What’s next
-See how Alice, the tenant owner, can assign different user roles in the tenant. [Assign permissions](./permissions.md).

docs/operator/use-cases/custom-resources.md

@@ -1,78 +0,0 @@
-# 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
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: argoproj-provisioner
-rules:
-- apiGroups:
-  - argoproj.io
-  resources:
-  - applications
-  - appprojects
-  verbs:
-  - create
-  - get
-  - list
-  - watch
-  - update
-  - patch
-  - delete
-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
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  - name: joe
-    kind: User
-  additionalRoleBindings:
-    - clusterRoleName: 'argoproj-provisioner'
-      subjects:
-        - apiGroup: rbac.authorization.k8s.io
-          kind: User
-          name: alice
-        - apiGroup: rbac.authorization.k8s.io
-          kind: User
-          name: joe
-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-argoproj-provisioner
-  namespace: oil-production
-subjects:
-  - kind: User
-    apiGroup: rbac.authorization.k8s.io
-    name: alice
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: ClusterRole
-  name: argoproj-provisioner
-```
-
-With the above example, Capsule is leaving the tenant owner to create namespaced custom resources.
-
-> Take Note: a tenant owner having the admin scope on its namespaces only, does not have the permission to create Custom Resources Definitions (CRDs) because this requires a cluster admin permission level. Only Bill, the cluster admin, can create CRDs. This is a known limitation of any multi-tenancy environment based on a single Kubernetes cluster.
-
-# What’s next
-See how Bill, the cluster admin, can set taints on Alice's namespaces. [Taint namespaces](./taint-namespaces.md).

docs/operator/use-cases/deny-wildcard-hostnames.md

@@ -1,32 +0,0 @@
-# Deny Wildcard Hostnames
-
-Bill, the cluster admin, can deny the use of wildcard hostnames.
-
-Let's assume that we had a big organization, having a domain `bigorg.com` and there are two tenants, `gas` and `oil`.
-
-As a tenant-owner of `gas`, Alice create ingress with the host like `- host: "*.bigorg.com"`. That can lead to big problems for the `oil` tenant because Alice can deliberately create ingress with host: `oil.bigorg.com`.
-
-To avoid this kind of problems, Bill can deny the use of wildcard hostnames in the following way:
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: gas
-  annotations:
-    capsule.clastix.io/deny-wildcard: true
-spec:
-  owners:
-  - name: alice
-    kind: User
-EOF
-```
-
-Doing this, Alice will not be able to use `oil.bigorg.com`, being the tenant-owner of `gas`.
-
-# What’s next
-
-This ends our tour in Capsule use cases. As we improve Capsule, more  use cases about multi-tenancy, policy admission control, and cluster  governance will be covered in the future.
-
-Stay tuned!

docs/operator/use-cases/hostname-collision.md

@@ -1,80 +0,0 @@
-# Control hostname collision in ingresses
-In a multi-tenant environment, as more and more ingresses are defined, there is a chance of collision on the hostname leading to unpredictable behavior of the Ingress Controller. Bill, the cluster admin, can enforce hostname collision detection at different scope levels:
-
-1. Cluster
-2. Tenant
-3. Namespace
-4. Disabled (default)
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  - name: joe
-    kind: User
-  ingressOptions:
-    hostnameCollisionScope: Tenant
-EOF
-```
-
-When a tenant owner creates an Ingress resource, Capsule will check the collision of hostname in the current ingress with all the hostnames already used, depending on the defined scope.
-
-For example, Alice, one of the tenant owners, creates an Ingress
-
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: nginx
-  namespace: oil-production
-spec:
-  rules:
-  - host: web.oil.acmecorp.com
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: nginx
-            port:
-              number: 80
-EOF
-```
-
-Another user, Joe creates an Ingress having the same hostname
-
-```yaml
-kubectl -n oil-development apply -f - << EOF
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: nginx
-  namespace: oil-development
-spec:
-  rules:
-  - host: web.oil.acmecorp.com
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: nginx
-            port:
-              number: 80
-EOF
-```
-
-When a collision is detected at scope defined by `spec.ingressOptions.hostnameCollisionScope`, the creation of the Ingress resource will be rejected by the Validation Webhook enforcing it. When `hostnameCollisionScope=Disabled`, no collision detection is made at all.
-
-# What’s next
-See how Bill, the cluster admin, can assign a Storage Class to Alice's tenant. [Assign Storage Classes](./storage-classes.md).

docs/operator/use-cases/images-pullpolicy.md

@@ -1,32 +0,0 @@
-# Enforcing Pod containers image PullPolicy
-
-Bill is a cluster admin providing a Container as a Service platform using shared nodes.
-
-Alice, a Tenant Owner, can start container images using private images: according to the Kubernetes architecture, the `kubelet` will download the layers on its cache.
-
-Bob, an attacker, could try to schedule a Pod on the same node where Alice is running her Pods backed by private images: they could start new Pods using `ImagePullPolicy=IfNotPresent` and be able to start them, even without required authentication since the image is cached on the node. 
-
-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
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  imagePullPolicies:
-  - Always
-EOF
-```
-
-Allowed values are: `Always`, `IfNotPresent`, `Never`.
-
-Any attempt of Alice to use a disallowed `imagePullPolicies` value is denied by the Validation Webhook enforcing it.
-
-# What’s next
-
-See how Bill, the cluster admin, can assign trusted images registries to Alice's tenant. [Assign Trusted Images Registries](./images-registries.md).

docs/operator/use-cases/images-registries.md

@@ -1,36 +0,0 @@
-# Assign Trusted Images Registries
-Bill, the cluster admin, can set a strict policy on the applications running into Alice's tenant: he'd like to allow running just images hosted on a list of specific container registries.
-
-The spec `containerRegistries` addresses this task and can provide a combination with hard enforcement using a list of allowed values.
-
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  containerRegistries:
-    allowed:
-    - docker.io
-    - quay.io
-    allowedRegex: 'internal.registry.\\w.tld'
-```
-
-> In case of `non-FQDI` (non fully qualified Docker image) and official images hosted on Docker Hub,
-> Capsule is going to retrieve the registry even if it's not explicit: a `busybox:latest` Pod
-> running on a Tenant allowing `docker.io` will not be blocked, even if the image
-> field is not explicit as `docker.io/busybox:latest`.
-
-A Pod running `internal.registry.foo.tld` as registry will be allowed, as well `internal.registry.bar.tld` since these are matching the regular expression.
-
-> A catch-all regex entry as `.*` allows every kind of registry, which would be the same result of unsetting `containerRegistries` at all.
-
-Any attempt of Alice to use a not allowed `containerRegistries` value is denied by the Validation Webhook enforcing it.
-
-# What’s next
-See how Bill, the cluster admin, can assign Pod Security Policies to Alice's tenant. [Assign Pod Security Policies](./pod-security-policies.md).

docs/operator/use-cases/ingress-classes.md

@@ -1,52 +0,0 @@
-# Assign Ingress Classes
-An Ingress Controller is used in Kubernetes to publish services and applications outside of the cluster. An Ingress Controller can be provisioned to accept only Ingresses with a given Ingress Class.
-
-Bill can assign a set of dedicated Ingress Classes to the `oil` tenant to force the applications in the `oil` tenant to be published only by the assigned Ingress Controller: 
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  ingressOptions:
-    allowedClasses:
-      allowed:
-      - default
-      allowedRegex: ^\w+-lb$
-EOF
-```
-
-Capsule assures that all Ingresses created in the tenant can use only one of the valid Ingress Classes.
-
-Alice can create an Ingress using only an allowed Ingress Class:
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: nginx
-  namespace: oil-production
-  annotations:
-    kubernetes.io/ingress.class: default
-spec:
-  rules:
-  - host: oil.acmecorp.com
-    http:
-      paths:
-      - backend:
-          serviceName: nginx
-          servicePort: 80
-        path: /
-EOF
-```
-
-Any attempt of Alice to use a non-valid Ingress Class, or missing it, is denied by the Validation Webhook enforcing it.
-
-# What’s next
-See how Bill, the cluster admin, can assign a set of dedicated ingress hostnames to Alice's tenant. [Assign Ingress Hostnames](./ingress-hostnames.md).

docs/operator/use-cases/ingress-hostnames.md

@@ -1,53 +0,0 @@
-# Assign Ingress Hostnames
-Bill can control ingress hostnames to the `oil` tenant to force the applications to be published only using the given hostname or set of hostnames: 
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  ingressOptions:
-    allowedHostnames:
-      allowed:
-        - oil.acmecorp.com
-      allowedRegex: ^.*acmecorp.com$
-EOF
-```
-
-The Capsule controller assures that all Ingresses created in the tenant can use only one of the valid hostnames.
-
-Alice can create an Ingress using any allowed hostname
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: nginx
-  namespace: oil-production
-  annotations:
-    kubernetes.io/ingress.class: oil
-spec:
-  rules:
-  - host: web.oil.acmecorp.com
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: nginx
-            port:
-              number: 80
-EOF
-```
-
-Any attempt of Alice to use a non-valid hostname is denied by the Validation Webhook enforcing it.
-
-# What’s next
-See how Bill, the cluster admin, can control the hostname collision in Ingresses. [Control hostname collision in ingresses](./hostname-collision.md).

docs/operator/use-cases/multiple-tenants.md

@@ -1,94 +0,0 @@
-# Assign multiple tenants to an owner
-In some scenarios, 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.
-
-By design, the Capsule operator does not permit a hierarchy of tenants, since all tenants are at the same levels. However, we can assign the ownership of multiple tenants to the same user or group of users.
-
-Bill, the cluster admin, creates multiple tenants having `alice` as owner:
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-EOF
-```
-
-and
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: gas
-spec:
-  owners:
-  - name: alice
-    kind: User
-EOF
-```
-
-Alternatively, the ownership can be assigned to a group called `oil-and-gas`:
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: oil-and-gas
-    kind: Group
-EOF
-```
-
-and
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: gas
-spec:
-  owners:
-  - name: oil-and-gas
-    kind: Group
-EOF
-```
-
-The two tenants remain isolated from each other in terms of resources assignments, e.g. _ResourceQuota_, _Nodes Pool_, _Storage Calsses_ and _Ingress Classes_, and in terms of governance, e.g. _NetworkPolicies_, _PodSecurityPolicies_, _Trusted Registries_, etc.
-
-
-When Alice logs in, she has access to all namespaces belonging to both the `oil` and `gas` tenants.
-
-```
-kubectl create ns oil-production
-kubectl create ns gas-production
-```
-
-When the enforcement of the naming convention with the `--force-tenant-prefix` option, is enabled, the namespaces are automatically assigned to the right tenant by Capsule because the operator does a lookup on the tenant names. If the `--force-tenant-prefix` option, is not set,   Alice needs to specify the tenant name as a label `capsule.clastix.io/tenant=<desired_tenant>` in the namespace manifest:
-
-```yaml
-kubectl apply -f - << EOF
-kind: Namespace
-apiVersion: v1
-metadata:
-  name: gas-production
-  labels:
-    capsule.clastix.io/tenant: gas
-EOF
-```
-
-> If not specified, Capsule will deny with the following message:
->`Unable to assign namespace to tenant. Please use capsule.clastix.io/tenant label when creating a namespace.`
-
-# What’s next
-
-See how Bill, the cluster admin, can cordon all the Namespaces belonging to a Tenant. [Cordoning a Tenant](./cordoning-tenant.md).

docs/operator/use-cases/namespace-labels-and-annotations.md

@@ -1,28 +0,0 @@
-# Denying user-defined labels or annotations
-
-By default, capsule allows tenant owners to add and modify any label or annotation on their namespaces. 
-
-But there are some scenarios, when tenant owners should not have an ability to add or modify specific labels or annotations (for example, this can be labels used in [Kubernetes network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) which are added by cluster administrator).
-
-Bill, the cluster admin, can deny Alice to add specific labels and annotations on namespaces:
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-  annotations:
-    capsule.clastix.io/forbidden-namespace-labels: foo.acme.net, bar.acme.net
-    capsule.clastix.io/forbidden-namespace-labels-regexp: .*.acme.net
-    capsule.clastix.io/forbidden-namespace-annotations: foo.acme.net, bar.acme.net
-    capsule.clastix.io/forbidden-namespace-annotations-regexp: .*.acme.net
-spec:
-  owners:
-  - name: alice
-    kind: User
-EOF
-```
-
-# What’s next
-Let's check it out how to restore Tenants after a Velero Backup. [Velero Backup Restoration](./velero-backup-restoration.md).

docs/operator/use-cases/network-policies.md

@@ -1,102 +0,0 @@
-# Assign Network Policies
-Kubernetes network policies control network traffic between namespaces and between pods in the same namespace. Bill, the cluster admin, can enforce network traffic isolation between different tenants while leaving to Alice, the tenant owner, the freedom to set isolation between namespaces in the same tenant or even between pods in the same namespace.
-
-To meet this requirement, Bill needs to define network policies that deny pods belonging to Alice's namespaces to access pods in namespaces belonging to other tenants, e.g. Bob's tenant `water`, or in system namespaces, e.g. `kube-system`.
-
-Also, Bill can make sure pods belonging to a tenant namespace cannot access other network infrastructures like cluster nodes, load balancers, and virtual machines running other services.  
-
-Bill can set network policies in the tenant manifest, according to the requirements:
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  networkPolicies:
-    items:
-    - policyTypes:
-      - Ingress
-      - Egress
-      egress:
-      - to:
-        - ipBlock:
-            cidr: 0.0.0.0/0
-            except:
-              - 192.168.0.0/16 
-      ingress:
-      - from:
-        - namespaceSelector:
-            matchLabels:
-              capsule.clastix.io/tenant: oil
-        - podSelector: {}
-        - ipBlock:
-            cidr: 192.168.0.0/16
-      podSelector: {}
-EOF
-```
-
-The Capsule controller, watching for namespace creation, creates the Network Policies for each namespace in the tenant.
-
-Alice has access to network policies:
-
-```
-kubectl -n oil-production get networkpolicies
-NAME            POD-SELECTOR   AGE
-capsule-oil-0   <none>         42h
-```
-
-Alice can create, patch, and delete additional network policies within her namespaces
-
-```
-kubectl -n oil-production auth can-i get networkpolicies
-yes
-
-kubectl -n oil-production auth can-i delete networkpolicies
-yes
-
-kubectl -n oil-production auth can-i patch networkpolicies
-yes
-```
-
-For example, she can create
-
-```yaml
-kubectl -n oil-production apply -f - << EOF
-apiVersion: networking.k8s.io/v1
-kind: NetworkPolicy
-metadata:
-  labels:
-  name: production-network-policy
-  namespace: oil-production
-spec:
-  podSelector: {}
-  policyTypes:
-  - Ingress
-  - Egress
-EOF
-```
-
-Check all the network policies
-
-```
-kubectl -n oil-production get networkpolicies
-NAME                        POD-SELECTOR   AGE
-capsule-oil-0               <none>         42h
-production-network-policy   <none>         3m
-```
-
-And delete the namespace network policies
-
-```
-kubectl -n oil-production delete networkpolicy production-network-policy
-```
-
-Any attempt of Alice to delete the tenant network policy defined in the tenant manifest is denied by the Validation Webhook enforcing it.
-
-# What’s next
-See how Bill can enforce the Pod containers image pull policy to `Always` to avoid leaking of private images when running on shared nodes. [Enforcing Pod containers image PullPolicy](./images-pullpolicy.md)

docs/operator/use-cases/nodes-pool.md

@@ -1,64 +0,0 @@
-# Assign a node's pool
-Bill, the cluster admin, can dedicate a pool of worker nodes to the `oil` tenant, to isolate the tenant applications from other noisy neighbors.
-
-These nodes are labeled by Bill as `pool=oil`
-
-```
-kubectl get nodes --show-labels
-
-NAME                      STATUS   ROLES             AGE   VERSION   LABELS
-...
-worker06.acme.com         Ready    worker            8d    v1.18.2   pool=oil
-worker07.acme.com         Ready    worker            8d    v1.18.2   pool=oil
-worker08.acme.com         Ready    worker            8d    v1.18.2   pool=oil
-```
-
-The label `pool=oil` is defined as node selector in the tenant manifest:
-
-```yaml
-kubectl apply -f - << EOF
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  nodeSelector:
-    pool: oil
-    kubernetes.io/os: linux
-EOF
-```
-
-The Capsule controller makes sure that any namespace created in the tenant has the annotation: `scheduler.alpha.kubernetes.io/node-selector: pool=oil`. This annotation tells the scheduler of Kubernetes to assign the node selector `pool=oil` to all the pods deployed in the tenant. The effect is that all the pods deployed by Alice are placed only on the designated pool of nodes.
-
-Multiple node selector labels can be defined as in the following snippet:
-
-```yaml
-apiVersion: capsule.clastix.io/v1beta1
-kind: Tenant
-metadata:
-  name: oil
-spec:
-  owners:
-  - name: alice
-    kind: User
-  nodeSelector:
-    pool: oil
-    kubernetes.io/os: linux
-    kubernetes.io/arch: amd64
-    hardware: gpu
-```
-
-Any attempt of Alice to change the selector on the pods will result in an error from the `PodNodeSelector` Admission Controller plugin.
-
-Also, RBAC prevents Alice to change the annotation on the namespace:
-
-```
-kubectl auth can-i edit ns -n oil-production
-no
-```
-
-# What’s next
-See how Bill, the cluster admin, can assign an Ingress Class to Alice's tenant. [Assign Ingress Classes](./ingress-classes.md).