Reference Documentation

Design docs, concept definitions, and references for APIs and CLIs.

Edit This Page

Top Level API Objects

Definitions

unversioned.Patch

Patch is provided to give a concrete name and type to the Kubernetes PATCH request body.

v1.DeleteOptions

DeleteOptions may be provided when deleting an API object

Name Description Required Schema Default

kind

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds

false

string

apiVersion

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#resources

false

string

gracePeriodSeconds

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

true

integer (int64)

v1.HorizontalPodAutoscalerList

list of horizontal pod autoscaler objects.

Name Description Required Schema Default

kind

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds

false

string

apiVersion

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#resources

false

string

metadata

Standard list metadata.

false

unversioned.ListMeta

items

list of horizontal pod autoscaler objects.

true

v1.HorizontalPodAutoscaler array

unversioned.StatusDetails

StatusDetails is a set of additional properties that MAY be set by the server to provide additional information about a response. The Reason field of a Status object defines what attributes will be set. Clients must ignore fields that do not match the defined type of each attribute, and should assume that any attribute may be empty, invalid, or under defined.

Name Description Required Schema Default

name

The name attribute of the resource associated with the status StatusReason (when there is a single name which can be described).

false

string

group

The group attribute of the resource associated with the status StatusReason.

false

string

kind

The kind attribute of the resource associated with the status StatusReason. On some operations may differ from the requested resource Kind. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds

false

string

causes

The Causes array includes more details associated with the StatusReason failure. Not all StatusReasons may provide detailed causes.

false

unversioned.StatusCause array

retryAfterSeconds

If specified, the time in seconds before the operation should be retried.

false

integer (int32)

unversioned.ListMeta

ListMeta describes metadata that synthetic resources must have, including lists and various status objects. A resource may have only one of {ObjectMeta, ListMeta}.

Name Description Required Schema Default

selfLink

SelfLink is a URL representing this object. Populated by the system. Read-only.

false

string

resourceVersion

String that identifies the server’s internal version of this object that can be used by clients to determine when objects have changed. Value must be treated as opaque by clients and passed unmodified back to the server. Populated by the system. Read-only. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#concurrency-control-and-consistency

false

string

v1.CrossVersionObjectReference

CrossVersionObjectReference contains enough information to let you identify the referred resource.

Name Description Required Schema Default

kind

Kind of the referent; More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds"

true

string

name

Name of the referent; More info: http://releases.k8s.io/release-1.2/docs/user-guide/identifiers.md#names

true

string

apiVersion

API version of the referent

false

string

v1.HorizontalPodAutoscaler

configuration of a horizontal pod autoscaler.

Name Description Required Schema Default

kind

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds

false

string

apiVersion

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#resources

false

string

metadata

Standard object metadata. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#metadata

false

v1.ObjectMeta

spec

behaviour of autoscaler. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#spec-and-status.

false

v1.HorizontalPodAutoscalerSpec

status

current information about the autoscaler.

false

v1.HorizontalPodAutoscalerStatus

unversioned.Status

Status is a return value for calls that don’t return other objects.

Name Description Required Schema Default

kind

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds

false

string

apiVersion

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#resources

false

string

metadata

Standard list metadata. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#types-kinds

false

unversioned.ListMeta

status

Status of the operation. One of: "Success" or "Failure". More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#spec-and-status

false

string

message

A human-readable description of the status of this operation.

false

string

reason

A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. A Reason clarifies an HTTP status code but does not override it.

false

string

details

Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type.

false

unversioned.StatusDetails

code

Suggested HTTP return code for this status, 0 if not set.

false

integer (int32)

v1.HorizontalPodAutoscalerStatus

current status of a horizontal pod autoscaler

Name Description Required Schema Default

observedGeneration

most recent generation observed by this autoscaler.

false

integer (int64)

lastScaleTime

last time the HorizontalPodAutoscaler scaled the number of pods; used by the autoscaler to control how often the number of pods is changed.

false

string

currentReplicas

current number of replicas of pods managed by this autoscaler.

true

integer (int32)

desiredReplicas

desired number of replicas of pods managed by this autoscaler.

true

integer (int32)

currentCPUUtilizationPercentage

current average CPU utilization over all pods, represented as a percentage of requested CPU, e.g. 70 means that an average pod is using now 70% of its requested CPU.

false

integer (int32)

v1.HorizontalPodAutoscalerSpec

