KAHIBARO Bookshelves
Discord Login Register

3.6. Declarative configuration model

Imperative vs Declarative in Kubernetes

In Kubernetes, the declarative configuration model means you describe what the desired state of the system should be, and the system figures out how to make it so.

This contrasts with imperative usage, where you directly tell Kubernetes what action to perform step by step.

  • Imperative style examples (telling it what to do right now):
    • kubectl create deployment ...
    • kubectl scale deployment myapp --replicas=5
  • Declarative style examples (describing the final state you want):
    • A YAML file that says:
      • there should be a Deployment named myapp
      • it should have 5 replicas
      • they should run a specific image

Kubernetes’ controllers then work continuously to match the actual state of the cluster to the desired state you declared.

Desired vs Actual State

The declarative model is built around the idea of desired state:

  • You specify the desired state in resource manifests (YAML/JSON).
  • Kubernetes stores this state in the API server.
  • Controllers watch for changes and reconcile the real world back towards the desired state.

Conceptually:

  • Desired state: “There should always be 3 replicas of this pod running.”
  • Actual state: “Right now, there are only 2 pods running because one crashed.”
  • Reconciliation loop: A controller notices the difference and schedules a new pod to restore 3 replicas.

This model makes Kubernetes:

  • Self-healing: drifts from the desired state are corrected automatically.
  • Predictable: you can inspect the stored configuration to see what the cluster should look like.
  • Repeatable: you can apply the same manifests in different clusters and expect consistent results.

Resource Manifests as Source of Truth

In the declarative model, Kubernetes resources are usually defined in manifest files (often YAML):

  • Manifests represent the source of truth for application and cluster configuration.
  • They can be:
    • checked into version control (e.g., Git)
    • peer-reviewed
    • versioned, rolled back, and audited

A Kubernetes manifest typically includes:

  • apiVersion: which version of the API this resource uses
  • kind: the type of resource (e.g. Deployment, Service)
  • metadata: name, namespace, labels, annotations
  • spec: the desired configuration for that resource

Example (simplified) Deployment manifest:

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

In this file you’re not giving step-by-step instructions; you are declaring:

  • there should be a Deployment called myapp
  • it should manage 3 replicas
  • pods should run the nginx:1.27 image

Idempotence and Repeated Application

A key property of the declarative model is idempotence:

  • Applying the same manifest multiple times leads to the same resulting state.
  • Re-applying a file:
    • updates only the fields that changed
    • leaves others untouched
    • does not duplicate the resource

This enables workflows like:

  • Safely running kubectl apply -f . many times during development.
  • Automated systems (e.g., GitOps tools) continuously reconciling manifests with the cluster without harming running workloads.

Using `kubectl` Declaratively

Kubernetes supports a declarative workflow through commands like:

  • kubectl apply -f file.yaml
  • kubectl apply -f ./directory/
  • kubectl delete -f file.yaml

kubectl apply:

  • Sends your desired configuration to the API server.
  • Stores a “last applied” configuration as an annotation (by default).
  • Computes the diff between current and desired configuration to perform minimal changes.

Common patterns:

  • Maintain one or more directories of YAML manifests for your application.
  • Use kubectl apply -f on those directories for:
    • initial deployment
    • configuration updates
    • sync after changes in version control

Partial vs Full Specifications

In declarative manifests, you typically:

  • Specify the fields you care about under spec.
  • Rely on Kubernetes to fill in defaults or status fields.

Over-specifying everything can:

  • Make manifests verbose and harder to maintain.
  • Increase chances of conflicts with fields managed by controllers or the cluster itself.

Common practice:

  • Define only the critical settings in spec (e.g., replicas, containers, resources).
  • Avoid modifying fields that are clearly managed by controllers (for example, most of status).

Patching and Declarative Updates

While kubectl apply is the main declarative tool, Kubernetes also supports patching resources:

  • kubectl patch allows you to adjust specific parts of a resource without replacing the entire spec.
  • This can be done in a declarative-like way using strategic merge or JSON patches, but is often used for one-off changes.

Example:

kubectl patch deployment myapp \
  -p '{"spec":{"replicas":5}}'

This is somewhat between imperative and declarative:

  • You’re not scripting every step.
  • But you are not maintaining the full desired state in a file either.

In a strictly declarative practice, you’d usually:

  • Update the replicas field in the YAML file.
  • Re-apply the manifest to keep the file as the source of truth.

Declarative Model and GitOps

The declarative configuration model is a foundation for GitOps practices:

  • All cluster and application configuration is declared in version-controlled manifests.
  • A Git repository becomes the canonical desired state.
  • Automated agents (such as Argo CD or Flux) continuously:
    • compare cluster state with the Git repo
    • apply changes to converge the cluster to what’s declared in Git

This builds on Kubernetes’ native reconciliation:

  • Kubernetes reconciles its own internal objects to match their manifests.
  • GitOps tools reconcile the cluster objects to match what’s in Git.

