(pending https://github.com/rancher/rancher/pull/40155)

All Rancher functionality is based on the Kubernetes API, which includes built-in APIs and extensions.

The vast majority of Rancher objects are implemented as Kubernetes Custom Resource Definitions (CRDs). These are the most common mechanism for extending the Kubernetes API. These are stateful objects with schemas defined in Kubernetes that have CRUD functionality. Custom Resources (CRs) act the same as the rest of the Kubernetes API and can be interacted with using kubectl or directly through the Kubernetes REST API.

Another, less common way of extending the Kubernetes API is API extension servers or aggregation layers. These APIs are more customizable and aren't necessarily stateful.

The steve (or /v1) API is a thin API proxy aimed at presenting data from the Kubernetes API in a dashboard-friendly way. Steve registered all Kubernetes APIs it can find in the catalog (built-in APIs, CRDs, and API extensions) and registers them as schemas in its own API, making them available to the client. Steve is mainly used by Rancher, but could be used by any service that wants to forward data between Kubernetes and a dashboard.

The norman (or /v3) API (deprecated) is a workhorse API that uses the Kubernetes API as its backend but implements significant functionality in addition.

Projects are Rancher's implementation of soft multi-tenancy. Projects are a concept central to Rancher and do not have relevance to other Kubernetes-backed projects. Steve does not have any special handling for Projects, because steve only knows about what's in the Kubernetes API.

Projects are a grouping of namespaces. If a user has access to a Project, that permission is replicated to all member namespaces. The Project resource only exists in the local Rancher cluster, and membership in a project is inferred by labels and annotations on namespaces.

While Projects have primarily been a way to sync role assignments to a set of namespaces, until now they have not been useful for presenting the resources belonging to namespaces belonging to Projects. Before this API extension, finding all resources (pods, configmaps, rolebindings, etc) in all the namespaces belonging to a Project could only be done by individually querying each member namespace, which would mean multiple requests. The new API extension creates a new Project scope which allows for querying a single endpoint and having the full list returned in one response.

The project resources API endpoint supports both cluster-scoped and namespace-scoped URI formats. To list resources by a single project, you can use the namespace-scoped format, where the Project ID is treated as a kind of parent namespace:

GET /apis/resources.project.cattle.io/namespaces/<project ID>/<resource group and name>

In the steve API, this translates to

GET /v1/resources.project.cattle.io.<resource group and name>/<project ID>

Or to list resources filtered by one or more projects or namespaces, use the cluster-scoped format with a fieldSelector query using the projectsornamespaces key. In k8s:

GET /apis/resources.project.cattle.io/<resource group and name>?fieldSelector=projectsornamespaces=p-abcde,ns1,ns2

In steve:

GET /v1/resources.project.cattle.io.<resource group and name>?fieldSelector=projectsornamespaces=p-abcde,ns1,ns2

The selector supports negation:

GET /apis/resources.project.cattle.io/<resource group and name>?fieldSelector=projectsornamespaces!=p-vwxyz

GET /v1/resources.project.cattle.io.<resource group and name>?fieldSelector=projectsornamespaces!=p-vwxyz

The API can be interacted with through kubectl:

kubectl get --raw /apis/resources.project.cattle.io/namespaces/p-abcde/pods # if you only have access to project p-abcde, use that namespaced endpoint
kubectl get --raw /apis/resources.project.cattle.io/pods?fieldSelector=projectsornamespaces=p-abcde # if you are an admin, filter by a single project

or through steve:

curl -u $TOKEN https://rancher/v1/resources.project.cattle.io.pods/p-abcde # local
curl -u $TOKEN https://rancher/k8s/clusters/c-abcde/v1/resources.project.cattle.io.pods/p-abcde # downstream named c-abcde
curl -u $TOKEN https://rancher/v1/resources.project.cattle.io.pods?fieldSelector=projectsornamespaces=p-abcde # any user can use this format in steve. If the user does not have access to project p-abcde the response will be empty.
curl -u $TOKEN https://rancher/v1/resources.project.cattle.io.pods?fieldSelector=projectsornamespaces!=p-vwxyz # exclude resources in one project, for example the system project

Resources that aren't core resources are concatenated with their APIGroup:

kubectl get --raw /apis/resources.project.cattle.io/namespaces/p-abcde/apps.deployments
kubectl get --raw /apis/resources.project.cattle.io/namespaces/p-abcde/rbac.authorization.k8s.io.roles
curl -u $TOKEN https://rancher/v1/resources.project.cattle.io.rbac.authorization.k8s.io.roles/p-abcde
curl -u $TOKEN https://rancher/k8s/clusters/c-abcde/v1/resources.project.cattle.io.rbac.authorization.k8s.io.roles/p-abcde

Only list operations are currently supported through this API. To get an individual resource, make the usual GET request on the resource's standard API using the resource's ID. To start a watch, make the usual websocket request on the resource's standard API using the list's resource version.