Kubernetes is a REST API driven system. All the operations in the system are executed by making the API requests to it’s API server. This makes kubernetes easy to interact from external systems.

Most of the initial interactions with the API is done using kubectl. kubectl is a command line tool which converts the user commands to a API call.But once the user is comfortable with kubectl, for advance operations it will be beneficial to know how to interact with API directly. This gives more power to the user to express the operations more effectively.

So in this series of blog posts, I will be discussing about how to use various kubernetes API’s. This is the third post in the series which discusses about deployments API. You can access all the posts in the series here.

Deployments API

Deployment is a kubernetes abstraction that is responsible for running one or more replicas of a pod. Most of the time deployments are preferred over pod as they provide more control over failures of a pod.

Deployments API is the part of Kubernetes API which allows user to run CRUD operations on deployments.

List Deployments

We can list the deployments using GET API call to /apis/apps/v1/namespaces/{namespace}/deployments.

The below curl request lists all the deployments in kube-system namespace.

curl --request GET \
  --url http://localhost:8080/apis/apps/v1/namespaces/kube-system/deployments

The output contains same fields as pods. But status field of the deployment has information about number of replicas. You can observe in below output

  "status": {
        "observedGeneration": 1,
        "replicas": 1,
        "updatedReplicas": 1,
        "readyReplicas": 1,
        "availableReplicas": 1
}

Get Details about Single Deployment

We can access the details of individual deployment using /apis/apps/v1/namespaces/{namespace}/deployments/{deployment-name}.

Example for kube-dns deployment look as below

curl --request GET \
  --url http://localhost:8080/apis/apps/v1/namespaces/kube-system/deployments/kube-dns

Create Deployment

Creating deployment requires defining the spec and metadata for the same. Usually user writes a yaml file to define the spec.

The below is the YAML definition for creating ngnix deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

Kubernetes API accepts the json rather than YAML. The respective json looks as below

{
    "apiVersion":"apps/v1",
    "kind":"Deployment",
    "metadata":{
        "name":"nginx-deployment",
        "labels":{
            "app":"nginx"
        }
    },
    "spec": {
    "replicas" : 3,
    "selector": {
        "matchLabels" : {
            "app":"nginx"
        }
    },
    "template" : {
    "metadata" : {
        "labels" : {
            "app":"nginx"
        }
    },
    "spec":{
        "containers":[
            {
                "name":"ngnix",
                "image":"nginx:1.7.9",
                "ports":[
                  {
                    "containerPort": 80 
                }
                ]
            }
        ]
    }
 }
}
}

User needs to send PUT API call to apps/v1/namespaces/default/deployments.

curl --request POST \
  --url http://localhost:8080/apis/apps/v1/namespaces/default/deployments \
  --header 'content-type: application/json' \
  --data '{
	"apiVersion":"apps/v1",
	"kind":"Deployment",
	"metadata":{
		"name":"nginx-deployment",
		"labels":{
			"app":"nginx"
		}
	},
	"spec": {
	"replicas" : 3,
	"selector": {
		"matchLabels" : {
			"app":"nginx"
		}
	},
	"template" : {
	"metadata" : {
		"labels" : {
			"app":"nginx"
		}
	},
	"spec":{
		"containers":[
			{
				"name":"ngnix",
				"image":"nginx:1.7.9",
				"ports":[
				  {
				    "containerPort": 80 
			    }
				]
			}
		]
	}
 }
}
}'

Delete Deployment

We can delete individual deployment using DELETE API call /apis/apps/v1/namespaces/default/deployments/nginx-deployment.

curl --request DELETE \
  --url http://localhost:8080/apis/apps/v1/namespaces/default/deployments/nginx-deployment

Conclusion

Deployment is a abstraction in kubernetes to run multiple replicas of a pod. In this post, we discussed about how to create, delete and list deployments using kubernetes API.