API reference

This document contains the endpoints of the KubeArchive API and the query parameters they support.

Related to Kubernetes

/livez
/readyz

Collection of Resources

/apis/:group/:version/:resourceType
/apis/:group/:version/namespaces/:namespace/:resourceType
/api/:version/:resourceType
/api/:version/namespaces/:namespace/:resourceType

Examples:

/apis/apps/v1/deployments
/apis/batch/v1/namespaces/default/jobs
/api/v1/services
/api/v1/namespaces/default/pods

Parameters allowed:

  • limit: defaults to 100. Not higher than 1000. Limits the number of entries returned.

  • continue: token to access the next page of the pagination. Retrieve it at .metadata.continue of the returned List resource. An empty string if there are no more pages remaining.

  • labelSelector: allows filtering resources based on label filtering.

  • creationTimestampAfter: filters resources created after the specified timestamp (RFC3339 format, e.g., 2023-01-01T12:00:00Z).

  • creationTimestampBefore: filters resources created before the specified timestamp (RFC3339 format, e.g., 2023-12-31T23:59:59Z).

Timestamp Filters

The API supports filtering resources by their creation timestamp using RFC3339 format:

After timestamp

creationTimestampAfter=2023-01-01T12:00:00Z

Before timestamp

creationTimestampBefore=2023-12-31T23:59:59Z

Both filters

creationTimestampAfter=2023-01-01T12:00:00Z&creationTimestampBefore=2023-12-31T23:59:59Z

Timestamp filters can be combined with other filters (labelSelector, pagination) and will be applied as AND conditions.

Examples:

/api/v1/namespaces/default/pods?creationTimestampAfter=2023-06-01T00:00:00Z (1)
/apis/apps/v1/namespaces/production/deployments?creationTimestampBefore=2023-12-31T23:59:59Z (2)
/api/v1/pods?creationTimestampAfter=2023-01-01T00:00:00Z&creationTimestampBefore=2023-01-31T23:59:59Z (3)
/api/v1/namespaces/default/pods?creationTimestampAfter=2023-06-01T00:00:00Z&labelSelector=app=frontend (4)
1 Filter pods created after a specific date
2 Filter deployments created before a specific date
3 Filter resources created within a date range
4 Combine timestamp filters with label selectors

Label Selector

It implements the same filters available in the Kubernetes API:

Existence

labelSelector=wantedLabelKey

Not existence

labelSelector=!unwantedLabelKey or labelSelector=%21unwantedLabelKey with URL encoding

Equality

labelSelector=labelKey=labelValue or labelSelector=labelKey%3DlabelValue with URL encoding

Inequality

labelSelector=labelKey!=unwantedLabelValue or labelSelector=labelKey%21%3DlabelValue with URL encoding

Set based

labelSelector=labelKey in (value1, value2) or labelSelector=labelKey+in+%28value1,+value2%29 with URL encoding

Set not based

labelSelector=labelKey notin (value1, value2) or labelSelector=labelKey+notin+%28value1,+value2%29 with URL encoding

Label selectors can be combined based on a logical AND by separating them with a comma.

For example to retrieve pods in the default namespace with the following label selector: app=kubearchive, env in (stage, dev), release!=stable

The API call is:

/api/v1/namespaces/default/pods?labelSelector=app%3Dkubearchive%2C+env+in+%28stage%2C+dev%29%2C+release%21%3Dstable

Individual Resources

/apis/:group/:version/namespaces/:namespace/:resourceType/:name
/api/:version/namespaces/:namespace/:resourceType/:name

Examples:

/apis/batch/v1/namespaces/default/cronjobs/cleanup-tasks
/api/v1/namespaces/default/pods/busybox-tooling

Logs

/apis/:group/:version/namespaces/:namespace/:resourceType/:name/log
/api/:version/namespaces/:namespace/:resourceType/:name/log

Examples:

/apis/batch/v1/namespaces/default/cronjobs/cleanup-tasks/log
/api/v1/namespaces/default/pods/busybox-tooling/log

Parameters allowed: * container: name of the container to select the log from, defaults to an empty string.

When /log endpoint is called for a resource other than a Pod, KubeArchive searches, recursively, for any Pod owned by the resource. If a Pod is found its log is returned.

When a Pod has multiple containers, a single container is selected in the following order of preference:

  • container parameter

  • kubectl.kubernetes.io/default-container Pod annotation

  • First container listed in the Pod definition