Advantages and Trade-Offs

Advantages:

  • Consistency: same manifests deployed in many environments yield consistent results.
  • Auditability: history of changes is tracked in version control.
  • Recovery: you can recreate cluster state from manifests after a failure.
  • Automation-friendly: tools can safely re-apply configuration without side effects.

Trade-offs:

  • Learning curve: requires understanding resource schemas and YAML.
  • State drift without discipline: imperative ad-hoc changes (kubectl edit, kubectl scale) can move the cluster away from what’s in your manifests.
  • Merge conflicts: many people editing the same manifests can lead to version control conflicts.

Typical mitigation:

  • Adopt a workflow where all intentional changes go through manifests (and usually Git).
  • Minimize direct imperative changes in production clusters, or treat them as temporary/debug-only.

Practical Guidelines

When working with Kubernetes in a declarative way:

  • Prefer kubectl apply -f (or equivalent tooling) over imperative kubectl create/kubectl scale for ongoing management.
  • Keep manifests:
    • small and focused (group related resources together)
    • named clearly (e.g., deployment-myapp.yaml, service-myapp.yaml)
  • Store all manifests in version control and treat them as code.
  • Avoid manual edits to running resources that are not reflected back into the manifests.
  • Use labels and annotations consistently in manifests to support automation and organization.

These practices let you fully benefit from Kubernetes’ declarative configuration model and its reconciliation-driven behavior.

Views: 0

Comments

Please login to add a comment.

Don't have an account? Register now!

Where to Move

