Skip to content

Commit fb0c625

Browse files
Svarrogh1337Svarrogh1337
authored
Merge pull request #77 from projectcapsule/chore/fix-polito-logo
chore(website) update politecnico di torino logo url
2 parents 15ceed8 + d039719 commit fb0c625

2 files changed

Lines changed: 266 additions & 1 deletion

File tree

‎content/en/docs/tenants/rules.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
title: Rules
3+
weight: 5
4+
description: >
5+
Configure policies and restrictions on tenant-basis with Rules
6+
---
7+
8+
Enforcement rules allow Bill, the cluster admin, to set policies and restrictions on a per-`Tenant` basis. These rules are enforced by Capsule Admission Webhooks when Alice, the `TenantOwner`, creates or modifies resources in her `Namespaces`. With the Rule Construct we can profile namespaces within a tenant to adhere to specific policies, depending on metadata.
9+
10+
## Namespace Selector
11+
12+
By default a rule is applied to all namespaces within a `Tenant`. However you can select a subset of namespaces to apply the rule on, by using a `namespaceSelector`. This selector works the same way as a standard Kubernetes label selector:
13+
14+
```yaml
15+
---
16+
apiVersion: capsule.clastix.io/v1beta2
17+
kind: Tenant
18+
metadata:
19+
name: solar
20+
spec:
21+
...
22+
rules:
23+
# Matches all Namespaces and enforces the rule for all of them
24+
- enforce:
25+
registries:
26+
- url: "harbor/v2/customer-registry/.*"
27+
policy: [ "ifNotPresent" ]
28+
29+
# Select a subset of namespaces (enviornment=prod) to allow further registries
30+
- namespaceSelector:
31+
matchExpressions:
32+
- key: env
33+
operator: In
34+
values: ["prod"]
35+
enforce:
36+
registries:
37+
- url: "harbor/v2/prod-registry/.*"
38+
policy: [ "ifNotPresent" ]
39+
```
40+
41+
Note that rules are combined together. In the above example, all namespaces within the `solar` tenant will be enforced to use images from `harbor/v2/customer-registry/*`, while namespaces labeled with `env=prod` will also be allowed to pull images from `harbor/v2/prod-registry/*`.
42+
43+
## Enforcement
44+
45+
Declare Enforcement rules for the selected namespaces.
46+
47+
### Registries
48+
49+
Define allowed image registries for `Pods` with rules. Each registry can have specific policies and validation targets. We use Regexp pattern matching for the registry URL, so you can specify patterns like `harbor/v2/customer-registry/*` to match all images from that registry. The matching is done against the full image name, including the path and tag. The ordering is based on the order of declaration, so the first matching rule will be applied. The later the match is found, the higher the precedence. This allows you to build constructs like these:
50+
51+
```yaml
52+
---
53+
apiVersion: capsule.clastix.io/v1beta2
54+
kind: Tenant
55+
metadata:
56+
name: solar
57+
spec:
58+
...
59+
rules:
60+
- enforce:
61+
registries:
62+
63+
# Enforce PullPolicy "always" for all registries (For Container Images and Volume Images)
64+
- url: ".*"
65+
policy: [ "Always" ]
66+
67+
# If we are pulling from a harbor registry we want to verify the images for Containers only
68+
- url: "harbor/.*"
69+
70+
- namespaceSelector:
71+
matchExpressions:
72+
- key: env
73+
operator: In
74+
values: ["prod"]
75+
enforce:
76+
registries:
77+
- url: "harbor/v2/customer-registry/prod-image/.*"
78+
policy: [ "Always" ]
79+
```
80+
81+
Let's try to apply the following pod in the namespace `solar-test` (Does not match the `env=prod` selector):
82+
83+
```yaml
84+
apiVersion: v1
85+
kind: Pod
86+
metadata:
87+
name: image-volume
88+
spec:
89+
containers:
90+
91+
- name: shell
92+
command: ["sleep", "infinity"]
93+
imagePullPolicy: Never
94+
image: harbor/v2/prod-registry/debian
95+
volumeMounts:
96+
- name: volume
97+
mountPath: /volume
98+
99+
volumes:
100+
- name: volume
101+
image:
102+
reference: quay.io/crio/artifact:v2
103+
pullPolicy: IfNotPresent
104+
105+
106+
```
107+
108+
**What do you expect to happen?**
109+
110+
```bash
111+
kubectl apply -f pod.yaml -n solar-test
112+
113+
Error from server (Forbidden): error when creating "pod.yaml": admission webhook "pods.projectcapsule.dev" denied the request: containers[0] reference "harbor/v2/prod-registry/debian" uses pullPolicy=Never which is not allowed (allowed: Always)
114+
```
115+
116+
Because our first rule enforces all registries to use the `always` image pull policy, the pod creation is denied because it uses the `Never` policy. We can either allow the `Never` policy for this specific registry:
117+
118+
```yaml
119+
---
120+
apiVersion: capsule.clastix.io/v1beta2
121+
kind: Tenant
122+
metadata:
123+
name: solar
124+
spec:
125+
...
126+
rules:
127+
- enforce:
128+
registries:
129+
130+
# Enforce PullPolicy "always" for all registries (For Container Images and Volume Images)
131+
- url: ".*"
132+
policy: [ "Always" ]
133+
134+
# If we are pulling from a harbor registry we want to verify the images for Containers only
135+
- url: "harbor/.*"
136+
policy: [ "Never" ]
137+
138+
- namespaceSelector:
139+
matchExpressions:
140+
- key: env
141+
operator: In
142+
values: ["prod"]
143+
enforce:
144+
registries:
145+
- url: "harbor/v2/customer-registry/prod-image/.*"
146+
policy: [ "always" ]
147+
```
148+
149+
But let's for now also remove the generic rule for all registries and only keep the harbor one:
150+
151+
```yaml
152+
---
153+
apiVersion: capsule.clastix.io/v1beta2
154+
kind: Tenant
155+
metadata:
156+
name: solar
157+
spec:
158+
...
159+
rules:
160+
- enforce:
161+
registries:
162+
163+
# If we are pulling from a harbor registry we want to verify the images for Containers only
164+
- url: "harbor/.*"
165+
policy: [ "Never" ]
166+
167+
- namespaceSelector:
168+
matchExpressions:
169+
- key: env
170+
operator: In
171+
values: ["prod"]
172+
enforce:
173+
registries:
174+
- url: "harbor/v2/customer-registry/prod-image/.*"
175+
policy: [ "Always" ]
176+
```
177+
178+
If we try to apply the pod again, it we will still get an error. The problem is that we are mounting an image volume that is not coming from the allowed harbor registry:
179+
180+
```bash
181+
Error from server (Forbidden): error when creating "pod.yaml": admission webhook "pods.projectcapsule.dev" denied the request: volumes[0](volume) reference "quay.io/crio/artifact:v2" is not allowed
182+
```
183+
184+
However we would like to only validate the images used in the Pod spec (Containers, InitContainers, EphemeralContainers) and not the ones used in the Volumes. We can achieve this by specifying the [`validation`](#validation) field for the harbor registry:
185+
186+
```yaml
187+
---
188+
apiVersion: capsule.clastix.io/v1beta2
189+
kind: Tenant
190+
metadata:
191+
name: solar
192+
spec:
193+
...
194+
rules:
195+
- enforce:
196+
registries:
197+
# If we are pulling from a harbor registry we want to verify the images for Containers only
198+
- url: "harbor/.*"
199+
policy: [ "Never" ]
200+
validation:
201+
- "pod/images"
202+
203+
- namespaceSelector:
204+
matchExpressions:
205+
- key: env
206+
operator: In
207+
values: ["prod"]
208+
enforce:
209+
registries:
210+
- url: "harbor/v2/customer-registry/prod-image/.*"
211+
policy: [ "Always" ]
212+
```
213+
214+
#### Policy
215+
216+
Define the allowed image pull policies for the specified registry URL. Supported policies are:
217+
218+
* `Always`: The image is always pulled.
219+
* `IfNotPresent`: The image is pulled only if it is not already present on the node.
220+
* `Never`: The image is never pulled. If the image is not present on the node, the Pod will fail to start.
221+
222+
This configuration is optional. If no policy is specified, all image pull policies are allowed for the given registry.
223+
224+
```yaml
225+
---
226+
apiVersion: capsule.clastix.io/v1beta2
227+
kind: Tenant
228+
metadata:
229+
name: solar
230+
spec:
231+
...
232+
rules:
233+
# Matches all Namespaces and enforces the rule for all of them
234+
- enforce:
235+
registries:
236+
- url: "harbor/v2/customer-registry/.*"
237+
policy: [ "IfNotPresent", "Always" ]
238+
```
239+
240+
241+
#### Validation
242+
243+
Define on which parts of the Pod the registry policy must be validated. Currently supported validation targets are:
244+
245+
* `pod/images`: Validate the images used in the Pod spec (For `Containers`, `InitContainers` and `EphemeralContainers`).
246+
* `pod/volumes`: Validate the images used in the Pod `Volumes` ([Read More](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/))
247+
248+
**By default, both targets are validated**. You can override this behavior by specifying the `validation` field for each registry:
249+
250+
```yaml
251+
---
252+
apiVersion: capsule.clastix.io/v1beta2
253+
kind: Tenant
254+
metadata:
255+
name: solar
256+
spec:
257+
...
258+
rules:
259+
# Matches all Namespaces and enforces the rule for all of them
260+
- enforce:
261+
registries:
262+
- url: "harbor/v2/customer-registry/.*"
263+
validation:
264+
- "pod/images"
265+
```

‎data/adopters.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ adopters:
3131
logo: https://www.pitsdatarecovery.com/wp-content/uploads/2020/09/pits-logo.svg
3232
- name: Politecnico di Torino
3333
link: https://www.polito.it/
34-
logo: https://www.polito.it/themes/custom/polito/logo.svg
34+
logo: https://www.polito.it/themes/custom/polito_customizations/polito_logo_desktop.svg
3535
- name: Reevo
3636
link: https://www.reevo.it/
3737
logo: https://www.reevo.it/hs-fs/hubfs/logo_reevo_azzurro.png?width=95&height=40&name=logo_reevo_azzurro.png

0 commit comments

Comments
 (0)