Skip to content

Kubernetes playground ​

Documentation · Kubernetes

Practice with disposable workloads in an existing cluster. Run commands from a Plous checkout. The packaged application does not include the playground script.

Start with Investigate a restarting Pod for a guided exercise. Argo CD and Flux use a separate playground.

Before starting ​

You need Python 3.9+, Helm 3.13+ or Helm 4, kubectl, and a disposable Kubernetes 1.26+ cluster. Use a default StorageClass or supply --storage-class NAME. Images and charts need network access.

Examples use the exact context minikube. Every operation requires --context. Add --kubeconfig PATH for another file. The script does not change active contexts or saved Helm repositories.

Reserve plous-demo, plous-failures, plous-cert-manager, plous-ingress, plous-metrics, and plous-list-a through plous-list-c. Reset and cleanup delete their contents, including PVCs. The script refuses namespaces without its ownership label and unexpected releases.

Install ​

Use plan to inspect the selection without cluster access or downloads. Use setup for healthy workloads, and add --failures all for broken examples.

sh
# Preview locally
python3 scripts/playground.py plan --context minikube --failures all

# Install healthy examples
python3 scripts/playground.py setup --context minikube

# Include deliberate failures
python3 scripts/playground.py setup --context minikube --failures all

Healthy releases wait up to five minutes each. Deliberate failures do not wait for readiness. Use --timeout-seconds 600 for slow provisioning.

Repeating setup updates the releases. The failure list replaces the old selection. Setup without --failures removes previous failure fixtures. Reapply optional flags when updating or resetting.

What to explore ​

In Plous, select the cluster, press 22, and choose namespace plous-demo.

ResourceTry this
frontend-podinfo and backend-podinfo DeploymentsFollow Related links through ReplicaSets, Pods, and Services. Scale or restart the frontend.
log-lab DeploymentOpen Logs. The sh container emits continuous messages, Unicode, long lines, and sample errors. Search, select, copy, hold your position, and jump live.
log-lab containersChoose prepare for completed init logs, bash for another stream, or no-shell for an image without an interactive shell.
log-lab ExecUse /bin/sh in sh. For bash, choose Custom command and enter /usr/local/bin/bash. Try either shell in no-shell to inspect launch failure and explicit retry.
playground-config ConfigMapOpen YAML and search the 100 example entries. Edit a value and save with :w. Optionally preview the diff with :v first.
playground-credentials SecretPractice reveal, value inspection, and editing with a dummy password.
store StatefulSetFollow its headless Service, Pod, PVC, and PV. The container writes a counter to its 128 MiB volume and serves it over HTTP. Restart and inspect the continuing counter.
node-reporter DaemonSetInspect the Pod on each eligible node and its logs.
completed-example JobInspect successful completion and retained logs.
periodic-report CronJobWait for the five-minute schedule and follow its Job/Pod relationships. History is limited to one successful and one failed Job.
playground-observer ServiceAccount, Role, RoleBindingInspect read permissions. Its Role omits Secrets, Exec, and writes. Generate its separate kubeconfig with the credentials action below. Adding the fixture does not change your identity.
LimitRange, ResourceQuota, NetworkPolicy, frontend PDBInspect defaults, limits, selectors, and disruption settings. The sample NetworkPolicy allows traffic and does not test enforcement.
sh
i=0; while [ "$i" -lt 500 ]; do echo "review example $i"; i=$((i + 1)); done

In Exec, Ctrl+] opens output review and Ctrl+C exits Plous. The loop above provides scrollback practice.

For an edit conflict, keep a modified ConfigMap draft open and change the same object from another terminal. Saving should report the conflict and keep your draft.

Select failure cases ​

Choose failures by comma-separated names, then inspect namespace plous-failures. Allow time for backoff states to appear.

sh
python3 scripts/playground.py setup --context minikube --failures crash,readiness,storage
NameObjectExpected result
crashbroken-crash PodRepeated exits, then CrashLoopBackOff. Previous-run logs contain the example error.
imagebroken-image PodImagePullBackOff for an intentionally nonexistent image tag.
readinessbroken-readiness Pod and ServiceRunning but unready. Service endpoints report no ready backend.
schedulingbroken-scheduling PodPending because no node matches the deliberately missing label.
configbroken-config PodCreateContainerConfigError for a missing ConfigMap.
storagebroken-storage Pod and PVCPending because the requested StorageClass does not exist.
initbroken-init PodA failing init container prevents the application container from starting.
jobbroken-job JobA failed Pod and Job with retries disabled.

These fixtures have resource limits and do not deliberately exhaust node memory or disk.

Add custom resources and TLS examples ​

This adds cert-manager, a self-signed Issuer, a Certificate, and a generated TLS Secret. The certificate is for local testing and is not publicly trusted.

sh
python3 scripts/playground.py setup --context minikube --failures all --with-cert-manager

Press g in a resource table to discover the new APIs.

Do not use this option with an unrelated cert-manager installation. It installs cluster-wide CRDs, RBAC, and webhooks. Cleanup removes its CRDs and refuses if cert-manager objects exist outside plous-demo.

Extended playground ​

Add ingress, metrics, autoscaling, rollout examples, and 300 ConfigMaps:

