Onboarding Basics

This page is the day-one path for a new app developer: get authenticated kubectl access, find your namespace, and ship the golden-path template to staging.

Each example is a small, real step you can run in order on your first morning.

Prerequisites

• kubectl matching the cluster minor (client within one minor of Kubernetes 1.36.2).
• Cluster access configured by the platform team via OIDC (your kubeconfig context is provided, not self-issued).
• helm (Helm 3) and git installed locally.
• Docker Engine 29.6.1 (Compose v2) for local builds only - the cluster runs containerd, not Docker.

Quick install on macOS:

brew install kubectl helm
kubectl version --client
helm version --short

Basic Examples

1. Confirm which cluster and context you are on

Never run a command until you know where it lands.

kubectl config current-context
kubectl config get-contexts

• current-context prints the active cluster; read it out loud before mutating anything.
• New developers get a staging context first; production is added later, if at all.
• If the context is wrong, switch with kubectl config use-context <name>.
• Treat a production context as read-only until training is complete.

2. Find your namespace and set it as default

Your team owns one namespace; work there, not in default.

kubectl get namespaces --show-labels
kubectl config set-context --current --namespace=team-payments

• Setting the namespace on your context means you can drop -n team-payments from every command.
• The --show-labels output reveals Pod Security enforcement, such as pod-security.kubernetes.io/enforce=restricted.
• You will get "Forbidden" if you try to list resources in a namespace you do not own - that is expected.

3. Check what you are allowed to do

RBAC decides your verbs; kubectl auth can-i tells you before you try.

kubectl auth can-i create deployments -n team-payments
kubectl auth can-i delete nodes

• The first should return yes; the second should return no.
• Run kubectl auth can-i --list -n team-payments to see your full permission set.
• If a command is denied, that is a policy boundary, not a bug - open a request rather than escalating locally.

4. Read running workloads and their health

Observing before changing is the core habit of a cluster-safe developer.

kubectl get deploy,pods -n team-payments
kubectl describe pod <pod-name> -n team-payments

• get shows desired vs ready replicas; a mismatch means something is wrong.
• describe surfaces events at the bottom - image pull errors, failed probes, and scheduling problems.
• Bookmark these two commands; they answer most "is it up?" questions.

5. Tail logs from a workload

Logs are your first debugging tool and are usually granted on day one.

kubectl logs -f deploy/checkout -n team-payments
kubectl logs -f deploy/checkout --previous -n team-payments

• -f follows the stream; --previous shows the last crashed container's logs.
• For multi-container Pods, add -c <container> to pick the right one.
• If logs are empty, the container may be crash-looping before it writes - check describe events.

6. Deploy the golden-path template to staging

The golden path is a pre-approved Helm chart that already sets probes, resources, and security context.

git clone https://git.internal/golden-path/service-chart
helm upgrade --install checkout ./service-chart \
  --namespace team-payments \
  --set image.repository=registry.internal/checkout \
  --set image.tag=1.4.0

• You supply your image and a few values; the chart supplies the safe defaults.
• Using the template means you inherit non-root, resource limits, and readiness probes without writing them.
• This is the sanctioned way to ship - hand-written manifests are for learning, not day-one production.

7. Roll back when a deploy goes wrong

Every deploy must be reversible, and the golden path makes rollback one command.

helm history checkout -n team-payments
helm rollback checkout 1 -n team-payments

• helm history lists revisions; pick the last known-good number.
• Rollback re-applies the previous release atomically.
• Knowing how to undo is a prerequisite for being trusted with self-service deploys.

Intermediate Examples

8. Port-forward to test a service without exposing it

You can reach a service privately without an ingress or public URL.

kubectl port-forward svc/checkout 8080:80 -n team-payments
curl localhost:8080/healthz

• This tunnels a local port to the in-cluster service for quick verification.
• Nothing is exposed publicly, so it is safe for testing pre-release changes.
• The forward stops when you close the terminal; it is not a deployment mechanism.

9. Diff your change before you apply it

Preview what a manifest change will do before it touches the cluster.

kubectl diff -f deployment.yaml -n team-payments

• diff renders the exact fields that would change, additions in one column and removals in another.
• Run it in code review to reason about a manifest PR without merging it.
• A surprising diff is a signal to stop and ask, not to apply.

10. Open a manifest PR instead of applying to prod

For production, you do not run apply; you open a pull request that GitOps reconciles.

git checkout -b bump-checkout-1.4.0
# edit apps/checkout/deployment.yaml to set the new image tag
git commit -am "checkout: bump to 1.4.0"
git push origin bump-checkout-1.4.0

• Argo CD watches the repo and syncs the merged state into the cluster.
• Your write access to production is code review plus merge, not direct kubectl.
• This keeps every production change reviewed, auditable, and revertible via Git.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).