Documentation
¶
Overview ¶
Package devicemetadata provides consumer-side utilities for reading and decoding DRA device metadata files. It is intended for any Go program that needs to consume metadata written by a DRA kubelet plugin, including sidecars, monitoring tools, and in-container agents.
Index ¶
- func DecodeMetadataFromStream(decoder *json.Decoder, dest runtime.Object) error
- func ReadResourceClaimMetadata(claimName, requestName string) (*metadata.DeviceMetadata, error)
- func ReadResourceClaimMetadataWithDriverName(driverName, claimName, requestName string) (*metadata.DeviceMetadata, error)
- func ReadResourceClaimTemplateMetadata(podClaimName, requestName string) (*metadata.DeviceMetadata, error)
- func ReadResourceClaimTemplateMetadataWithDriverName(driverName, podClaimName, requestName string) (*metadata.DeviceMetadata, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeMetadataFromStream ¶
DecodeMetadataFromStream reads the first compatible object from a DRA device metadata stream. A metadata file may contain the same data encoded in multiple API versions (see k8s.io/dynamic-resource-allocation/api/metadata for the file format); this function tries each in order and populates dest with the first one it can successfully decode and convert.
Entries whose apiVersion is not registered in the scheme (e.g. a newer version written by an upgraded driver) are skipped silently so that a driver upgrade does not break older consumers. Any other failure is fatal. dest is only populated on a nil return.
dest must be a pointer to a type registered in the metadata scheme (e.g., *v1alpha1.DeviceMetadata or *metadata.DeviceMetadata). The internal type is recommended because it can be decoded with less conversions and source code does not need to be updated when new API versions get added or (at some point) removed.
Example ¶
ExampleDecodeMetadataFromStream demonstrates reading a metadata file that may contain multiple API versions as a JSON stream. Decoding into the internal type (metadata.DeviceMetadata) is recommended because it can be decoded with less conversions and source code does not need to be updated when new API versions get added or (at some point) removed.
package main
import (
"bytes"
"encoding/json"
"fmt"
"k8s.io/dynamic-resource-allocation/api/metadata"
"k8s.io/dynamic-resource-allocation/devicemetadata"
)
func main() {
fileData := []byte(`{"apiVersion":"metadata.resource.k8s.io/v1alpha1","kind":"DeviceMetadata","metadata":{"name":"my-claim","namespace":"default","uid":"uid-1234","generation":1},"requests":[{"name":"gpu","devices":[{"driver":"gpu.example.com","pool":"worker-0","name":"gpu-0","attributes":{"model":{"string":"LATEST-GPU-MODEL"},"driverVersion":{"version":"1.0.0"},"type":{"string":"gpu"}}}]}]}`)
var md metadata.DeviceMetadata
if err := devicemetadata.DecodeMetadataFromStream(json.NewDecoder(bytes.NewReader(fileData)), &md); err != nil {
fmt.Printf("error: %v\n", err)
return
}
fmt.Printf("claim: %s/%s\n", md.Namespace, md.Name)
fmt.Printf("request: %s, devices: %d\n", md.Requests[0].Name, len(md.Requests[0].Devices))
fmt.Printf("device: %s (driver: %s, pool: %s)\n", md.Requests[0].Devices[0].Name, md.Requests[0].Devices[0].Driver, md.Requests[0].Devices[0].Pool)
}
Output: claim: default/my-claim request: gpu, devices: 1 device: gpu-0 (driver: gpu.example.com, pool: worker-0)
Example (MultiVersion) ¶
ExampleDecodeMetadataFromStream_multiVersion demonstrates reading a metadata file that contains the same data encoded in multiple API versions (newest first). The function skips versions it cannot decode and resolves the first compatible one into the internal type.
package main
import (
"encoding/json"
"fmt"
"strings"
"k8s.io/dynamic-resource-allocation/api/metadata"
"k8s.io/dynamic-resource-allocation/devicemetadata"
)
func main() {
// This fictional v1000 uses slightly different field names.
stream := `
{"apiVersion":"metadata.resource.k8s.io/v1000","kind":"DeviceMetadata","metadata":{"claimName":"my-claim","claimNamespace":"default","uid":"uid-1234","generation":1},"requests":[{"name":"gpu","devices":[{"driver":"gpu.example.com","pool":"worker-0","name":"gpu-0"}]}]}
{"apiVersion":"metadata.resource.k8s.io/v1alpha1","kind":"DeviceMetadata","metadata":{"name":"my-claim","namespace":"default","uid":"uid-1234","generation":1},"requests":[{"name":"gpu","devices":[{"driver":"gpu.example.com","pool":"worker-0","name":"gpu-0","attributes":{"model":{"string":"LATEST-GPU-MODEL"},"type":{"string":"gpu"}}}]}]}
`
var md metadata.DeviceMetadata
if err := devicemetadata.DecodeMetadataFromStream(json.NewDecoder(strings.NewReader(stream)), &md); err != nil {
fmt.Printf("error: %v\n", err)
return
}
fmt.Printf("claim: %s/%s\n", md.Namespace, md.Name)
fmt.Printf("request: %s, devices: %d\n", md.Requests[0].Name, len(md.Requests[0].Devices))
fmt.Printf("device: %s (driver: %s, pool: %s)\n", md.Requests[0].Devices[0].Name, md.Requests[0].Devices[0].Driver, md.Requests[0].Devices[0].Pool)
}
Output: claim: default/my-claim request: gpu, devices: 1 device: gpu-0 (driver: gpu.example.com, pool: worker-0)
func ReadResourceClaimMetadata ¶
func ReadResourceClaimMetadata(claimName, requestName string) (*metadata.DeviceMetadata, error)
ReadResourceClaimMetadata reads and decodes all metadata files for a directly referenced ResourceClaim request, regardless of which driver(s) wrote them. It globs the request directory for all *-metadata.json files and merges the results into a single metadata.DeviceMetadata.
func ReadResourceClaimMetadataWithDriverName ¶
func ReadResourceClaimMetadataWithDriverName(driverName, claimName, requestName string) (*metadata.DeviceMetadata, error)
ReadResourceClaimMetadataWithDriverName reads and decodes the metadata file for a directly referenced ResourceClaim from a specific driver. driverName identifies which driver's metadata to read, since each driver writes a separate file per request.
func ReadResourceClaimTemplateMetadata ¶
func ReadResourceClaimTemplateMetadata(podClaimName, requestName string) (*metadata.DeviceMetadata, error)
ReadResourceClaimTemplateMetadata reads and decodes all metadata files for a template-generated claim request, regardless of which driver(s) wrote them. It globs the request directory for all *-metadata.json files and merges the results into a single metadata.DeviceMetadata.
func ReadResourceClaimTemplateMetadataWithDriverName ¶
func ReadResourceClaimTemplateMetadataWithDriverName(driverName, podClaimName, requestName string) (*metadata.DeviceMetadata, error)
ReadResourceClaimTemplateMetadataWithDriverName reads and decodes the metadata file for a template-generated claim from a specific driver. podClaimName is the pod-local name (pod.spec.resourceClaims[].name). driverName identifies which driver's metadata to read, since each driver writes a separate file per request.
Types ¶
This section is empty.
Source Files