specification of a horizontal pod autoscaler.

Name Description Required Schema Default

scaleTargetRef

reference to scaled resource; horizontal pod autoscaler will learn the current resource consumption and will set the desired number of pods by using its Scale subresource.

true

v1.CrossVersionObjectReference

minReplicas

lower limit for the number of pods that can be set by the autoscaler, default 1.

false

integer (int32)

maxReplicas

upper limit for the number of pods that can be set by the autoscaler; cannot be smaller than MinReplicas.

true

integer (int32)

targetCPUUtilizationPercentage

target average CPU utilization (represented as a percentage of requested CPU) over all the pods; if not specified the default autoscaling policy will be used.

false

integer (int32)

v1.ObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

Name Description Required Schema Default

name

Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://releases.k8s.io/release-1.2/docs/user-guide/identifiers.md#names

false

string

generateName

GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server.

If this field is specified and the generated name exists, the server will NOT return a 409 - instead, it will either return 201 Created or 500 with Reason ServerTimeout indicating a unique name could not be found in the time allotted, and the client should retry (optionally after the time indicated in the Retry-After header).

Applied only if Name is not specified. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#idempotency

false

string

namespace

Namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty.

Must be a DNS_LABEL. Cannot be updated. More info: http://releases.k8s.io/release-1.2/docs/user-guide/namespaces.md

false

string

selfLink

SelfLink is a URL representing this object. Populated by the system. Read-only.

false

string

uid

UID is the unique in time and space value for this object. It is typically generated by the server on successful creation of a resource and is not allowed to change on PUT operations.

Populated by the system. Read-only. More info: http://releases.k8s.io/release-1.2/docs/user-guide/identifiers.md#uids

false

string

resourceVersion

An opaque value that represents the internal version of this object that can be used by clients to determine when objects have changed. May be used for optimistic concurrency, change detection, and the watch operation on a resource or set of resources. Clients must treat these values as opaque and passed unmodified back to the server. They may only be valid for a particular resource or set of resources.

Populated by the system. Read-only. Value must be treated as opaque by clients and . More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#concurrency-control-and-consistency

false

string

generation

A sequence number representing a specific generation of the desired state. Populated by the system. Read-only.

false

integer (int64)

creationTimestamp

CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations. Clients may not set this value. It is represented in RFC3339 form and is in UTC.

Populated by the system. Read-only. Null for lists. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#metadata

false

string

deletionTimestamp

DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This field is set by the server when a graceful deletion is requested by the user, and is not directly settable by a client. The resource will be deleted (no longer visible from resource lists, and not reachable by name) after the time in this field. Once set, this value may not be unset or be set further into the future, although it may be shortened or the resource may be deleted prior to this time. For example, a user may request that a pod is deleted in 30 seconds. The Kubelet will react by sending a graceful termination signal to the containers in the pod. Once the resource is deleted in the API, the Kubelet will send a hard termination signal to the container. If not set, graceful deletion of the object has not been requested.

Populated by the system when a graceful deletion is requested. Read-only. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#metadata

false

string

deletionGracePeriodSeconds

Number of seconds allowed for this object to gracefully terminate before it will be removed from the system. Only set when deletionTimestamp is also set. May only be shortened. Read-only.

false

integer (int64)

labels

Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://releases.k8s.io/release-1.2/docs/user-guide/labels.md

false

any

annotations

Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://releases.k8s.io/release-1.2/docs/user-guide/annotations.md

false

any

unversioned.StatusCause

StatusCause provides more information about an api.Status failure, including cases when multiple errors are encountered.

Name Description Required Schema Default

reason

A machine-readable description of the cause of the error. If this value is empty there is no information available.

false

string

message

A human-readable description of the cause of the error. This field may be presented as-is to a reader.

false

string

field

The field of the resource that has caused this error, as named by its JSON serialization. May include dot and postfix notation for nested attributes. Arrays are zero-indexed. Fields may appear more than once in an array of causes due to fields having multiple errors. Optional.

Examples:
"name" - the field "name" on the current resource
"items[0].name" - the field "name" on the first array entry in "items"

false

string

json.WatchEvent

Name Description Required Schema Default

type

the type of watch event; may be ADDED, MODIFIED, DELETED, or ERROR

false

string

object

the object being watched; will match the type of the resource endpoint or be a Status object if the type is ERROR

false

string

any

Represents an untyped JSON map - see the description of the field for more info about the structure of this object.

Analytics