Leveraging the strengths of the declarative and imperative ways of Kubernetes for your team

(Octopus, Shawn Sesna, 2021)

Kubernetes is a powerful and flexible platform for deploying and managing applications and services in the cloud. One of the key features of Kubernetes is its ability to support two different ways of managing applications and resources: the declarative way and the imperative way. In this blog, we will compare the declarative and imperative ways of managing Kubernetes clusters, and we will discuss the advantages and disadvantages of each approach.

The declarative way of managing Kubernetes involves specifying the desired state of the applications and resources, and letting Kubernetes figure out how to achieve this state. This is done using declarative configuration files, which define the desired properties and behaviors of the applications and resources, such as the number of replicas, the resource constraints, the health checks, and the access controls.

The imperative way of managing Kubernetes, on the other hand, involves giving Kubernetes explicit instructions on how to manage the applications and resources. This is done using imperative commands and APIs, which specify the actions that Kubernetes should take, such as creating, updating, or deleting resources, or scaling, rolling out, or rolling back deployments.

Here are some examples for the declarative and imperative ways of managing provisioning a Service in the Kubernetes clusters:

Declarative way:

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

kubectl apply -f service.yaml

Imperative way:

kubectl create service my-service --selector=app=my-app --port=80:8080

In the declarative way, teams specify the desired state of the applications and resources using a configuration file in YAML format. In the example above, the configuration file specifies a service named my-service that selects the pods with the label app=my-app and exposes the port 80 as the target port 8080. Teams can then use the kubectl apply command to apply the configuration file to the cluster, and Kubernetes will automatically and consistently create and manage the service based on the specified state.

In the imperative way, teams specify the desired actions and parameters using commands and options. In the example above, the kubectl create service command creates a service named my-service that selects the pods with the label app=my-app and exposes the port 80 as the target port 8080. Teams can then use the kubectl expose service command to expose the service, and they can use the kubectl expose ingress command to expose the ingress. This allows teams to directly and dynamically interact with the applications and resources, and to get immediate feedback and results.

One of the main advantages of the declarative way is that it is more flexible and adaptable than the imperative way. This is because the declarative way allows teams to specify the desired state of the applications and resources, and it allows Kubernetes to figure out the best way to achieve this state. This can make the declarative way more resilient to changes and failures, and it can make it easier to update and maintain the applications and resources over time.

For example, if a team specifies that they want their deployment to have three replicas, Kubernetes will automatically create and manage the replicas in a way that is optimal for the current conditions and constraints of the cluster. If the team later decides to increase the number of replicas to four, Kubernetes will automatically add the fourth replica without disrupting the existing replicas. This can make the declarative way more efficient and effective than the imperative way, which would require teams to manually create and manage the replicas.

Another advantage of the declarative way is that it is more predictable and transparent than the imperative way. This is because the declarative way allows teams to specify the desired state of the applications and resources in a clear and explicit way, and it allows Kubernetes to automatically and consistently apply these specifications to the cluster. This can make the declarative way more predictable and traceable than the imperative way, which can be more prone to errors and inconsistencies.

For example, if a team specifies that they want their deployment to use a specific image and a specific configuration, Kubernetes will automatically ensure that the deployment uses the specified image and configuration, regardless of who is deploying or updating the deployment. This can make the declarative way more reliable and auditable than the imperative way, which may allow different users to deploy or update the deployment using different images or configurations.

One of the main disadvantages of the declarative way is that it can be more complex and difficult to understand than the imperative way. This is because the declarative way requires teams to specify the desired state of the applications and resources in a precise and detailed way, and it requires teams to understand the underlying mechanisms and conventions of Kubernetes. This can make the declarative way more challenging and steep to learn than the imperative way, which is often more intuitive and straightforward.

For example, if a team wants to deploy a simple web application to Kubernetes, the declarative way may require them to write a configuration file that specifies the deployment, the service, the ingress, the liveness probe, and the readiness probe, among other things. This can be more complex and daunting than the imperative way, which may allow teams to deploy the web application using a single command or a few commands, such as kubectl create deployment, kubectl expose service, and kubectl expose ingress.

Another disadvantage of the declarative way is that it can be less flexible and reactive than the imperative way. This is because the declarative way relies on Kubernetes to automatically and consistently apply the specified state to the cluster, and it does not allow teams to directly and dynamically interact with the applications and resources. This can make the declarative way less responsive and agile than the imperative way, which allows teams to issue commands and APIs in real time and to get immediate feedback and results.

For example, if a team wants to troubleshoot a deployment that is not working as expected, the declarative way may require them to update the configuration file and to wait for Kubernetes to apply the changes to the cluster. This can be less flexible and efficient than the imperative way, which may allow teams to use commands and APIs to inspect, debug, and fix the deployment in real time, without needing to update the configuration file.

Overall, the declarative and imperative ways of managing Kubernetes clusters are two different approaches that offer different benefits and drawbacks. The declarative way allows teams to specify the desired state of the applications and resources, and it allows Kubernetes to automatically and consistently apply these specifications to the cluster. This can make the declarative way more flexible, adaptable, predictable, and transparent, but it can also make it more complex and less reactive.

The imperative way, on the other hand, allows teams to give Kubernetes explicit instructions on how to manage the applications and resources. This can make the imperative way more intuitive, straightforward, responsive, and agile, but it can also make it less reliable and less auditable.

As a best practice, teams should use the declarative way for managing the core components and the essential properties of their applications and resources, and they should use the imperative way for managing the transient and dynamic aspects of their applications and resources. This can help teams to benefit from the strengths of both approaches, and it can help them to optimize their workflow and their release cycle.