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

> kubectl create deployment scaffolds a Deployment from an image. Replicas and port flags, generating YAML to commit, and the AlreadyExists re-run error.

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

Stand up a Deployment from an image in one line.

kubectl create deployment makes a Deployment from an image without a manifest. It is handy for a quick preview environment and, with --dry-run, for scaffolding a real Deployment YAML to commit.

## What it does

kubectl create deployment NAME --image=IMG creates a Deployment managing one replica by default; --replicas sets the count and --port declares a container port. Add --dry-run=client -o yaml to print the manifest instead of creating it - the canonical scaffold workflow.

## Common usage

```Terminal
kubectl create deployment web --image=nginx:1.27
kubectl create deployment web --image=nginx:1.27 --replicas=3 --port=80
kubectl create deployment web --image=nginx --dry-run=client -o yaml > deploy.yaml
kubectl expose deployment web --port=80           # add a Service
```

## Common errors in CI

"AlreadyExists" on re-run is the usual failure - for declarative, idempotent deploys commit the scaffolded YAML and use kubectl apply -f instead. create deployment exposes only a few flags, so for anything beyond image/replicas/port (env, resources, probes) you must scaffold YAML and edit it, or follow up with kubectl set. The created Deployment is not reachable until you add a Service (kubectl expose), and create deployment does not wait for pods to be Ready - gate with kubectl rollout status.

## 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 deployment: Usage, Options & Common CI Errors?

kubectl create deployment makes a Deployment from an image without a manifest. It is handy for a quick preview environment and, with --dry-run, for scaffolding a real Deployment YAML to commit.

### What it does?

kubectl create deployment NAME --image=IMG creates a Deployment managing one replica by default; --replicas sets the count and --port declares a container port. Add --dry-run=client -o yaml to print the manifest instead of creating it - the canonical scaffold workflow.

### Common errors in CI?

"AlreadyExists" on re-run is the usual failure - for declarative, idempotent deploys commit the scaffolded YAML and use kubectl apply -f instead. create deployment exposes only a few flags, so for anything beyond image/replicas/port (env, resources, probes) you must scaffold YAML and edit it, or follow up with kubectl set.

---

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