API reference

This document contains the endpoints and features supported by the KubeArchive API. It also lists the query parameters each endpoint supports.

General Features

gzip Compression

The KubeArchive API supports gzip compression using the standard headers for compression. To receive compressed content, the client should send an Accept-Encoding header with gzip among its values. KubeArchive response will contain a Content-Encoding: gzip header. Note that error responses are not compressed.

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).

  • name: allows filtering resources by name with wildcard support (see Name Filtering section below).

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

Name Filtering

The name parameter supports wildcard pattern matching for filtering resources by name. The filtering is case-insensitive and supports the following wildcard patterns:

Exact match

name=my-deployment - Matches resources with exactly the name "my-deployment"

Prefix match

name=test-* - Matches resources whose names start with "test-"

Suffix match

name=*-job - Matches resources whose names end with "-job"

Contains match

name=e2e - Matches resources whose names contain "e2e" anywhere

Examples:

# Find all deployments containing "e2e" in their name
/apis/apps/v1/namespaces/default/deployments?name=*e2e*

# Find all pods starting with "test-"
/api/v1/namespaces/default/pods?name=test-*

# Find all services ending with "-api"
/api/v1/namespaces/default/services?name=*-api

# Exact match (same as before, no wildcards)
/api/v1/namespaces/default/pods?name=my-exact-pod-name

# Invalid: Both path and query name parameters (returns 400)
/api/v1/namespaces/default/pods/existing-pod?name=*e2e*

# Invalid: Wildcard in path parameter (returns 400)
/api/v1/namespaces/default/pods/*e2e*

  • Wildcard queries return a list of matching resources with pagination support

  • Exact name queries (without wildcards) return a single resource object

  • Name filtering is case-insensitive: E2E matches "test-e2e-pod"

  • Name filtering can be combined with labelSelector for more precise filtering

  • Cannot specify both path name parameter and query name parameter (returns 400 Bad Request)

  • Wildcard characters (*) are not allowed in path parameters, use query parameters instead (returns 400 Bad Request)

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