From e7b33bda26b449c37e37b87670527627b9d22d22 Mon Sep 17 00:00:00 2001
From: Dario Tranchitella <dario@tranchitella.eu>
Date: Sat, 12 Jun 2021 10:05:30 +0200
Subject: [PATCH] docs: documenting ImagePullPolicy enforcement

---
 docs/operator/use-cases/images-pullpolicy.md | 34 ++++++++++++++++++++
 docs/operator/use-cases/network-policies.md  |  3 +-
 docs/operator/use-cases/overview.md          |  1 +
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 docs/operator/use-cases/images-pullpolicy.md

diff --git a/docs/operator/use-cases/images-pullpolicy.md b/docs/operator/use-cases/images-pullpolicy.md
new file mode 100644
index 00000000..42a2ff7a
--- /dev/null
+++ b/docs/operator/use-cases/images-pullpolicy.md
@@ -0,0 +1,34 @@
+# 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 their Pod backed by private images: they could start new Pods using `ImagePullPolicy=IfNotPresent` and able to start them, even without required authentication since the image is cached on the node. 
+
+To avoid this kind of attack all the Tenant Owners must start their Pods using the `ImagePullPolicy` to `Always`, enforcing the `kubelet` to check the authorization first.
+
+Capsule provides a way to enforce this behavior, as follows.
+
+```yaml
+apiVersion: capsule.clastix.io/v1alpha1
+kind: Tenant
+metadata:
+  name: oil
+  annotations:
+    capsule.clastix.io/allowed-image-pull-policy: Always
+spec:
+  owner:
+    name: alice
+    kind: User
+```
+
+> If you need to address specific use-case, the said annotation supports multiple values comme separated
+> 
+> ```yaml
+> capsule.clastix.io/allowed-image-pull-policy: Always,IfNotPresent
+> ```
+
+# 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).
diff --git a/docs/operator/use-cases/network-policies.md b/docs/operator/use-cases/network-policies.md
index a94586cf..24c4f4b2 100644
--- a/docs/operator/use-cases/network-policies.md
+++ b/docs/operator/use-cases/network-policies.md
@@ -100,4 +100,5 @@ Error from server (Capsule Network Policies cannot be deleted: please, reach out
 ```
 
 # 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).
\ No newline at end of file
+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)
diff --git a/docs/operator/use-cases/overview.md b/docs/operator/use-cases/overview.md
index dc4f6377..68c2080d 100644
--- a/docs/operator/use-cases/overview.md
+++ b/docs/operator/use-cases/overview.md
@@ -32,6 +32,7 @@ Bill, at Acme Corp. can use Capsule to address any of the following scenarios:
 * [Assign Storage Classes](./storage-classes.md)
 * [Disable NodePort Services](./node-ports.md)
 * [Assign Network Policies](./network-policies.md)
+* [Enforcing Pod containers image PullPolicy](./images-pullpolicy.md)
 * [Assign Trusted Images Registries](./images-registries.md)
 * [Assign Pod Security Policies](./pod-security-policies.md)
 * [Create Custom Resources](./custom-resources.md)