sh
python3 scripts/playground.py setup --context minikube \
  --failures all --with-cert-manager --with-traefik \
  --with-metrics-server --with-rollout --list-count 100 \
  --timeout-seconds 600

Reapply the same flags when updating. Omitting HPA, rollout, or list flags removes those examples. Installed controllers stay until cleanup.

Traefik watches plous-demo, uses the non-default plous-playground IngressClass, and exposes an internal Service. It does not install Traefik CRDs or expose its dashboard.

The metrics-server option skips kubelet certificate verification for disposable clusters. It does not change kubeconfig. Setup refuses unrelated metrics API registrations or IngressClass ownership.

--list-count accepts 0–500 ConfigMaps per namespace and starts no Pods.

Follow an ingress route ​

Open the frontend Ingress in plous-demo. Follow its class, route, TLS Secret, and Service.

For a local request, keep the port-forward command running in another terminal. The curl commands use the playground hostname without changing DNS.

sh
kubectl --context minikube -n plous-ingress port-forward service/plous-ingress 8080:80 8443:443
sh
curl -H 'Host: plous.local' http://127.0.0.1:8080/
curl --insecure --resolve plous.local:8443:127.0.0.1 https://plous.local:8443/

HTTPS uses the self-signed sample certificate. Stop port forwarding when finished.

Exercise autoscaling ​

Start a fixed-duration load Job:

sh
python3 scripts/playground.py load --context minikube --load-seconds 180

The Job uses eight workers with a combined half-CPU limit. Duration accepts 30–600 seconds. Only one load Job can run at a time. Finished Jobs expire after ten minutes.

Watch frontend-podinfo in HorizontalPodAutoscalers, Deployments, and Pods. Its HPA targets 70% CPU and at most three replicas. Scaling depends on measured load and is not guaranteed. Scale-down can take several minutes.

Open workload or Pod Describe to collect metrics. I inspects charts, W changes the window, and P follows latest. See chart meanings.

Add a restricted connection ​

Create a separate read-only kubeconfig:

sh
python3 scripts/playground.py credentials --context minikube \
  --output .local/playground/minikube-observer.kubeconfig

The private file contains a minikube-plous-observer context and a temporary ServiceAccount token. The script requests 24 hours and prints the granted expiry, without printing the token or copying administrator credentials.

Add that file in Plous, refresh contexts, and choose plous-demo. The identity can read the example workloads and logs, but not Secrets, Exec, writes, all namespaces, or namespace lists. Enter plous-demo manually if namespace discovery fails.

Rerun to renew. Only files marked for the same source context are replaced. Keep .local out of source control. Cleanup invalidates the token by deleting its ServiceAccount but leaves the local file.

Break and recover a rollout ​

Use rollout-break to set a missing image on rollout-lab. Inspect its ReplicaSet, Pod, and conditions. Use rollout-recover to restore the recorded image.

sh
python3 scripts/playground.py rollout-break --context minikube
sh
python3 scripts/playground.py rollout-recover --context minikube

The two healthy replicas stay available. The failure deadline is 45 seconds, though controller status can arrive later. These commands leave the frontend unchanged. Setup also restores the healthy chart image.

Exercise validation and concurrent edits ​

Edit playground-config in Plous and leave its draft open. Run this in another terminal:

sh
python3 scripts/playground.py edit-conflict --context minikube

The command adds data.concurrent-edit without replacing other data. Return to Plous and validate or save to inspect the conflict.

Also try malformed YAML, an object where a ConfigMap string is required, or an immutable Deployment selector change. Read the error, then correct or discard the draft.

Use existing metrics and ingress controllers ​

For an existing Minikube metrics-server, enable its addon if needed and use --with-hpa. For an existing ingress controller, supply its class with --ingress-class.

sh
minikube -p minikube addons enable metrics-server
python3 scripts/playground.py setup --context minikube --with-hpa
sh
python3 scripts/playground.py setup --context minikube --ingress-class traefik --with-cert-manager

--with-hpa checks the Metrics API before installation. The HPA may override manual replica changes.

--ingress-class does not install a controller, change DNS, or start a tunnel. The playground does not install Prometheus or Grafana.

Status, reset, and cleanup ​

status reads resources. reset removes the owned playground and reinstalls the requested selection. cleanup removes the owned releases and namespaces.

sh
python3 scripts/playground.py status --context minikube
python3 scripts/playground.py reset --context minikube --failures all --with-cert-manager
python3 scripts/playground.py cleanup --context minikube

Use the same extended flags with reset to recreate that selection.

Cleanup removes sample certificates before cert-manager. It refuses to remove metrics-server while outside HPAs exist, or Traefik while outside Ingresses use its class. It leaves the cluster, addons, and unrelated namespaces intact.

PVC deletion follows the StorageClass reclaim policy. Retain can leave PVs and storage behind. Cleanup does not bypass finalizers or force storage removal. Inspect terminating resources before retrying a timed-out cleanup.

Render and verify locally ​

The fixtures and version pins define these examples.

Render the local chart and run offline checks:

sh
python3 scripts/playground.py render --failures all --with-cert-manager > /tmp/plous-playground.yaml
make test-playground

Render prints only the local fixture chart. It does not download upstream charts or contact Kubernetes.

Tests use fake CLIs and temporary storage. With Helm installed, they also lint and render. They do not verify a live deployment. See the separate Minikube acceptance tests.