Move chapter:

  • ☰ 1. Course Overview
    • ☰ 1.1. What is OpenShift
      • ☰ 1.2. Why OpenShift is used in modern IT and cloud environments
        • ☰ 1.3. OpenShift vs Kubernetes
          • ☰ 1.4. Typical OpenShift use cases
            • ☰ 1.5. Structure and goals of the course
            • ☰ 2. Containers and Cloud-Native Fundamentals
              • ☰ 2.1. What is a container
                • ☰ 2.2. Containers vs virtual machines
                  • ☰ 2.3. Introduction to Docker and container images
                    • ☰ 2.4. Container registries
                      • ☰ 2.5. Basics of cloud-native applications
                      • ☰ 3. Kubernetes Fundamentals
                        • ☰ 3.1. What is Kubernetes
                          • ☰ 3.2. Kubernetes architecture
                            • ☰ 3.3. Control plane components
                              • ☰ 3.4. Worker node components
                                • ☰ 3.5. Kubernetes objects and resources
                                  • ☰ 3.6. Declarative configuration model
                                  • ☰ 4. OpenShift Architecture
                                    • ☰ 4.1. Overview of OpenShift architecture
                                      • ☰ 4.2. Control plane in OpenShift
                                        • ☰ 4.3. Nodes and machine roles
                                          • ☰ 4.4. OpenShift Operators
                                            • ☰ 4.5. OpenShift networking model
                                              • ☰ 4.6. OpenShift storage model
                                              • ☰ 5. OpenShift Installation and Deployment Models
                                                • ☰ 5.1. OpenShift deployment options
                                                  • ☰ 5.2. Installer-Provisioned Infrastructure
                                                    • ☰ 5.3. User-Provisioned Infrastructure
                                                      • ☰ 5.4. Managed OpenShift services
                                                        • ☰ 5.5. Single-node OpenShift
                                                          • ☰ 5.6. Cluster lifecycle management
                                                          • ☰ 6. Accessing and Using OpenShift
                                                            • ☰ 6.1. OpenShift web console
                                                              • ☰ 6.2. OpenShift CLI (oc)
                                                                • ☰ 6.3. Authentication and authorization
                                                                  • ☰ 6.4. Projects and namespaces
                                                                    • ☰ 6.5. Resource quotas and limits
                                                                    • ☰ 7. Building and Deploying Applications
                                                                      • ☰ 7.1. Application deployment concepts
                                                                        • ☰ 7.2. Source-to-Image (S2I)
                                                                          • ☰ 7.3. Container-based deployments
                                                                            • ☰ 7.4. DeploymentConfigs and Deployments
                                                                              • ☰ 7.5. Rolling updates and rollbacks
                                                                              • ☰ 8. Networking in OpenShift
                                                                                • ☰ 8.1. Services and service discovery
                                                                                  • ☰ 8.2. Routes and ingress
                                                                                    • ☰ 8.3. Network policies
                                                                                      • ☰ 8.4. Load balancing
                                                                                        • ☰ 8.5. External access to applications
                                                                                        • ☰ 9. Storage in OpenShift
                                                                                          • ☰ 9.1. Persistent storage concepts
                                                                                            • ☰ 9.2. Persistent Volumes
                                                                                              • ☰ 9.3. Persistent Volume Claims
                                                                                                • ☰ 9.4. StorageClasses
                                                                                                  • ☰ 9.5. Dynamic provisioning
                                                                                                    • ☰ 9.6. Stateful applications
                                                                                                    • ☰ 10. Configuration and Secrets Management
                                                                                                      • ☰ 10.1. ConfigMaps
                                                                                                        • ☰ 10.2. Secrets
                                                                                                          • ☰ 10.3. Environment variables
                                                                                                            • ☰ 10.4. Managing sensitive data
                                                                                                              • ☰ 10.5. Best practices for configuration
                                                                                                              • ☰ 11. Scaling and High Availability
                                                                                                                • ☰ 11.1. Horizontal pod autoscaling
                                                                                                                  • ☰ 11.2. Vertical scaling
                                                                                                                    • ☰ 11.3. Self-healing and pod restarts
                                                                                                                      • ☰ 11.4. High availability concepts
                                                                                                                        • ☰ 11.5. Multi-zone and multi-region clusters
                                                                                                                        • ☰ 12. Monitoring, Logging, and Observability
                                                                                                                          • ☰ 12.1. Built-in monitoring stack
                                                                                                                            • ☰ 12.2. Metrics and alerts
                                                                                                                              • ☰ 12.3. Logging architecture
                                                                                                                                • ☰ 12.4. Distributed tracing
                                                                                                                                  • ☰ 12.5. Troubleshooting applications
                                                                                                                                  • ☰ 13. Security in OpenShift
                                                                                                                                    • ☰ 13.1. Security model overview
                                                                                                                                      • ☰ 13.2. Role-Based Access Control
                                                                                                                                        • ☰ 13.3. Security Context Constraints
                                                                                                                                          • ☰ 13.4. Image security and scanning
                                                                                                                                            • ☰ 13.5. Network security
                                                                                                                                              • ☰ 13.6. Compliance and auditing
                                                                                                                                              • ☰ 14. CI/CD and DevOps with OpenShift
                                                                                                                                                • ☰ 14.1. DevOps concepts
                                                                                                                                                  • ☰ 14.2. CI/CD pipelines overview
                                                                                                                                                    • ☰ 14.3. OpenShift Pipelines (Tekton)
                                                                                                                                                      • ☰ 14.4. GitOps with Argo CD
                                                                                                                                                        • ☰ 14.5. Integrating OpenShift with external CI tools
                                                                                                                                                        • ☰ 15. Operators and Platform Services
                                                                                                                                                          • ☰ 15.1. What are Operators
                                                                                                                                                            • ☰ 15.2. Operator Lifecycle Manager
                                                                                                                                                              • ☰ 15.3. Installing and managing Operators
                                                                                                                                                                • ☰ 15.4. Common platform Operators
                                                                                                                                                                  • ☰ 15.5. Custom Operators
                                                                                                                                                                  • ☰ 16. Upgrades, Maintenance, and Operations
                                                                                                                                                                    • ☰ 16.1. OpenShift upgrade process
                                                                                                                                                                      • ☰ 16.2. Backup and restore
                                                                                                                                                                        • ☰ 16.3. Node maintenance
                                                                                                                                                                          • ☰ 16.4. Cluster troubleshooting
                                                                                                                                                                            • ☰ 16.5. Capacity planning
                                                                                                                                                                            • ☰ 17. OpenShift on HPC and Specialized Workloads
                                                                                                                                                                              • ☰ 17.1. Running batch workloads on OpenShift
                                                                                                                                                                                • ☰ 17.2. OpenShift and GPUs
                                                                                                                                                                                  • ☰ 17.3. MPI and parallel workloads in containers
                                                                                                                                                                                    • ☰ 17.4. Hybrid HPC and cloud workflows
                                                                                                                                                                                    • ☰ 18. OpenShift in Practice
                                                                                                                                                                                      • ☰ 18.1. Typical OpenShift workflows
                                                                                                                                                                                        • ☰ 18.2. Development to production lifecycle
                                                                                                                                                                                          • ☰ 18.3. Case studies from industry
                                                                                                                                                                                            • ☰ 18.4. Common pitfalls and best practices
                                                                                                                                                                                            • ☰ 19. Future Directions and Ecosystem
                                                                                                                                                                                              • ☰ 19.1. Kubernetes ecosystem overview
                                                                                                                                                                                                • ☰ 19.2. OpenShift roadmap
                                                                                                                                                                                                  • ☰ 19.3. Serverless and event-driven workloads
                                                                                                                                                                                                    • ☰ 19.4. AI and data platforms on OpenShift
                                                                                                                                                                                                    • ☰ 20. Final Project and Hands-On Exercises
                                                                                                                                                                                                      • ☰ 20.1. Deploying a containerized application
                                                                                                                                                                                                        • ☰ 20.2. Implementing CI/CD with OpenShift
                                                                                                                                                                                                          • ☰ 20.3. Securing and scaling an application
                                                                                                                                                                                                            • ☰ 20.4. Monitoring and troubleshooting report