Kubernetes are persistent objects that reside within the Kubernetes system, and represent the state of the cluster.

They can describe:

  • Which workloads are running (and on which nodes)
  • Resources available to workloads in the system
  • Policies describing how workloads should behave (restart policies, upgrades, and fault-tolerance)

An object can be thought of as a "record of intent" -- after the object is created, Kubernetes will work to ensure it is exists. The composition of all created objects are the systems desired state.

In order to create, modify, or delete objects in Kubernetes, you will need to interact with the API. For example, you can use kubectl (the default command-line interface), which will in turn make the API calls for you. Alternatively, you can leverage the RESTful API directly in your own client applications.

Spec & Status 

Alls Kubernetes objects include two nested object fields that drive the object’s configuration: the object spec and object status. The required spec field describes your desired state for the object. On the other hand, the status field describes the actual state of the object, and is controlled by Kubernetes itself.  Kubernetes will actively manage an object’s actual state to match the desired state you supplied.

For example, a Deployment is an object that represents an application running on your cluster. When creating a Deployment, you might set the spec to specify that you want five replicas to be running. The system will read the Deployment spec, and start five instances of your desired application. The status will be updated to match the spec. If any of those instances should fail (a status change), the Kubernetes system will respond to the difference between the spec and status fields by taking an action. In this case, the system would replace the failed instance.

Describing an Object

When creating a Kubernetes object, some basic information (such as name) is required in addition to the spec. When you use the Kubernetes API to create the object (either directly or indirectly), the API request must include all required fields as JSON in the request body. When providing a YAML file to kubectl, it will be converted to JSON automatically when making the API request.

apiVersion: apps/v1 # for versions before 1.9.0 use apps/v1beta2
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 5
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

One way to create a Deployment using a YAML file (like the one above) is to use the kubectl create command in the kubectl command-line interface, passing the YAML file as an argument.

For example:

$ kubectl create -f https://k8s.io/docs/user-guide/nginx-deployment.yaml --record

If the command executes successfully, you will see output similar to:

deployment "nginx-deployment" created

Required Fields

In the YAML configuration for the Kubernetes object you want to create, you’ll need to set the following:

  • apiVersion - the Kubernetes API version you’re using to create this object
  • kind - the kind of object you want to create
  • metadata - data used to uniquely identify the object, including a name string, UID, and optional namespace
  • spec - contains nested fields specific to the given object
Did this answer your question?