Skip to content

Commit 9360ca7

Browse files
Svarrogh1337Svarrogh1337
authored
feat(docs): add DRA documentation (#62)
* feat(docs): add DRA documentation Signed-off-by: Hristo Hristov <me@hhristov.info> * feat(docs): add DRA documentation Signed-off-by: Hristo Hristov <me@hhristov.info> * feat(docs): add DRA documentation Signed-off-by: Hristo Hristov <me@hhristov.info> --------- Signed-off-by: Hristo Hristov <me@hhristov.info>
1 parent 4eb630a commit 9360ca7

3 files changed

Lines changed: 132 additions & 32 deletions

File tree

‎content/en/docs/proxy/reference.md‎

Lines changed: 78 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,14 @@ Resource Types:
2828

2929
GlobalProxySettings is the Schema for the globalproxysettings API.
3030

31+
3132
| **Name** | **Type** | **Description** | **Required** |
3233
| :---- | :---- | :----------- | :-------- |
3334
| **apiVersion** | string | capsule.clastix.io/v1beta1 | true |
3435
| **kind** | string | GlobalProxySettings | true |
3536
| **[metadata](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)** | object | Refer to the Kubernetes API documentation for the fields of the `metadata` field. | true |
36-
| **[spec](#globalproxysettingsspec)** | object | GlobalProxySettingsSpec defines the desired state of GlobalProxySettings. | false |
37+
| **[spec](#globalproxysettingsspec)** | object |GlobalProxySettingsSpec defines the desired state of GlobalProxySettings.
38+
| false |
3739

3840

3941
### GlobalProxySettings.spec
@@ -42,9 +44,11 @@ GlobalProxySettings is the Schema for the globalproxysettings API.
4244

4345
GlobalProxySettingsSpec defines the desired state of GlobalProxySettings.
4446

47+
4548
| **Name** | **Type** | **Description** | **Required** |
4649
| :---- | :---- | :----------- | :-------- |
47-
| **[rules](#globalproxysettingsspecrulesindex)** | []object | Subjects that should receive additional permissions.<br>The subjects are selected based on the oncoming requests. They don't have to relate to an existing tenant.<br>However they must be part of the capsule-user groups. | true |
50+
| **[rules](#globalproxysettingsspecrulesindex)** | []object |Subjects that should receive additional permissions.<br>The subjects are selected based on the oncoming requests. They don't have to relate to an existing tenant.<br>However they must be part of the capsule-user groups.
51+
| true |
4852

4953

5054
### GlobalProxySettings.spec.rules[index]
@@ -53,10 +57,13 @@ GlobalProxySettingsSpec defines the desired state of GlobalProxySettings.
5357

5458

5559

60+
5661
| **Name** | **Type** | **Description** | **Required** |
5762
| :---- | :---- | :----------- | :-------- |
58-
| **[subjects](#globalproxysettingsspecrulesindexsubjectsindex)** | []object | Subjects that should receive additional permissions.<br>The subjects are selected based on the oncoming requests. They don't have to relate to an existing tenant.<br>However they must be part of the capsule-user groups. | true |
59-
| **[clusterResources](#globalproxysettingsspecrulesindexclusterresourcesindex)** | []object | Cluster Resources for tenant Owner. | false |
63+
| **[subjects](#globalproxysettingsspecrulesindexsubjectsindex)** | []object |Subjects that should receive additional permissions.<br>The subjects are selected based on the oncoming requests. They don't have to relate to an existing tenant.<br>However they must be part of the capsule-user groups.
64+
| true |
65+
| **[clusterResources](#globalproxysettingsspecrulesindexclusterresourcesindex)** | []object |Cluster Resources for tenant Owner.
66+
| false |
6067

6168

6269
### GlobalProxySettings.spec.rules[index].subjects[index]
@@ -65,10 +72,13 @@ GlobalProxySettingsSpec defines the desired state of GlobalProxySettings.
6572

6673

6774

75+
6876
| **Name** | **Type** | **Description** | **Required** |
6977
| :---- | :---- | :----------- | :-------- |
70-
| **kind** | enum | Kind of tenant owner. Possible values are "User", "Group", and "ServiceAccount".<br/>*Enum*: User, Group, ServiceAccount<br/> | true |
71-
| **name** | string | Name of tenant owner. | true |
78+
| **kind** | enum |Kind of tenant owner. Possible values are "User", "Group", and "ServiceAccount".<br/>*Enum*: User, Group, ServiceAccount<br/>
79+
| true |
80+
| **name** | string |Name of tenant owner.
81+
| true |
7282

7383

7484
### GlobalProxySettings.spec.rules[index].clusterResources[index]
@@ -77,12 +87,17 @@ GlobalProxySettingsSpec defines the desired state of GlobalProxySettings.
7787

7888

7989

90+
8091
| **Name** | **Type** | **Description** | **Required** |
8192
| :---- | :---- | :----------- | :-------- |
82-
| **apiGroups** | []string | APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against any resource listed will be allowed. '*' represents all resources. Empty string represents v1 api resources. | true |
83-
| **resources** | []string | Resources is a list of resources this rule applies to. '*' represents all resources. | true |
84-
| **[selector](#globalproxysettingsspecrulesindexclusterresourcesindexselector)** | object | Select all cluster scoped resources with the given label selector.<br>Defining a selector which does not match any resources is considered not selectable (eg. using operation NotExists). | true |
85-
| **operations** | []enum | Operations which can be executed on the selected resources.<br>Deprecated: For all registered Routes only LIST ang GET requests will intercepted<br>Other permissions must be implemented via kubernetes native RBAC<br/>*Enum*: List, Update, Delete<br/> | false |
93+
| **apiGroups** | []string |APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against any resource listed will be allowed. '*' represents all resources. Empty string represents v1 api resources.
94+
| true |
95+
| **resources** | []string |Resources is a list of resources this rule applies to. '*' represents all resources.
96+
| true |
97+
| **[selector](#globalproxysettingsspecrulesindexclusterresourcesindexselector)** | object |Select all cluster scoped resources with the given label selector.<br>Defining a selector which does not match any resources is considered not selectable (eg. using operation NotExists).
98+
| true |
99+
| **operations** | []enum |<span style="color:red;font-weight:bold">Operations which can be executed on the selected resources.<br>Deprecated: For all registered Routes only LIST ang GET requests will intercepted<br>Other permissions must be implemented via kubernetes native RBAC</span><br/>*Enum*: List, Update, Delete<br/>
100+
| false |
86101

87102

88103
### GlobalProxySettings.spec.rules[index].clusterResources[index].selector
@@ -92,10 +107,13 @@ GlobalProxySettingsSpec defines the desired state of GlobalProxySettings.
92107
Select all cluster scoped resources with the given label selector.
93108
Defining a selector which does not match any resources is considered not selectable (eg. using operation NotExists).
94109

110+
95111
| **Name** | **Type** | **Description** | **Required** |
96112
| :---- | :---- | :----------- | :-------- |
97-
| **[matchExpressions](#globalproxysettingsspecrulesindexclusterresourcesindexselectormatchexpressionsindex)** | []object | matchExpressions is a list of label selector requirements. The requirements are ANDed. | false |
98-
| **matchLabels** | map[string]string | matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels<br>map is equivalent to an element of matchExpressions, whose key field is "key", the<br>operator is "In", and the values array contains only "value". The requirements are ANDed. | false |
113+
| **[matchExpressions](#globalproxysettingsspecrulesindexclusterresourcesindexselectormatchexpressionsindex)** | []object |matchExpressions is a list of label selector requirements. The requirements are ANDed.
114+
| false |
115+
| **matchLabels** | map[string]string |matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels<br>map is equivalent to an element of matchExpressions, whose key field is "key", the<br>operator is "In", and the values array contains only "value". The requirements are ANDed.
116+
| false |
99117

100118

101119
### GlobalProxySettings.spec.rules[index].clusterResources[index].selector.matchExpressions[index]
@@ -105,11 +123,15 @@ Defining a selector which does not match any resources is considered not selecta
105123
A label selector requirement is a selector that contains values, a key, and an operator that
106124
relates the key and values.
107125

126+
108127
| **Name** | **Type** | **Description** | **Required** |
109128
| :---- | :---- | :----------- | :-------- |
110-
| **key** | string | key is the label key that the selector applies to. | true |
111-
| **operator** | string | operator represents a key's relationship to a set of values.<br>Valid operators are In, NotIn, Exists and DoesNotExist. | true |
112-
| **values** | []string | values is an array of string values. If the operator is In or NotIn,<br>the values array must be non-empty. If the operator is Exists or DoesNotExist,<br>the values array must be empty. This array is replaced during a strategic<br>merge patch. | false |
129+
| **key** | string |key is the label key that the selector applies to.
130+
| true |
131+
| **operator** | string |operator represents a key's relationship to a set of values.<br>Valid operators are In, NotIn, Exists and DoesNotExist.
132+
| true |
133+
| **values** | []string |values is an array of string values. If the operator is In or NotIn,<br>the values array must be non-empty. If the operator is Exists or DoesNotExist,<br>the values array must be empty. This array is replaced during a strategic<br>merge patch.
134+
| false |
113135

114136
## ProxySetting
115137

@@ -120,12 +142,14 @@ relates the key and values.
120142

121143
ProxySetting is the Schema for the proxysettings API.
122144

145+
123146
| **Name** | **Type** | **Description** | **Required** |
124147
| :---- | :---- | :----------- | :-------- |
125148
| **apiVersion** | string | capsule.clastix.io/v1beta1 | true |
126149
| **kind** | string | ProxySetting | true |
127150
| **[metadata](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)** | object | Refer to the Kubernetes API documentation for the fields of the `metadata` field. | true |
128-
| **[spec](#proxysettingspec)** | object | ProxySettingSpec defines the additional Capsule Proxy settings for additional users of the Tenant.<br>Resource is Namespace-scoped and applies the settings to the belonged Tenant. | false |
151+
| **[spec](#proxysettingspec)** | object |ProxySettingSpec defines the additional Capsule Proxy settings for additional users of the Tenant.<br>Resource is Namespace-scoped and applies the settings to the belonged Tenant.
152+
| false |
129153

130154

131155
### ProxySetting.spec
@@ -135,9 +159,11 @@ ProxySetting is the Schema for the proxysettings API.
135159
ProxySettingSpec defines the additional Capsule Proxy settings for additional users of the Tenant.
136160
Resource is Namespace-scoped and applies the settings to the belonged Tenant.
137161

162+
138163
| **Name** | **Type** | **Description** | **Required** |
139164
| :---- | :---- | :----------- | :-------- |
140-
| **[subjects](#proxysettingspecsubjectsindex)** | []object | Subjects that should receive additional permissions. | true |
165+
| **[subjects](#proxysettingspecsubjectsindex)** | []object |Subjects that should receive additional permissions.
166+
| true |
141167

142168

143169
### ProxySetting.spec.subjects[index]
@@ -146,12 +172,17 @@ Resource is Namespace-scoped and applies the settings to the belonged Tenant.
146172

147173

148174

175+
149176
| **Name** | **Type** | **Description** | **Required** |
150177
| :---- | :---- | :----------- | :-------- |
151-
| **kind** | enum | Kind of tenant owner. Possible values are "User", "Group", and "ServiceAccount"<br/>*Enum*: User, Group, ServiceAccount<br/> | true |
152-
| **name** | string | Name of tenant owner. | true |
153-
| **[clusterResources](#proxysettingspecsubjectsindexclusterresourcesindex)** | []object | Cluster Resources for tenant Owner. | false |
154-
| **[proxySettings](#proxysettingspecsubjectsindexproxysettingsindex)** | []object | Proxy settings for tenant owner. | false |
178+
| **kind** | enum |Kind of tenant owner. Possible values are "User", "Group", and "ServiceAccount"<br/>*Enum*: User, Group, ServiceAccount<br/>
179+
| true |
180+
| **name** | string |Name of tenant owner.
181+
| true |
182+
| **[clusterResources](#proxysettingspecsubjectsindexclusterresourcesindex)** | []object |Cluster Resources for tenant Owner.
183+
| false |
184+
| **[proxySettings](#proxysettingspecsubjectsindexproxysettingsindex)** | []object |Proxy settings for tenant owner.
185+
| false |
155186

156187

157188
### ProxySetting.spec.subjects[index].clusterResources[index]
@@ -160,12 +191,17 @@ Resource is Namespace-scoped and applies the settings to the belonged Tenant.
160191

161192

162193

194+
163195
| **Name** | **Type** | **Description** | **Required** |
164196
| :---- | :---- | :----------- | :-------- |
165-
| **apiGroups** | []string | APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against any resource listed will be allowed. '*' represents all resources. Empty string represents v1 api resources. | true |
166-
| **resources** | []string | Resources is a list of resources this rule applies to. '*' represents all resources. | true |
167-
| **[selector](#proxysettingspecsubjectsindexclusterresourcesindexselector)** | object | Select all cluster scoped resources with the given label selector.<br>Defining a selector which does not match any resources is considered not selectable (eg. using operation NotExists). | true |
168-
| **operations** | []enum | Operations which can be executed on the selected resources.<br>Deprecated: For all registered Routes only LIST ang GET requests will intercepted<br>Other permissions must be implemented via kubernetes native RBAC<br/>*Enum*: List, Update, Delete<br/> | false |
197+
| **apiGroups** | []string |APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against any resource listed will be allowed. '*' represents all resources. Empty string represents v1 api resources.
198+
| true |
199+
| **resources** | []string |Resources is a list of resources this rule applies to. '*' represents all resources.
200+
| true |
201+
| **[selector](#proxysettingspecsubjectsindexclusterresourcesindexselector)** | object |Select all cluster scoped resources with the given label selector.<br>Defining a selector which does not match any resources is considered not selectable (eg. using operation NotExists).
202+
| true |
203+
| **operations** | []enum |<span style="color:red;font-weight:bold">Operations which can be executed on the selected resources.<br>Deprecated: For all registered Routes only LIST ang GET requests will intercepted<br>Other permissions must be implemented via kubernetes native RBAC</span><br/>*Enum*: List, Update, Delete<br/>
204+
| false |
169205

170206

171207
### ProxySetting.spec.subjects[index].clusterResources[index].selector
@@ -175,10 +211,13 @@ Resource is Namespace-scoped and applies the settings to the belonged Tenant.
175211
Select all cluster scoped resources with the given label selector.
176212
Defining a selector which does not match any resources is considered not selectable (eg. using operation NotExists).
177213

214+
178215
| **Name** | **Type** | **Description** | **Required** |
179216
| :---- | :---- | :----------- | :-------- |
180-
| **[matchExpressions](#proxysettingspecsubjectsindexclusterresourcesindexselectormatchexpressionsindex)** | []object | matchExpressions is a list of label selector requirements. The requirements are ANDed. | false |
181-
| **matchLabels** | map[string]string | matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels<br>map is equivalent to an element of matchExpressions, whose key field is "key", the<br>operator is "In", and the values array contains only "value". The requirements are ANDed. | false |
217+
| **[matchExpressions](#proxysettingspecsubjectsindexclusterresourcesindexselectormatchexpressionsindex)** | []object |matchExpressions is a list of label selector requirements. The requirements are ANDed.
218+
| false |
219+
| **matchLabels** | map[string]string |matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels<br>map is equivalent to an element of matchExpressions, whose key field is "key", the<br>operator is "In", and the values array contains only "value". The requirements are ANDed.
220+
| false |
182221

183222

184223
### ProxySetting.spec.subjects[index].clusterResources[index].selector.matchExpressions[index]
@@ -188,11 +227,15 @@ Defining a selector which does not match any resources is considered not selecta
188227
A label selector requirement is a selector that contains values, a key, and an operator that
189228
relates the key and values.
190229

230+
191231
| **Name** | **Type** | **Description** | **Required** |
192232
| :---- | :---- | :----------- | :-------- |
193-
| **key** | string | key is the label key that the selector applies to. | true |
194-
| **operator** | string | operator represents a key's relationship to a set of values.<br>Valid operators are In, NotIn, Exists and DoesNotExist. | true |
195-
| **values** | []string | values is an array of string values. If the operator is In or NotIn,<br>the values array must be non-empty. If the operator is Exists or DoesNotExist,<br>the values array must be empty. This array is replaced during a strategic<br>merge patch. | false |
233+
| **key** | string |key is the label key that the selector applies to.
234+
| true |
235+
| **operator** | string |operator represents a key's relationship to a set of values.<br>Valid operators are In, NotIn, Exists and DoesNotExist.
236+
| true |
237+
| **values** | []string |values is an array of string values. If the operator is In or NotIn,<br>the values array must be non-empty. If the operator is Exists or DoesNotExist,<br>the values array must be empty. This array is replaced during a strategic<br>merge patch.
238+
| false |
196239

197240

198241
### ProxySetting.spec.subjects[index].proxySettings[index]
@@ -201,8 +244,11 @@ relates the key and values.
201244

202245

203246

247+
204248
| **Name** | **Type** | **Description** | **Required** |
205249
| :---- | :---- | :----------- | :-------- |
206-
| **kind** | enum | <br/>*Enum*: Nodes, StorageClasses, IngressClasses, PriorityClasses, RuntimeClasses, PersistentVolumes<br/> | true |
207-
| **operations** | []enum | <br/>*Enum*: List, Update, Delete<br/> | true |
250+
| **kind** | enum |<br/>*Enum*: Nodes, StorageClasses, IngressClasses, PriorityClasses, RuntimeClasses, PersistentVolumes<br/>
251+
| true |
252+
| **operations** | []enum |<br/>*Enum*: List, Update, Delete<br/>
253+
| true |
208254

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,7 +350,59 @@ Any attempt of Alice to change the selector on the `Pods` will result in an erro
350350
kubectl auth can-i edit ns -n solar-production
351351
no
352352
```
353+
### Dynamic resource allocation (DRA)
354+
Dynamic Resource Allocation (DRA) is a Kubernetes capability that allows Pods to request and use shared resources, typically external devices such as hardware accelerators.
355+
See [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/) for more information.
353356

357+
Bill can assign a set of dedicated `DeviceClasses` to tell the `solar` `Tenant` what devices they can request.
358+
```yaml
359+
apiVersion: resource.k8s.io/v1
360+
kind: DeviceClass
361+
metadata:
362+
name: gpu.example.com
363+
labels:
364+
env: "production"
365+
spec:
366+
selectors:
367+
- cel:
368+
expression: device.driver == 'gpu.example.com' && device.attributes['gpu.example.com'].type
369+
== 'gpu'
370+
extendedResourceName: example.com/gpu
371+
```
372+
373+
```yaml
374+
apiVersion: capsule.clastix.io/v1beta2
375+
kind: Tenant
376+
metadata:
377+
name: solar
378+
spec:
379+
owners:
380+
- name: alice
381+
kind: User
382+
deviceClasses:
383+
matchLabels:
384+
env: "production"
385+
```
386+
With the said Tenant specification, Alice can create a ResourceClaim or ResourceClaimTemplate resource if spec.devices.requests[].deviceClassName ( ResourceClaim) or spec.spec.devices.requests[].deviceClassName ( ResourceClaimTemplate) equals to:
387+
388+
* Any DeviceClass, which has the label env with the value production
389+
390+
If any of the devices in the ResourceClaim or ResourceClaimTemplate spec is going to use a non-allowed DeviceClass, the entire request will be rejected by the Validation Webhook enforcing it.
391+
392+
Alice now can create a ResourceClaim using only an allowed DeviceClass:
393+
```yaml
394+
apiVersion: resource.k8s.io/v1
395+
kind: ResourceClaim
396+
metadata:
397+
name: example-resource-claim
398+
namespace: solar-production
399+
spec:
400+
devices:
401+
requests:
402+
- name: gpu-request
403+
exactly:
404+
deviceClassName: 'gpu.example.com'
405+
```
354406
## Connectivity
355407

356408
### Services

0 commit comments

Comments
 (0)