# kubectl create namespace: Usage, Options & Common CI Errors

> kubectl create namespace makes a namespace for isolated CI environments. The idempotent create-or-apply pattern and the AlreadyExists re-run error.

Source: https://latchkey.dev/learn/command-reference/kubectl-create-namespace  
Updated: 2026-06-25

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

```Terminal
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 teardown
```

## Common 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.

```Terminal
# 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl create namespace: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt