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

  • 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