kubectl basics

Getting started

On Kestrel, kubectl authenticates via OIDC using the kubelogin plugin, which you install and wire into your kubeconfig yourself — see Set up kubelogin. Once that’s done, if kubectl auth whoami shows your username and a Groups row containing oidc:<your-tenant>, you’re ready.

kubectl auth whoami

An empty kubectl get ns is not an error — Kestrel does not pre-create any namespaces for you, so a fresh tenant lists none until you create one.

Note

All commands below assume you’re working in a namespace you created under your tenant prefix. If you haven’t created one yet, see the first step of Your first deployment. Add -n <namespace> if your kubeconfig doesn’t set a default, or set one with kubectl config set-context --current --namespace=<namespace>.

Inspecting resources

get — list resources

kubectl get pods
kubectl get deployments
kubectl get services
kubectl get all

Useful flags:

Flag	Effect
-o wide	Show extra columns (node, IP)
-o yaml	Full YAML output
--show-labels	Append labels column
-w	Watch for changes in real time

describe — detailed view

describe shows events, conditions, and configuration in human-readable form. Use it when a Pod won’t start or a Service isn’t routing.

kubectl describe pod my-app-7b4f6d8c9-x2lkj
kubectl describe service my-app

The Events section at the bottom is where most debugging starts — it tells you about image pull failures, scheduling problems, and readiness probe failures.

logs — container output

kubectl logs my-app-7b4f6d8c9-x2lkj
kubectl logs -f my-app-7b4f6d8c9-x2lkj        # follow (tail -f)
kubectl logs my-app-7b4f6d8c9-x2lkj -c sidecar # specific container in a multi-container Pod
kubectl logs --previous my-app-7b4f6d8c9-x2lkj  # logs from the last crash

Tip

If a Pod keeps crash-looping, --previous shows the logs from the container that just died — invaluable for diagnosing startup failures.

Executing commands in a container

kubectl exec -it my-app-7b4f6d8c9-x2lkj -- /bin/sh

This opens an interactive shell inside the container. Use it for ad-hoc debugging — checking files, testing network connectivity, or running one-off commands.

kubectl exec my-app-7b4f6d8c9-x2lkj -- env          # print environment variables
kubectl exec my-app-7b4f6d8c9-x2lkj -- cat /etc/hosts # check DNS entries

Caution

Changes made via exec are ephemeral. The container filesystem resets when the Pod restarts. Don’t use exec to patch running production workloads.

Applying and deleting

apply — declarative create/update

kubectl apply -f deployment.yaml
kubectl apply -f k8s/        # apply every YAML file in a directory

apply is idempotent: run it again with the same manifest and nothing changes.

Note

On Kestrel, GitOps with ArgoCD is the supported way to manage resources, not direct kubectl apply. ArgoCD applications run with self-heal enabled, so a manually applied change is reverted to match Git. Use kubectl apply for one-off experiments and learning; commit anything you want to keep to a repo. See Bring your own repo.

delete — remove resources

kubectl delete -f deployment.yaml
kubectl delete pod my-app-7b4f6d8c9-x2lkj

Deleting a Pod managed by a Deployment just triggers a replacement. To stop the workload, delete the Deployment.

Quick reference

Task	Command
List Pods	kubectl get pods
Pod details + events	kubectl describe pod <name>
Follow logs	kubectl logs -f <pod>
Shell into a container	kubectl exec -it <pod> -- /bin/sh
Apply a manifest	kubectl apply -f <file>
Delete a resource	kubectl delete -f <file>
Scale a Deployment	kubectl scale deployment/<name> --replicas=N
Rollback a Deployment	kubectl rollout undo deployment/<name>
Check rollout status	kubectl rollout status deployment/<name>
Port-forward for local testing	kubectl port-forward svc/<name> 8080:80

Port forwarding

To test a Service locally without an Ingress:

kubectl port-forward svc/my-app 8080:80

Then open http://localhost:8080 in your browser. The tunnel stays open until you press Ctrl+C.

Next steps

• YAML editing patterns — manifest patterns and common pitfalls
• ArgoCD on Kestrel — how GitOps deploys replace manual kubectl apply