Desired State

Desired state is a recorded target against which a system reconciles observed conditions. In Kubernetes, a Deployment’s current spec describes its target; controllers act on that API object. A file in a repository is a separate source and needs a process that keeps the API object synchronized with it.

Intent and observation

Many Kubernetes resources, including Deployments, separate intent and observation into two fields.

• spec describes the target, such as replica count and Pod template. Users or authorized controllers may change it.
• status records component observations, such as available replicas, observed generation, and conditions. It can lag the latest request.

The relevant controller must be present, healthy, and able to act. Storing a resource does not establish those conditions: a custom resource can exist without a controller.

For a Deployment requesting three replicas, the Deployment and ReplicaSet controllers can create a replacement when a managed Pod is lost. Scheduling, image access, and application startup still have to succeed. This repairs a dependent resource while its owning declaration remains.

Submitting a target and observing its result

A command may submit work or wait for an outcome. Inspect its contract rather than inferring completion from whether the interface is imperative or declarative.

	Imperative command	Declared desired state
Purpose	Request an operation	Record a target for reconciliation
Completion	Depends on whether the command waits	Individual rollouts and Jobs have observable outcomes
Failure	May be immediate or asynchronous	May appear in API errors, status, events, or a waiting command
Repetition	Depends on operation identity and effects	Depends on object identity, current state, and field management
Later changes	Observation requires configured monitoring	Controllers reconcile their managed scope against the current target

A repeated declaration can leave an unchanged object unchanged, but safe repetition is not guaranteed by syntax. Reapplying after deletion may create a new object; another writer’s changes can be overwritten or cause conflicts. External effects need their own idempotency contract. Replaying an older declaration can also restore obsolete intent.

A request, not a guarantee

Validation, admission, authorization, or quota can reject a request. An accepted Pod can still remain unscheduled because no node meets its requirements. Check Pod conditions and scheduler events for the reason; accepted intent is not proof that execution is feasible.

A Deployment reports stalled progress with Progressing=False and reason ProgressDeadlineExceeded after its progress deadline, which defaults to 600 seconds. Earlier conditions and events can already expose failure. The deadline concerns stalled progress, not total rollout time; pause and completion affect its evaluation. kubectl rollout status can wait and return success or failure for a rollout.

The Deployment stall condition does not automatically stop or revert it. A recovery policy must decide whether to repair, pause, or perform rollback. A Job has a different lifecycle and can reach a terminal Complete or Failed condition.

Monitor completion and continuing health

Confirm the intended rollout’s generation and revision, then keep observing its running behavior. Two useful signals complement that completion check:

1. Progress toward the target. Use resource-specific conditions and replica counts, with observedGeneration where available; spec and status are not interchangeable schemas.
2. Impact and duration. A progress gap can be temporary, but a severe failure may need immediate action. Choose thresholds from the service’s SLO and risk rather than treating age as the only signal. A twenty-minute threshold is an example, not a general rule.

The cluster need not settle permanently for a particular workload to meet its target. A control loop can keep reconciling after a rollout completes. Conversely, a busy loop can repeatedly fail; activity alone is not evidence of health.

Continuous enforcement or point-in-time comparison

Terraform normally refreshes live managed resources before planning against configuration and its infrastructure state file. Whether configuration drift is checked between runs depends on scheduled or service-managed automation. The wider infrastructure as code practice must define that observation and response policy.

Kubernetes normally reconciles against current API intent. A manual edit to a Deployment’s replicas can become the new target rather than being undone. Restoring a repository baseline needs a later apply or a separate synchronization controller. Similarly, deleting a top-level Deployment does not make it recreate itself unless another owner or synchronizer restores it.

For any declarative system, identify the source of intent, the reconciler’s scope, completion and failure signals, and the contract for repeated effects. These vary by resource and implementation; declaring a target does not settle them.

References

• Kubernetes: Objects In Kubernetes
• Controllers
• Deployments
• Kubernetes Scheduler
• kubectl rollout status
• Kubernetes Jobs
• Debug Pods
• Declarative Management of Kubernetes Objects
• Server-Side Apply
• Custom Resources
• Terraform plan