Skip to content

enhancements: Downward API #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oshoval wants to merge 1 commit into
base: main
Choose a base branch
from
Open

enhancements: Downward API #62

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions enhancements/DownwardAPI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# DRA Attributes Downward API

## Overview

This enhancement provides containers with access to Dynamic Resource Allocation (DRA) device attributes and networking information through files mounted into the container filesystem. This allows applications to discover allocated SR-IOV VF attributes, networking configuration, and CNI results without querying the Kubernetes API.

Based on upstream KEP: [KEP-5304: DRA Attributes Downward API](https://github.com/kubernetes/enhancements/blob/97e2ebed48363deeec45be11d59efe072d9570d5/keps/sig-node/5304-dra-attributes-downward-api/README.md)

## File Structure

### Node-Level Storage
Files are stored on the node at:
```
/etc/dra/<pod_uid>/<claimName>.<requestName>.json
```
Comment on lines +13 to +15
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specification to fenced code block.

The first code block lacks a language specifier, which is flagged by markdown linting rules.

🔎 Proposed fix 
-```
+```text
 /etc/dra/<pod_uid>/<claimName>.<requestName>.json
-```
+```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

13-13: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In @enhancements/DownwardAPI.md around lines 13-15, Update the fenced code block
that contains the path "/etc/dra/<pod_uid>/<claimName>.<requestName>.json" to
include a language specifier (e.g., add "text" after the opening backticks) so
the block becomes a proper markdown code fence with language declared.


### Container-Level Access
Within containers, files are mounted to:
```
/etc/dra/<claimName>.<requestName>.json
Comment on lines +19 to +20
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specification to fenced code block.

The second code block lacks a language specifier, which is flagged by markdown linting rules.

🔎 Proposed fix 
-```
+```text
 /etc/dra/<claimName>.<requestName>.json
-```
+```
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```
/etc/dra/<claimName>.<requestName>.json
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

19-19: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In @enhancements/DownwardAPI.md around lines 19-20, The second fenced code block
containing the line "/etc/dra/<claimName>.<requestName>.json" is missing a
language specifier; update that fence to include a language (e.g., replace the
opening ``` with ```text) so the block becomes a ```text fenced block to satisfy
markdown linting.

```

Each file corresponds to a unique `(claimName, requestName)` tuple, supporting scenarios with multiple resource claims per pod.
Copy link
Copy Markdown
Member Author

@oshoval oshoval Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note that the example below doesn't adhere to it, so we need to raise it on the KEP or align here,
since as we spoke each clainName, requestName tuple can belong to a different driver, so we need a separate file per tuple or at least per driver ?
(while the example belows shows one file for all the requests)


## File Format

Each JSON file is a Kubernetes-style API object containing claim metadata and per-device information:

```json
{
"apiVersion": "dra.k8s.io/v1alpha1",
"kind": "DeviceMetadata",
"metadata": {
"name": "my-claim",
"namespace": "default",
"uid": "abc-123-def-456"
},
"requests": [
{
"name": "gpu-request",
"devices": [
{
"name": "gpu-0",
"driver": "nvidia.com",
"pool": "node-1-gpus",
"bestEffortData": {
"attributes": {
"model": "A100",
"memory": "80Gi",
"vendor": "nvidia"
}
},
"driverProvidedData": {
"conditions": [
{
"type": "Ready",
"status": "True",
"lastTransitionTime": "2024-01-15T10:00:00Z"
}
],
"data": {
"pciBusID": "0000:00:1e.0"
}
}
}
]
},
{
"name": "network-request",
"devices": [
{
"name": "vf-3",
"driver": "cni.dra.networking.x-k8s.io",
"pool": "node-1-sriov",
"bestEffortData": {
"attributes": {
"vendor": "mellanox",
"model": "ConnectX-6"
}
},
"driverProvidedData": {
"conditions": [
{
"type": "Ready",
"status": "True",
"lastTransitionTime": "2024-01-15T10:00:00Z"
}
],
"data": {
Copy link
Copy Markdown
Member Author

@oshoval oshoval Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we need to add here type ? for example network 0x as we discussed for SR-IOV ?
(btw not sure today Kubevirt is protected in this aspect of device mixing)

"pciAddress": "0000:00:01.3",
"vfIndex": 3,
"mtu": 9000
},
"networkData": {
"interfaceName": "net1",
"addresses": ["10.10.1.2/24", "fd00::2/64"],
"hwAddress": "5a:9f:d8:84:fb:51"
}
}
}
]
}
]
}
```
## Implementation

### High-Level Workflow

1. **CDI (Container Device Interface)**: Prepares the pod manifest with volume mounts, specifying that the DRA attribute files should be mounted into the container at `/etc/dra/`

2. **NRI (Node Resource Interface)**: Writes the JSON files to the node filesystem at `/etc/dra/<pod_uid>/` after CNI network attachment completes and networking information is available

3. **Container Runtime**: Mounts the files into the container at startup, ensuring the container has access to device attributes throughout its lifetime

### Lifecycle

- Files are created during pod sandbox creation after network attachment succeeds
- Files persist on the node for the pod's lifetime
- The container receives a consistent view of the allocated devices from initialization

## Future Considerations

When Kubernetes adds native support for DRA attributes in the Downward API, the base directory path may change while maintaining the same file structure and naming convention.
Loading