Merge pull request #48330 from pohly/dra-1.32

DRA 1.32: beta

Author: k8s-ci-robot

content/en/docs/concepts/scheduling-eviction/dynamic-resource-allocation.md

@@ -5,6 +5,15 @@ reviewers:
 title: Dynamic Resource Allocation
 content_type: concept
 weight: 65
+api_metadata:
+- apiVersion: "resource.k8s.io/v1beta1"
+  kind: "ResourceClaim"
+- apiVersion: "resource.k8s.io/v1beta1"
+  kind: "ResourceClaimTemplate"
+- apiVersion: "resource.k8s.io/v1beta1"
+  kind: "DeviceClass"
+- apiVersion: "resource.k8s.io/v1beta1"
+  kind: "ResourceSlice"
 ---
 
 <!-- overview -->
@@ -39,7 +48,7 @@ v{{< skew currentVersion>}}, check the documentation for that version of Kuberne
 
 ## API
 
-The `resource.k8s.io/v1alpha3`
+The `resource.k8s.io/v1beta1`
 {{< glossary_tooltip text="API group" term_id="api-group" >}} provides these types:
 
 ResourceClaim
@@ -85,15 +94,15 @@ Here is an example for a fictional resource driver. Two ResourceClaim objects
 will get created for this Pod and each container gets access to one of them.
 
 ```yaml
-apiVersion: resource.k8s.io/v1alpha3
+apiVersion: resource.k8s.io/v1beta1
 kind: DeviceClass
 name: resource.example.com
 spec:
   selectors:
   - cel:
       expression: device.driver == "resource-driver.example.com"
 ---
-apiVersion: resource.k8s.io/v1alpha2
+apiVersion: resource.k8s.io/v1beta1
 kind: ResourceClaimTemplate
 metadata:
   name: large-black-cat-claim-template
@@ -200,6 +209,104 @@ spec:
 You may also be able to mutate the incoming Pod, at admission time, to unset
 the `.spec.nodeName` field and to use a node selector instead.
 
+## Admin access
+
+{{< feature-state feature_gate_name="DRAAdminAccess" >}}
+
+You can mark a request in a ResourceClaim or ResourceClaimTemplate as having privileged features.
+A request with admin access grants access to devices which are in use and
+may enable additional permissions when making the device available in a
+container:
+
+```yaml
+apiVersion: resource.k8s.io/v1beta1
+kind: ResourceClaimTemplate
+metadata:
+  name: large-black-cat-claim-template
+spec:
+  spec:
+    devices:
+      requests:
+      - name: req-0
+        deviceClassName: resource.example.com
+        adminAccess: true
+```
+
+If this feature is disabled, the `adminAccess` field will be removed
+automatically when creating such a ResourceClaim.
+
+Admin access is a privileged mode which should not be made available to normal
+users in a multi-tenant cluster. Cluster administrators can restrict usage of
+this feature by installing a validating admission policy similar to the following
+example. Cluster administrators need to adapt at least the names and replace
+"dra.example.com".
+
+```yaml
+# Permission to use admin access is granted only in namespaces which have the
+# "admin-access.dra.example.com" label. Other ways of making that decision are
+# also possible.
+
+apiVersion: admissionregistration.k8s.io/v1
+kind: ValidatingAdmissionPolicy
+metadata:
+  name: resourceclaim-policy.dra.example.com
+spec:
+  failurePolicy: Fail
+  matchConstraints:
+    resourceRules:
+    - apiGroups:   ["resource.k8s.io"]
+      apiVersions: ["v1alpha3", "v1beta1"]
+      operations:  ["CREATE", "UPDATE"]
+      resources:   ["resourceclaims"]
+  validations:
+    - expression: '! object.spec.devices.requests.exists(e, has(e.adminAccess) && e.adminAccess)'
+      reason: Forbidden
+      messageExpression: '"admin access to devices not enabled"'
+---
+apiVersion: admissionregistration.k8s.io/v1
+kind: ValidatingAdmissionPolicyBinding
+metadata:
+  name: resourceclaim-binding.dra.example.com
+spec:
+  policyName:  resourceclaim-policy.dra.example.com
+  validationActions: [Deny]
+  matchResources:
+    namespaceSelector:
+      matchExpressions:
+      - key: admin-access.dra.example.com
+        operator: DoesNotExist
+---
+apiVersion: admissionregistration.k8s.io/v1
+kind: ValidatingAdmissionPolicy
+metadata:
+  name: resourceclaimtemplate-policy.dra.example.com
+spec:
+  failurePolicy: Fail
+  matchConstraints:
+    resourceRules:
+    - apiGroups:   ["resource.k8s.io"]
+      apiVersions: ["v1alpha3", "v1beta1"]
+      operations:  ["CREATE", "UPDATE"]
+      resources:   ["resourceclaimtemplates"]
+  validations:
+    - expression: '! object.spec.spec.devices.requests.exists(e, has(e.adminAccess) && e.adminAccess)'
+      reason: Forbidden
+      messageExpression: '"admin access to devices not enabled"'
+---
+apiVersion: admissionregistration.k8s.io/v1
+kind: ValidatingAdmissionPolicyBinding
+metadata:
+  name: resourceclaimtemplate-binding.dra.example.com
+spec:
+  policyName:  resourceclaimtemplate-policy.dra.example.com
+  validationActions: [Deny]
+  matchResources:
+    namespaceSelector:
+      matchExpressions:
+      - key: admin-access.dra.example.com
+        operator: DoesNotExist
+```
+
 ## ResourceClaim Device Status
 
 {{< feature-state feature_gate_name="DRAResourceClaimDeviceStatus" >}}
@@ -219,9 +326,9 @@ existing ResourceClaim where the `status.devices` field is set.
 
 ## Enabling dynamic resource allocation
 
-Dynamic resource allocation is an *alpha feature* and only enabled when the
+Dynamic resource allocation is a *beta feature* which is off by default and only enabled when the
 `DynamicResourceAllocation` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
-and the `resource.k8s.io/v1alpha3` {{< glossary_tooltip text="API group" term_id="api-group" >}}
+and the `resource.k8s.io/v1beta1` {{< glossary_tooltip text="API group" term_id="api-group" >}}
 are enabled. For details on that, see the `--feature-gates` and `--runtime-config`
 [kube-apiserver parameters](/docs/reference/command-line-tools-reference/kube-apiserver/).
 kube-scheduler, kube-controller-manager and kubelet also need the feature gate.
@@ -258,6 +365,12 @@ include it.
 In addition to enabling the feature in the cluster, a resource driver also has to
 be installed. Please refer to the driver's documentation for details.
 
+### Enabling admin access
+
+[Admin access](#admin-access) is an *alpha feature* and only enabled when the
+`DRAAdminAccess` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+is enabled in the kube-apiserver and kube-scheduler.
+
 ### Enabling Device Status
 
 [ResourceClaim Device Status](#resourceclaim-device-status) is an *alpha feature* 

content/en/docs/reference/command-line-tools-reference/feature-gates/dra-admin-access.md

@@ -0,0 +1,18 @@
+---
+title: DRAAdminAccess
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.32"
+---
+Enables support for requesting [admin access](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/#admin-access)
+in a ResourceClaim. A ResourceClaim
+with admin access grants access to devices which are in use and may enable
+additional access permissions when making the device available in a container.
+
+This feature gate has no effect unless you also enable the `DynamicResourceAllocation` feature gate.

content/en/docs/reference/command-line-tools-reference/feature-gates/dynamic-resource-allocation.md

@@ -9,6 +9,15 @@ stages:
   - stage: alpha
     defaultValue: false
     fromVersion: "1.30"
+    toVersion: "1.31"
+  - stage: beta
+    defaultValue: false
+    fromVersion: "1.32"
+
+# TODO: as soon as this is locked to "true" (= GA), comments about other DRA
+# feature gate(s) like "unless you also enable the `DynamicResourceAllocation` feature gate"
+# can be removed (for example, in dra-admin-access.md).
+
 ---
 Enables support for resources with custom parameters and a lifecycle
 that is independent of a Pod. Allocation of resources is handled

content/en/docs/reference/kubernetes-api/extend-resources/device-class-v1alpha3.md

@@ -19,6 +19,8 @@ To update the reference content, please follow the
 [Contributing upstream](/docs/contribute/generate-ref-docs/contribute-upstream/)
 guide. You can file document formatting bugs against the
 [reference-docs](https://github.com/kubernetes-sigs/reference-docs/) project.
+
+TODO: this file should be under "workload-resources".
 -->
 
 `apiVersion: resource.k8s.io/v1alpha3`