DOCSEARCHbyAlgolia
Submit Docs

Kubernetes API Go Type Definitions

repository·master·Indexed 20 days ago

https://github.com/kubernetes/api

Canonical Go type definitions for the Kubernetes API, provided as a staged, read-only repository to prevent diamond dependency conflicts. It includes types for resources such as Deployments, StatefulSets, DaemonSets, and ReplicaSets, featuring support for DeepCopy cloning, OpenAPI model name identification, and protobuf serialization/deserialization.

Tokens
9.8K
Snippets
34
Records
54
Agent score
72%

What's inside kubernetes-api

  1. Understand the purpose and dependency model of k8s.io/api

    master

    The k8s.io/api repository is a staged, read-only version of the Kubernetes API definitions. It is published separately from the main Kubernetes repository to prevent 'diamond dependency' issues.

    Developers who depend on multiple Kubernetes libraries (such as k8s.io/client-go, k8s.io/apimachinery, and k8s.io/apiserver) benefit from this separation because it allows them to use the API definitions without being forced into a specific version of the entire Kubernetes codebase.

  2. How to use the Kubernetes API types

    master

    The k8s.io/api repository contains the canonical Go type definitions for the Kubernetes API.

    Recommended Usage

    • Use Go types directly: The recommended way to interact with Kubernetes is to use the Go types provided in this repository. These types can be serialized directly to JSON for most use cases.
    • Avoid direct Proto serialization: Do not attempt to serialize these types directly to Protobuf if you need to match the Kubernetes wire format. The official Kubernetes wire format uses a specific envelope and a magic prefix. To interact with proto-formatted objects correctly, use the official serialization stack found in k8s.io/apimachinery.
    • Storage Best Practices: When storing Kubernetes objects in your own systems, do not embed these proto objects directly into your own Protobuf definitions. Instead, store them as byte arrays in their wire format. This allows your system to handle both JSON and binary (proto) formats without code changes and ensures compatibility with Custom Resources and built-in types.

  3. DeepCopy methods for apps/v1beta1 API types

    master

    The apps/v1beta1 package provides autogenerated DeepCopy methods for its API types (such as Deployment, StatefulSet, Scale, and ControllerRevision). These methods allow for creating a complete, independent copy of an object and its nested fields, which is essential when working with Kubernetes controllers to avoid side effects from mutating shared state.

    Each type typically implements three methods:

    1. DeepCopy(): Returns a new pointer to a copy of the receiver. If the receiver is nil, it returns nil.
    2. DeepCopyInto(out *Type): Copies the receiver's data into an existing, non-nil out object. This is more memory-efficient as it avoids new allocations if the destination is already provided.
    3. DeepCopyObject() runtime.Object: Satisfies the runtime.Object interface, returning the copy as a generic runtime.Object type.

  4. Use DeepCopy methods to clone Kubernetes API objects

    master

    The apps/v1 package provides autogenerated DeepCopy methods for its types (such as Deployment, DaemonSet, ReplicaSet, and StatefulSet). These methods allow you to create a complete, independent copy of an object, ensuring that modifications to the new object do not affect the original.

    There are three primary patterns for deep copying:

    1. DeepCopy(): Creates and returns a new pointer to a copy of the receiver. If the receiver is nil, it returns nil.
    2. DeepCopyInto(out): Copies the receiver's values into an existing, non-nil object out. This is more memory-efficient when you already have a destination object allocated.
    3. DeepCopyObject(): Returns the copy as a runtime.Object interface, which is useful when working with generic Kubernetes runtime functions.
    // Example: Cloning a Deployment
newDeployment := originalDeployment.DeepCopy()

// Example: Cloning into an existing object
var target Deployment
originalDeployment.DeepCopyInto(&target)

