Kubernetes is a portable, extensible, open-source platform for managing containerized workloads and services. It does not write an application or build its image. Its central job is to run described work across a group of machines and continuously move the actual state toward the desired state.
Imagine an online shop API whose team wants three copies running. One machine goes offline, leaving two. Kubernetes notices the difference and tries to create a replacement on an available machine. Success is not guaranteed: an invalid image, insufficient resources, or an application bug may still prevent the copy from running.
From a container to a cluster
A container runs an application as an isolated process together with the files and libraries it needs. It is not a complete virtual machine, and it does not decide where it should restart after a failure.
A node is a physical or virtual machine. Several nodes form a cluster, and Kubernetes distributes work among them.
Containers run inside Pods. A Pod is a Kubernetes object that groups one or more containers for a shared run. In this example, each Pod contains one API container, so three API copies mean three separate Pods.
The cluster’s control plane accepts resource descriptions and runs control processes. They repeatedly follow the same cycle: read the desired state, observe the actual state, find a difference, and try to correct it. This cycle is called reconciliation.
One example: three copies of an API
The running example uses a fictional image, example/shop-api:1.0. The team describes a Deployment, a resource that maintains a requested number of similar Pods:
apiVersion: apps/v1
kind: Deployment
metadata:
name: shop-api
spec:
replicas: 3
selector:
matchLabels:
app: shop-api
template:
metadata:
labels:
app: shop-api
spec:
containers:
- name: api
image: example/shop-api:1.0This is a manifest: a textual description of a Kubernetes object, usually written in YAML or JSON. apiVersion identifies an API version, while kind names the object type. replicas requests three copies. selector connects the Deployment to Pods carrying the app: shop-api label. template describes those Pods and their container image.
When manifest data is sent through the Kubernetes API, spec records the desired state. status, updated by the system, describes the observed state. Controllers try to reduce the difference. They can create a new Pod after one disappears, but they cannot repair application code, an invalid image, a missing dependency, or an incorrect intention in spec.
The example has matching selectors and labels, but it is not a production recipe. A real system separately designs CPU and memory requests, readiness checks, networking, access, storage, updates, observability, and recovery.
What Kubernetes provides—and its boundaries
Kubernetes can schedule Pods on nodes, maintain replica counts, perform controlled rollouts, provide mechanisms for service discovery and load balancing, and attach storage. These are platform building blocks, not a complete answer to every operational problem.
Kubernetes does not automatically build code or determine a continuous integration and delivery process. It does not include databases, queues, or a complete monitoring system as built-in application services. Such components can run on or integrate with Kubernetes, but they still need to be selected, configured, and operated.
Self-healing also has limits. Kubernetes can replace a failed container, but it cannot restore corrupted data or make incorrect software correct. Security still requires deliberate access control, networking, secret handling, updates, and audits.
Which platform should you consider?
| Option | Main task | Appropriate when |
|---|---|---|
| Docker Compose | Describe several container services in one YAML file and run them together | Development, learning, or a small application without a failure-tolerant cluster requirement |
| Docker Swarm | Maintain declaratively described services across Docker Engine nodes | A cluster and Docker-integrated management are needed without Kubernetes’ broader platform model |
| Nomad | Schedule containers, batch work, and some non-container workloads | Mixed workload types or a deliberate preference for a narrower orchestrator |
| Kubernetes | Manage containerized applications through an extensible API | A shared platform, automation, and extensibility are explicit needs and a team can operate them |
| Google Cloud Run | Run a service, one-off job, or background worker without owning a cluster | Fast delivery and low operational work matter, and the provider’s model and limits are acceptable |
This is not a universal ranking. Docker Compose and Docker Swarm are not merely smaller Kubernetes editions. Nomad has a narrower focus, while Google Cloud Run transfers more operational responsibility to a cloud provider. Start with the workload, failure requirements, required control, and the people who will operate the system.
When Kubernetes is unnecessary
Kubernetes is probably unnecessary for one small application on one machine, a simple internal service, or a learning project without a specific need for a cluster model.
It may also be unnecessary when a managed platform already supplies the required HTTPS endpoint and scaling, and the team does not need to own a cluster. If nobody owns updates, access, networking, observability, and recovery, self-managed Kubernetes introduces another risk.
Having many services is not sufficient justification by itself. There should be explicit requirements that warrant the complexity, such as a shared platform API, placement across many nodes, infrastructure control, or an extensible resource model.
Safe AI assistance
For learning, an agent may explain the model, create a requirements card, propose a plan, and write one file only inside an explicitly approved disposable folder. It receives no kubeconfig, tokens, secrets, production access, or permission to run kubectl, install packages, push, or deploy.
Inspecting an existing project is a different branch. The agent reads only an approved sanitized local copy, creates an inventory, and labels unknowns. It does not edit the project. A later experiment first requires a separate disposable copy and a separate approval of its boundaries.
After any permitted local action, a person reviews the diff, file list, and every field against official documentation. A confident agent response is not evidence. Cluster application, secret handling, and production remain outside this route.
What to remember
Kubernetes maintains a described state for containerized applications across a cluster. Its core model is not a rigid sequence of commands, but continuous reconciliation between desired and actual states.
Define the problem first, compare simpler options, and identify who will operate the platform. A first exercise needs only one manifest read or created in a disposable local folder without cluster access. You can then continue with the news article about how KYAML makes Kubernetes manifest notation more explicit.
Sources
Choose a platform and build a safe model with AI
This route needs no cluster. Learning happens in a disposable folder, while an existing project may only be inspected through a sanitized local copy.
Completed steps:0 / 0
I am learning in an empty local folderWork only with a fictional web application and no credentials.
Separate the application from its management system
Explain the relationship between an application, container, Pod, node, and cluster.
Boundaries, checks, and agent brief
Understand first
- Kubernetes neither writes code nor builds an image.
Safe context for the agent
- The running example in this article.
Allowed
- Explain terms and ask comprehension questions without commands.
Not allowed
- Request access to a device, repository, cloud account, or cluster.
Stop when
- You cannot distinguish a container, Pod, and node yourself.
How to verify
- Close the agent response and reproduce the diagram yourself.
Goal: Explain the relationship between an application, container, Pod, node, and cluster. Safe context for the agent: - The running example in this article. Allowed: - Explain terms and ask comprehension questions without commands. Not allowed: - Request access to a device, repository, cloud account, or cluster. Stop when: - You cannot distinguish a container, Pod, and node yourself. Expected artifact: A diagram: application → container → Pod → node → cluster. How to verify: - Close the agent response and reproduce the diagram yourself.
Inspect only fictional requirements
Collect the facts needed to select a platform.
Boundaries, checks, and agent brief
Understand first
- The choice depends on the task and its operating team.
Safe context for the agent
- A fictional service, load, acceptable downtime, and job types.
Allowed
- Create a requirements card and label unknowns.
Not allowed
- Read real configuration, .env files, logs, or secrets.
Stop when
- Continuing supposedly requires private data.
How to verify
- A person traces every requirement to the original description.
Goal: Collect the facts needed to select a platform. Safe context for the agent: - A fictional service, load, acceptable downtime, and job types. Allowed: - Create a requirements card and label unknowns. Not allowed: - Read real configuration, .env files, logs, or secrets. Stop when: - Continuing supposedly requires private data. Expected artifact: A requirements card with no real names or secrets. How to verify: - A person traces every requirement to the original description.
Choose the least complex sufficient option
Compare Compose, Swarm, Nomad, Kubernetes, and a managed platform.
Boundaries, checks, and agent brief
Understand first
- More control creates more operational responsibility.
Safe context for the agent
- The requirements card and this article's comparison table.
Allowed
- Propose an option, reasons, a risk, and unknowns.
Not allowed
- Declare Kubernetes the default winner or invent cost estimates.
Stop when
- The recommendation does not follow from the requirements.
How to verify
- The owner checks capabilities against the official sources.
Goal: Compare Compose, Swarm, Nomad, Kubernetes, and a managed platform. Safe context for the agent: - The requirements card and this article's comparison table. Allowed: - Propose an option, reasons, a risk, and unknowns. Not allowed: - Declare Kubernetes the default winner or invent cost estimates. Stop when: - The recommendation does not follow from the requirements. Expected artifact: A decision record with the choice, two reasons, one risk, and a review condition. How to verify: - The owner checks capabilities against the official sources.
Change only a disposable local copy
Create a learning Deployment without running Kubernetes.
Boundaries, checks, and agent brief
Understand first
- A manifest records intent but does not prove successful operation.
Safe context for the agent
- An absolute path to a new empty folder, a fictional name, and a learning image.
Allowed
- Create one deployment.yaml in the approved folder and show the full diff.
Not allowed
- Run kubectl, use the network, install software, push, migrate, or read kubeconfig.
Stop when
- The folder is not empty, the path is ambiguous, or real data appears.
How to verify
- A person checks every field against the plan and official example.
Goal: Create a learning Deployment without running Kubernetes. Safe context for the agent: - An absolute path to a new empty folder, a fictional name, and a learning image. Allowed: - Create one deployment.yaml in the approved folder and show the full diff. Not allowed: - Run kubectl, use the network, install software, push, migrate, or read kubeconfig. Stop when: - The folder is not empty, the path is ambiguous, or real data appears. Expected artifact: One local deployment.yaml and its full diff. How to verify: - A person checks every field against the plan and official example.
Verify the artifacts independently
Find extra files, fields, and unexplained values.
Boundaries, checks, and agent brief
Understand first
- The agent's answer is not evidence.
Safe context for the agent
- The plan, folder contents, and diff.
Allowed
- Read files and compare them with official documentation.
Not allowed
- Apply the resource or connect a cluster.
Stop when
- A field is unclear, an extra file exists, or a claim is unsupported.
How to verify
- Another person repeats the source-based check.
Goal: Find extra files, fields, and unexplained values. Safe context for the agent: - The plan, folder contents, and diff. Allowed: - Read files and compare them with official documentation. Not allowed: - Apply the resource or connect a cluster. Stop when: - A field is unclear, an extra file exists, or a claim is unsupported. Expected artifact: A list of checked fields and open questions. How to verify: - Another person repeats the source-based check.
Explain the decision in your own words
Demonstrate understanding of the benefit and complexity cost.
Boundaries, checks, and agent brief
Understand first
- Rejecting Kubernetes can be the correct decision.
Safe context for the agent
- The decision record, diff, and verification result.
Allowed
- Ask the agent to identify one contradiction with a specific source.
Not allowed
- Let the agent provide the final justification or perform a deployment.
Stop when
- It is unclear who would operate the platform.
How to verify
- Another reader maps each conclusion to a requirement and source.
Goal: Demonstrate understanding of the benefit and complexity cost. Safe context for the agent: - The decision record, diff, and verification result. Allowed: - Ask the agent to identify one contradiction with a specific source. Not allowed: - Let the agent provide the final justification or perform a deployment. Stop when: - It is unclear who would operate the platform. Expected artifact: Five original sentences covering problem, choice, benefit, cost, and next check. How to verify: - Another reader maps each conclusion to a requirement and source.
I am inspecting an existing projectUse only a sanitized local copy; this branch does not authorize project edits.
Define the inspection boundary
Separate file explanation from permission to change a system.
Boundaries, checks, and agent brief
Understand first
- Manifest files do not reveal the complete live state.
Safe context for the agent
- An approved list of local files containing no secrets.
Allowed
- Explain known fields.
Not allowed
- Request credentials or production access.
Stop when
- The file boundary is undefined.
How to verify
- The owner confirms the boundary; agent confirmation is insufficient.
Goal: Separate file explanation from permission to change a system. Safe context for the agent: - An approved list of local files containing no secrets. Allowed: - Explain known fields. Not allowed: - Request credentials or production access. Stop when: - The file boundary is undefined. Expected artifact: A map of permitted files and questions. How to verify: - The owner confirms the boundary; agent confirmation is insufficient.
Perform a read-only inspection
Identify resources, images, replicas, and unknown fields without changes.
Boundaries, checks, and agent brief
Understand first
- Inspection does not confirm cluster state.
Safe context for the agent
- A sanitized local copy of approved files.
Allowed
- Read those files and produce an inventory.
Not allowed
- Read .env, kubeconfig, tokens, logs, or other directories.
Stop when
- A secret, out-of-copy reference, or unknown generator is found.
How to verify
- A person manually compares the inventory with the files.
Goal: Identify resources, images, replicas, and unknown fields without changes. Safe context for the agent: - A sanitized local copy of approved files. Allowed: - Read those files and produce an inventory. Not allowed: - Read .env, kubeconfig, tokens, logs, or other directories. Stop when: - A secret, out-of-copy reference, or unknown generator is found. Expected artifact: A read-only inventory with paths and unknowns. How to verify: - A person manually compares the inventory with the files.
Prepare a plan without a patch
Describe a possible learning change and its verification criteria.
Boundaries, checks, and agent brief
Understand first
- A plan does not authorize project edits.
Safe context for the agent
- The checked inventory and repository rules.
Allowed
- Propose a separate disposable copy for a future experiment.
Not allowed
- Plan production work, upgrades, migrations, pushes, or secret handling.
Stop when
- There is no rollback through deleting the disposable copy.
How to verify
- The owner checks its scope and criteria.
Goal: Describe a possible learning change and its verification criteria. Safe context for the agent: - The checked inventory and repository rules. Allowed: - Propose a separate disposable copy for a future experiment. Not allowed: - Plan production work, upgrades, migrations, pushes, or secret handling. Stop when: - There is no rollback through deleting the disposable copy. Expected artifact: An unexecuted experiment plan. How to verify: - The owner checks its scope and criteria.
Preserve read-only operation
Record inspection results without changing the project.
Boundaries, checks, and agent brief
Understand first
- This branch does not authorize a patch.
Safe context for the agent
- The inventory and an approved notes folder outside the project.
Allowed
- Create only a local note in a separate disposable folder if its path is explicitly approved.
Not allowed
- Edit the project, run cluster commands, or install packages.
Stop when
- No separate folder is approved or an action touches the project.
How to verify
- The project diff and file list remain unchanged.
Goal: Record inspection results without changing the project. Safe context for the agent: - The inventory and an approved notes folder outside the project. Allowed: - Create only a local note in a separate disposable folder if its path is explicitly approved. Not allowed: - Edit the project, run cluster commands, or install packages. Stop when: - No separate folder is approved or an action touches the project. Expected artifact: A separate local note or, without write permission, a chat response. How to verify: - The project diff and file list remain unchanged.
Independently confirm that nothing changed
Ensure the agent neither changed the project nor accessed a cluster.
Boundaries, checks, and agent brief
Understand first
- The agent's statement is not verification.
Safe context for the agent
- The initial state, current diff, and local artifacts.
Allowed
- A person may review the diff and file list.
Not allowed
- Use cluster credentials for additional verification.
Stop when
- Any unapproved change appears.
How to verify
- A person or read-only CI check confirms the clean diff.
Goal: Ensure the agent neither changed the project nor accessed a cluster. Safe context for the agent: - The initial state, current diff, and local artifacts. Allowed: - A person may review the diff and file list. Not allowed: - Use cluster credentials for additional verification. Stop when: - Any unapproved change appears. Expected artifact: An independent record of a clean project or a deviation list. How to verify: - A person or read-only CI check confirms the clean diff.
Separate facts from inferences
Explain only what the local files demonstrate.
Boundaries, checks, and agent brief
Understand first
- Files do not prove the actual runtime state.
Safe context for the agent
- The checked inventory and independently reviewed diff.
Allowed
- Label facts, inferences, and unknowns separately.
Not allowed
- Claim that production is working or secure.
Stop when
- A conclusion would require live access.
How to verify
- The owner traces each fact to a specific local file.
Goal: Explain only what the local files demonstrate. Safe context for the agent: - The checked inventory and independently reviewed diff. Allowed: - Label facts, inferences, and unknowns separately. Not allowed: - Claim that production is working or secure. Stop when: - A conclusion would require live access. Expected artifact: A short report of facts, inferences, and next questions. How to verify: - The owner traces each fact to a specific local file.
Quick checklist
- Describe the problem before choosing Kubernetes or a simpler platform.
- Never give an AI agent a kubeconfig, tokens, secrets, or production-cluster access.
- Create a first manifest only for a fictional application in an empty learning folder.
- Do not run the manifest in a cluster until a person understands every field and the access boundaries.