Kubernetes is a reconciliation system: you declare a desired state through the API, and controllers continuously work to make the cluster match it. This guide maps every major component to the request path you observe with kubectl.
1. Prepare and execute
Confirm the active kubeconfig context and namespace before applying changes. Save commands and manifests in version control without credentials.
kubectl cluster-info
kubectl get nodes -o wide
kubectl get --raw=/readyz?verbose
kubectl -n kube-system get pods -o wide
kubectl api-resources
2. Declarative configuration
Save the following example in a clearly named YAML file, review it, then use server-side dry-run when the API is available.
apiVersion: v1
kind: Pod
metadata:
name: architecture-demo
labels: {app: architecture-demo}
spec:
containers:
- name: web
image: nginx:1.28-alpine
ports: [{containerPort: 80}]
---
apiVersion: v1
kind: Service
metadata: {name: architecture-demo}
spec:
selector: {app: architecture-demo}
ports: [{port: 80, targetPort: 80}]
3. Verify the result
A successful command is not enough. Inspect resource state, conditions, events, endpoints, logs, and an end-to-end request where applicable.
kubectl apply -f architecture-demo.yaml
kubectl get pod,service,endpointslices -l app=architecture-demo
kubectl describe pod architecture-demo
kubectl run curl --rm -it --restart=Never --image=curlimages/curl:8.14.1 -- http://architecture-demo
4. Troubleshooting
If the Pod stays Pending, inspect scheduler events. If the Service has no endpoints, compare its selector with Pod labels. API failures belong to the control-plane path; application connection failures usually belong to workload, Service, DNS, or CNI layers.
5. Rollback and cleanup
Review the exact target before deleting resources, especially namespaces, claims, Secrets, and cluster-wide add-ons.
kubectl delete -f architecture-demo.yaml
Production checklist
- The active context, namespace, and target version were verified.
- Manifests passed client or server-side validation.
- Resource conditions and recent events show no unresolved error.
- Access, network exposure, resource limits, persistence, and rollback were reviewed.
- Commands and expected output were recorded for the operating team.
References: topic documentation and Kubernetes documentation.