// Example: Using the runtime.Object interface
var obj runtime.Object = originalDeployment.DeepCopyObject()

  5. Migrate from deprecated apps/v1beta1 types

    master

    When using deprecated types in the apps/v1beta1 group, you can use the APILifecycleReplacement() method to find the correct replacement. For example, most v1beta1 types in the apps group should be migrated to their v1 counterparts.

    Common migrations include:

    • apps/v1beta1/Deployment $\rightarrow$ apps/v1/Deployment
    • apps/v1beta1/StatefulSet $\rightarrow$ apps/v1/StatefulSet
    • apps/v1beta1/ControllerRevision $\rightarrow$ apps/v1/ControllerRevision

  6. Unmarshal Deployment and DeploymentList from protobuf bytes

    master

    The Deployment and DeploymentList types provide Unmarshal([]byte) error methods to deserialize protobuf-encoded data into the respective Go structs.

    For Deployment, the unmarshaler processes fields for ObjectMeta, Spec, and Status. For DeploymentList, it processes ListMeta and a repeated sequence of Items (each being a Deployment).

  7. Unmarshal StatefulSetSpec from protobuf

    master

    The StatefulSetSpec type provides an Unmarshal method to deserialize its state from a byte slice. The StatefulSetSpec structure contains:

    • Replicas (*int32): Desired number of replicas.
    • Selector (*v1.LabelSelector): Label selector for pods.
    • Template (*PodTemplateSpec): Pod template.
    • VolumeClaimTemplates ([]v11.PersistentVolumeClaim): List of PVC templates.
    • ServiceName (string): Name of the service.
    • PodManagementPolicy (PodManagementPolicyType): Policy for pod management.
    • UpdateStrategy (*StatefulSetUpdateStrategy): Strategy for updates.
    • RevisionHistoryLimit (*int32): Limit for revision history.
    • MinReadySeconds (int32): Minimum seconds for a pod to be considered ready.
    • PersistentVolumeClaimRetentionPolicy (*StatefulSetPersistentVolumeClaimRetentionPolicy): PVC retention policy.
    • Ordinals (*StatefulSetOrdinals): Ordinal configuration.
    err := spec.Unmarshal(data)

  8. Unmarshal StatefulSet protobuf messages

    master

    The StatefulSet type in apps/v1beta2 supports protobuf unmarshaling. It includes the following fields:

    • ObjectMeta (field 1, wire type 2)
    • Spec (field 2, wire type 2)
    • Status (field 3, wire type 2)

    Fields within StatefulSet.Spec include:

    • Replicas (field 1, wire type 0)
    • Selector (field 2, wire type 2)
    • Template (field 3, wire type 2)
    • VolumeClaimTemplates (field 4, wire type 2)
    • ServiceName (field 5, wire type 2)
    • PodManagementPolicy (field 6, wire type 2)
    • UpdateStrategy (field 7, wire type 2)
    • RevisionHistoryLimit (field 8, wire type 0)
    • MinReadySeconds (field 9, wire type 0)
    • PersistentVolumeClaimRetentionPolicy (field 10, wire type 2)
    • Ordinals (field 11, wire type 2)
    func (m *StatefulSet) Unmarshal(dAtA []byte) error

  9. String representation of DeploymentSpec and DeploymentStatus

    master
    The DeploymentSpec and DeploymentStatus types implement String() methods to provide detailed views of the deployment's desired state and current observed state, respectively. DeploymentSpec includes fields like Replicas, Selector, Template, Strategy, and RevisionHistoryLimit. DeploymentStatus includes ObservedGeneration, Replicas, UpdatedReplicas, AvailableReplicas, UnavailableReplicas, Conditions, and ReadyReplicas.

  12. Get OpenAPI model names for apps/v1 types

    master
    The apps/v1 package provides an OpenAPIModelName() method on its exported types. This method returns the canonical OpenAPI model name string used for schema identification in the Kubernetes OpenAPI specification. This is primarily used by tools and clients that interact with the Kubernetes API via OpenAPI-based discovery or code generation.