steve

Steve is a lightweight API proxy for Kubernetes whose aim is to create an interface layer suitable for dashboards to efficiently interact with Kubernetes.

API Usage

Kubernetes proxy

Requests made to /api, /api/*, /apis/*, /openapi/* and /version will be proxied directly to Kubernetes.

/v1 API

Steve registers all Kubernetes resources as schemas in the /v1 API. Any endpoint can support methods GET, POST, PATCH, PUT, or DELETE, depending on what the underlying Kubernetes endpoint supports and the user's permissions.

• /v1/{type} - all cluster-scoped resources OR all resources in all namespaces of type {type} that the user has access to
• /v1/{type}/{name} - cluster-scoped resource of type {type} and unique name {name}
• /v1/{type}/{namespace} - all resources of type {type} under namespace {namespace}
• /v1/{type}/{namespace}/{name} - resource of type {type} under namespace {namespace} with name {name} unique within the namespace

Query parameters

Steve supports query parameters to perform actions or process data on top of what Kubernetes supports. In-depth, auto-generated API examples can be found in rancher.

link

Trigger a link handler, which is registered with the schema. Examples are calling the shell for a cluster, or following logs during cluster or catalog operations:

GET /v1/management.cattle.io.clusters/local?link=log

action

Trigger an action handler, which is registered with the schema. Examples are generating a kubeconfig for a cluster, or installing an app from a catalog:

POST /v1/catalog.cattle.io.clusterrepos/rancher-partner-charts?action=install

List-specific query parameters

List requests (/v1/{type} and /v1/{type}/{namespace}) have additional parameters for filtering, sorting and pagination.

Note that the exact meaning and behavior of those parameters may vary if Steve is used with SQLite caching of resources, which is configured when calling server.New via the server.Options.SQLCache boolean option. Meaning and behavior are the same unless otherwise specified.

Note that, if SQLite caching of resources is enabled, some of the data can be stored in disk, in either encrypted or plain text forms based on:

• by default, Secrets and Rancher Tokens (management.cattle.io/v3, Kind=Token) are always encrypted
• if the environment variable CATTLE_ENCRYPT_CACHE_ALL is set to "true", all resources are encrypted
• regardless of the setting's value, any filterable/sortable columns are stored in plain text (see filter below for the exact list)

limit

If SQLite caching is disabled (server.Options.SQLCache=false), set the maximum number of results to retrieve from Kubernetes. The limit is passed on as a parameter to the Kubernetes request. The purpose of setting this limit is to prevent a huge response from overwhelming Steve and Rancher. For more information about setting limits, review the Kubernetes documentation on retrieving results in chunks.

The limit controls the size of the set coming from Kubernetes, and then filtering, sorting, and pagination are applied on that set. Because of this, if the result set is partial, there is no guarantee that the result returned to the client is fully sorted across the entire list, only across the returned chunk.

If SQLite caching is enabled (server.Options.SQLCache=true), set the maximum number of results to return from the SQLite cache.

If both this parameter and pagesize are set, the smallest is taken.

In both cases, the returned response will include a continue token, which indicates that the result is partial and must be used in the subsequent request to retrieve the next chunk.

The default limit is 100000. To override the default, set limit=-1.

continue

Continue retrieving the next chunk of a partial list. The continue token is included in the response of a limited list and indicates that the result is partial. This token can then be used as a query parameter to retrieve the next chunk. All chunks have been retrieved when the continue field in the response is empty.

filter

Filter results by a designated field. Filter keys use dot notation to denote the subfield of an object to filter on. The filter value is normally matched as a substring.

Example, filtering by object name:

/v1/{type}?filter=metadata.name=foo

When SQLite caching is not enabled, matching works this way:

If a target value is surrounded by single-quotes, it succeeds only on an exact match:

Example, filtering by object name:

/v1/{type}?filter=metadata.name='match-this-exactly'

A target value can be delimited by double-quotes, but this will succeed on a partial match:

Example, filtering by object name:

/v1/{type}?filter=metadata.name="can-be-a-substri"

When SQLite caching is enabled, equality is slightly different from non-sql-supported matching. Equality can be specified with either one or two '=' signs.

The following matches objects called either 'cat' or 'cows':

filter=metadata.name=cat,metadata.name=cows

The following matches objects whose names contain either the substring 'cat' or 'cows':

filter=metadata.name~cat,metadata.name~cows

For example, this will match an object with metadata.name=cowcatcher

Set membership is done with the in operator:

filter=metadata.name in (cat, cows)

When called via http the spaces will need to be encoded either as + or %20.

There are negative forms of the above operators:

filter=metadata.name!=dog  # no dogs allowed
filter=metadata.name!~x    # skip any names containing an 'x'
filter=metadata.name notin (goldfish, silverfish) # ignore these

Labels can be tested with the implicit "EXISTS" operator:

filter=metadata.labels[cattle.io.fences/wooden]

This will select any objects that have the specified label. Negate this test by preceding it with a !:

filter=!metadata.labels[cattle.io.fences/bamboo]

Existence tests only work for metadata.labels.

If you need to do a numeric computation, you can use the < and > operators.

filter=metadata.fields[3]>10&metadata.fields[3]<20

This is specific to a particular kind of Kubernetes object.

Finally, most values need to conform to specific syntaxes. But if the VALUE in an expression contains unusual characters, you can quote the value with either single or double quotes:

filter=metadata.name="oxford,metadata.labels.comma"

Without the quotes, the expression would be finding either objects called oxford, or that have the label "comma", which is very different from objects called oxford,metadata.labels.comma.

One filter can list multiple possible fields to match, these are ORed together:

/v1/{type}?filter=metadata.name=foo,metadata.namespace=foo

Stacked filters are ANDed together, so an object must match all filters to be included in the list.

/v1/{type}?filter=metadata.name=foo&filter=metadata.namespace=bar

Filters can be negated to exclude results:

/v1/{type}?filter=metadata.name!=foo

If SQLite caching is disabled (server.Options.SQLCache=false), arrays are searched for matching items. If any item in the array matches, the item is included in the list.

/v1/{type}?filter=spec.containers.image=alpine

When SQLite caching is enabled, multiple values are stored separated by "or-bars" (|), like abc|def|ghi. You'll need to use the partial-match operator ~ to match one member, like /v1/{type}?filter=spec.containers.image ~ ghi.

If SQLite caching is enabled (server.Options.SQLCache=true), filtering is only supported for a subset of attributes:

• id, metadata.name, metadata.namespace, metadata.state.name, and metadata.timestamp for any resource kind
• a short list of hardcoded attributes for a selection of specific types listed in typeSpecificIndexFields
• the special string metadata.fields[N], with N starting at 0, for all columns displayed by kubectl get $TYPE. For example secrets have "metadata.fields[0]", "metadata.fields[1]" , "metadata.fields[2]", and "metadata.fields[3]" respectively corresponding to "name", "type", "data", and "age". For CRDs, these come from Additional printer columns

When matching on array-type fields, the array's values are stored in the database as a single field separated by or-bars (|s).= So searching for those fields needs to do a partial match when a field contains more than one value.

projectsornamespaces

Resources can also be filtered by the Rancher projects their namespaces belong to. Since a project isn't an intrinsic part of the resource itself, the filter parameter for filtering by projects is separate from the main filter parameter. This query parameter is only applicable when steve is running in concert with Rancher.

The list can be filtered by either projects or namespaces or both.

Filtering by a single project or a single namespace:

/v1/{type}?projectsornamespaces=p1

Filtering by multiple projects or namespaces is done with a comma separated list. A resource matching any project or namespace in the list is included in the result:

/v1/{type}?projectsornamespaces=p1,n1,n2

The list can be negated to exclude results:

/v1/{type}?projectsornamespaces!=p1,n1,n2

sort

Results can be sorted lexicographically by any number of columns given in descending order of importance.

Sorting by only a single column, for example name:

/