kubectl create namespace: Usage, Options & Common CI Errors
Carve out an isolated namespace per branch or PR build.
kubectl create namespace makes a fresh namespace, the standard unit of isolation for an ephemeral CI environment. One namespace per PR or branch keeps test workloads and teardown cleanly separated.
What it does
kubectl create namespace NAME creates an empty namespace. Subsequent apply/create commands target it via -n NAME or by pinning it as the context default. Deleting the namespace cascades to everything inside it, which makes it the cleanest teardown primitive.
Common usage
kubectl create namespace pr-${PR_NUMBER}
kubectl create namespace ci --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -n pr-${PR_NUMBER} -f manifests/
kubectl delete namespace pr-${PR_NUMBER} # cascading teardownCommon errors in CI
"AlreadyExists" on re-run is the trap - make it idempotent with kubectl create namespace ci --dry-run=client -o yaml | kubectl apply -f -, or guard with kubectl get namespace ci. Namespace names must be a DNS label (lowercase alphanumeric and -, ≤63 chars), so a branch name with slashes or uppercase fails "Invalid value" - sanitize it. Deleting a namespace can hang in Terminating if a contained resource has a stuck finalizer; that is the namespace-stuck-terminating problem, not a create issue, but it blocks recreating a same-named namespace until it clears.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes