Populate NodeResourceTopology API

.gitignore

@@ -0,0 +1 @@
+vendor/

API.md

@@ -0,0 +1,128 @@
+# Introduction
+This document provides API specification of NodeResourceTopology API (aka NRT API)
+which is a CRD based API that describes the structure of topology on a node. One of
+the goals when designing this API was to ensure hardware independent data structure,
+which allows us to have a future-proof API that represents hardware of varying internal
+topology.
+
+CRD instances must be created external to kubelet and independently. Each instance
+will be bound to one working node.
+
+It is worth noting that there are multiple legitimate ways of representing topology of
+the same hardware.
+
+As an example, the list of zones of the harware below can be represented in the following ways via the API:
+
+![Hardware Topology](./NRTAPI-example.png)
+
+```
+{
+	{Name=NUMANode-gpu-0,Type=NUMA, cost={{NUMANode-cpu-0:10},{NUMANode-gpu-1:20}},
+	{Name=PCIE-0-gpu1, type=gpu, parent=NUMANode-gpu-0},
+	{Name=PCIE-0-gpu2, type=gpu, parent=NUMANode-gpu-0},
+	{Name=NUMANode-cpu-0,Type=NUMA, cost={{NUMANode-gpu-0:10},{NUMANode-gpu-1:30}},
+	{Name=PCIE-0-cpu1, type=cpu, parent=NUMANode-cpu-0},
+	{Name=PCIE-0-cpu2, type=cpu, parent=NUMANode-cpu-0},
+	{Name=NUMANode-gpu-1,Type=NUMA, cost={{NUMANode-cpu-0:30},{NUMANode-gpu-0:20}},
+	{Name=PCIE-1-gpu1, type=gpu, parent=NUMANode-gpu-1},
+	{Name=PCIE-1-gpu2, type=gpu, parent=NUMANode-gpu-1},
+}
+```
+
+```
+{
+	{Name=NUMANode-gpu,Type=Resource, cost=({NUMANode-cpu:20}}},
+	{Name=PCIE-0-gpu1, type=gpu, parent=NUMANode-gpu},
+	{Name=PCIE-0-gpu2, type=gpu, parent=NUMANode-gpu},
+	{Name=PCIE-1-gpu1, type=gpu, parent=NUMANode-gpu},
+	{Name=PCIE-1-gpu2, type=gpu, parent=NUMANode-gpu},
+	{Name=NUMANode-cpu,Type=Resource, cost=({NUMANode-gpu:20}},
+	{Name=PCIE-0-cpu1, type=cpu, parent=NUMANode-cpu},
+	{Name=PCIE-0-cpu2, type=cpu, parent=NUMANode-cpu},
+}
+```
+
+# NodeTopology Object Definition
+
+```
+// NodeResourceTopology describes node resources and their topology.
+type NodeResourceTopology struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Zones      ZoneList      `json:"zones"`
+	Attributes AttributeList `json:"attributes,omitempty"`
+}
+
+// Zone represents a resource topology zone, e.g. socket, node, die or core.
+type Zone struct {
+	Name       string           `json:"name" protobuf:"bytes,1,opt,name=name"`
+	Type       string           `json:"type" protobuf:"bytes,2,opt,name=type"`
+	Parent     string           `json:"parent,omitempty" protobuf:"bytes,3,opt,name=parent"`
+	Costs      CostList         `json:"costs,omitempty" protobuf:"bytes,4,rep,name=costs"`
+	Attributes AttributeList    `json:"attributes,omitempty" protobuf:"bytes,5,rep,name=attributes"`
+	Resources  ResourceInfoList `json:"resources,omitempty" protobuf:"bytes,6,rep,name=resources"`
+}
+
+// ZoneList contains an array of Zone objects.
+type ZoneList []Zone
+
+// ResourceInfo contains information about one resource type.
+type ResourceInfo struct {
+	// Name of the resource.
+	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
+	// Capacity of the resource, corresponding to capacity in node status, i.e.
+	// total amount of this resource that the node has.
+	Capacity resource.Quantity `json:"capacity" protobuf:"bytes,2,opt,name=capacity"`
+	// Allocatable quantity of the resource, corresponding to allocatable in
+	// node status, i.e. total amount of this resource available to be used by
+	// pods.
+	Allocatable resource.Quantity `json:"allocatable" protobuf:"bytes,3,opt,name=allocatable"`
+	// Available is the amount of this resource currently available for new (to
+	// be scheduled) pods, i.e. Allocatable minus the resources reserved by
+	// currently running pods.
+	Available resource.Quantity `json:"available" protobuf:"bytes,4,opt,name=available"`
+}
+
+// ResourceInfoList contains an array of ResourceInfo objects.
+type ResourceInfoList []ResourceInfo
+
+// CostInfo describes the cost (or distance) between two Zones.
+type CostInfo struct {
+	Name  string `json:"name" protobuf:"bytes,1,opt,name=name"`
+	Value int64  `json:"value" protobuf:"varint,2,opt,name=value"`
+}
+
+// CostList contains an array of CostInfo objects.
+type CostList []CostInfo
+
+// AttributeInfo contains one attribute of a Zone.
+type AttributeInfo struct {
+	Name  string `json:"name" protobuf:"bytes,1,opt,name=name"`
+	Value string `json:"value" protobuf:"bytes,2,opt,name=value"`
+}
+
+// AttributeList contains an array of AttributeInfo objects.
+type AttributeList []AttributeInfo
+
+// NodeResourceTopologyList is a list of NodeResourceTopology resources
+type NodeResourceTopologyList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata"`
+
+	Items []NodeResourceTopology `json:"items"`
+}
+```
+
+# Definitions of Keys
+
+1. NodeResourceTopology.Zones - List of Zones. A zone can represent NUMA nodes, packages, dies, cores etc.
+    1. Name - Name of a zone e.g numa-node-0, package-0
+	1. Type - Type of a zone e.g. NUMANode, Package
+    1. Parent - Parent of a zone. This is used to cross-reference a defined zone to establish a hierarchial structure between various zones. e.g. we can indicate that package-0 is parent of numa-node-0.
+	1. Costs -  reports the distance in the machine topology between two zones. e.g. NUMA distances between various NUMA nodes. 
+	1. Attributes - List of attributes corresponding to the zone
+	1. Resources - Resource information is a measure of resources within that zone e.g. cpu, memory etc.
+    This field also allows us to capture capacity, allocatable and available resources on a per-zone basis.
+
+1. NodeResourceTopology.Attributes - can be used to indicate top level attributes of the NodeResourceTopology CR e.g. list of the policy name. The policy name could be one of the Node TopologyManager policy or other resource management component like CRI Resource Manager. These policies represent the behaviour of the scheduler plugin, this behaviour reflects the node based component for resource management.

OWNERS

@@ -1,6 +1,6 @@
 # See the OWNERS docs at https://go.k8s.io/owners
 
 approvers:
-- ffromani
-- marquiz
-- swatisehgal
+  - nrt-approvers
+reviewers:
+  - nrt-reviewers

OWNERS_ALIASES

@@ -0,0 +1,15 @@
+aliases:
+  k8s-api-reviewers:
+  - thockin
+  - liggitt 
+  k8s-api-approvers:
+  - thockin
+  - liggitt
+  nrt-reviewers:
+  - ffromani
+  - marquiz
+  - swatisehgal
+  nrt-approvers:
+  - ffromani
+  - marquiz
+  - swatisehgal

README.md

@@ -1,25 +1,16 @@
-# Kubernetes Template Project
+# NodeResourceTopology API
 
-The Kubernetes Template Project is a template for starting new projects in the GitHub organizations owned by Kubernetes. All Kubernetes projects, at minimum, must have the following files:
-
-- a `README.md` outlining the project goals, sponsoring sig, and community contact information
-- an `OWNERS` with the project leads listed as approvers ([docs on `OWNERS` files][owners])
-- a `CONTRIBUTING.md` outlining how to contribute to the project
-- an unmodified copy of `code-of-conduct.md` from this repo, which outlines community behavior and the consequences of breaking the code
-- a `LICENSE` which must be Apache 2.0 for code projects, or [Creative Commons 4.0] for documentation repositories, without any custom content
-- a `SECURITY_CONTACTS` with the contact points for the Product Security Team 
-  to reach out to for triaging and handling of incoming issues. They must agree to abide by the
-  [Embargo Policy](https://git.k8s.io/security/private-distributors-list.md#embargo-policy)
-  and will be removed and replaced if they violate that agreement.
+## Purpose
+This repository contains the CRD based API definition used for enabling Topology aware Scheduling in Kubernetes.
+Please refer to [API.md](./API.md) document for more details.
 
 ## Community, discussion, contribution, and support
 
 Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
 
 You can reach the maintainers of this project at:
 
-- [Slack](https://slack.k8s.io/)
-- [Mailing List](https://groups.google.com/a/kubernetes.io/g/dev)
+- Slack: [#topology-aware-scheduling](https://kubernetes.slack.com/archives/C012XSGFZQE)
 
 ### Code of conduct
 

go.mod

@@ -0,0 +1,54 @@
+module sigs.k8s.io/noderesourcetopology-api
+
+go 1.20
+
+require (
+	github.com/gogo/protobuf v1.3.2
+	k8s.io/apimachinery v0.28.4
+	k8s.io/client-go v0.28.4
+	k8s.io/code-generator v0.28.4
+	sigs.k8s.io/structured-merge-diff/v4 v4.2.3
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/emicklei/go-restful/v3 v3.9.0 // indirect
+	github.com/evanphx/json-patch v4.12.0+incompatible // indirect
+	github.com/go-logr/logr v1.2.4 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.22.3 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/google/gnostic-models v0.6.8 // indirect
+	github.com/google/go-cmp v0.5.9 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/uuid v1.3.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+	golang.org/x/mod v0.10.0 // indirect
+	golang.org/x/net v0.17.0 // indirect
+	golang.org/x/oauth2 v0.8.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	golang.org/x/term v0.13.0 // indirect
+	golang.org/x/text v0.13.0 // indirect
+	golang.org/x/time v0.3.0 // indirect
+	golang.org/x/tools v0.8.0 // indirect
+	google.golang.org/appengine v1.6.7 // indirect
+	google.golang.org/protobuf v1.31.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/api v0.28.4 // indirect
+	k8s.io/gengo v0.0.0-20220902162205-c0856e24416d // indirect
+	k8s.io/klog/v2 v2.100.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20230717233707-2695361300d9 // indirect
+	k8s.io/utils v0.0.0-20230406110748-d93618cff8a2 // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/yaml v1.3.0 // indirect
+)