kubectl Documentation

Maintainers should routinely monitor newly filed issues in the Kubectl repo and the Kubernetes repo to identify regressions and manage the backlog.

When triaging, categorize issues as follows:

• Requests for help: Answer and close if simple.
• Regressions and bugs: Identify the root cause and triage severity. Note that issues occurring only in old versions are considered less severe.
• Simple issues for new contributors: Label with for-new-contributors, assign a priority, and ensure they are small, well-scoped, and located in areas with minimal technical debt and strong ownership.
• Feature requests: Either close with an explanation (e.g., "Don't have capacity right now, try reopening in 6 months") or label them with a priority.

The kubectl run command creates and runs a particular image in a pod. It is a high-level command used to quickly spin up containers for testing or running specific tasks on the cluster.

Usage Syntax: kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client] [--overrides=inline-json] [--command] -- [COMMAND] [args...]

# Start a nginx pod
kubectl run nginx --image=nginx

# Start a hazelcast pod and let the container expose port 5701
kubectl run hazelcast --image=hazelcast/hazelcast --port=5701

# Start a hazelcast pod and set environment variables
kubectl run hazelcast --image=hazelcast/hazelcast --env="DNS_DOMAIN=cluster" --env="POD_NAMESPACE=default"

# Start a hazelcast pod and set labels
kubectl run hazelcast --image=hazelcast/hazelcast --labels="app=hazelcast,env=prod"

# Dry run; print the corresponding API objects without creating them
kubectl run nginx --image=nginx --dry-run=client

# Start a nginx pod, but overload the spec with a partial set of values parsed from JSON
kubectl run nginx --image=nginx --overrides='{ "apiVersion": "v1", "spec": { ... } }'

# Start a busybox pod and keep it in the foreground, don't restart it if it exits
kubectl run -i -t busybox --image=busybox --restart=Never

# Start the nginx pod using the default command, but use custom arguments
kubectl run nginx --image=nginx -- <arg1> <arg2> ... <argN>

# Start the nginx pod using a different command and custom arguments
kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>

Use selectors and resource types to fetch logs from groups of pods:

• By Label Selector: Use -l <selector> to target pods matching specific labels. When using --all-pods=true, the output automatically enables --prefix to distinguish between sources.
• By Resource Type: You can target other resource types like deployment/name or job/name to get logs from the pods they manage.
• Concurrency Control: When following logs from multiple pods via a selector, use --max-log-requests=<number> to limit concurrent log requests (default is 5).

# Return snapshot logs from all pods in the deployment nginx
kubectl logs deployment/nginx --all-pods=true

# Return snapshot logs from all containers in pods defined by label app=nginx
kubectl logs -l app=nginx --all-containers=true

# Return snapshot logs from all pods defined by label app=nginx, limiting concurrent log requests to 10 pods
kubectl logs -l app=nginx --max-log-requests=10

# Return snapshot logs from first container of a job named hello
kubectl logs job/hello

The kubectl logs command prints the logs for a container in a pod or a specified resource. If the pod contains only one container, the container name is optional.

Usage Syntax: kubectl logs [-f] [-p] (POD | TYPE/NAME) [-c CONTAINER]

Common Tasks:

• Single container logs: kubectl logs <pod-name>
• Specific container logs: kubectl logs <pod-name> -c <container-name>
• Previous container logs: Use -p to see logs from a previously terminated instance of the container.
• Stream logs: Use -f to follow the log stream.
• All containers in a pod: Use --all-containers=true to retrieve logs from every container in the pod.

# Return snapshot logs from pod nginx with only one container
kubectl logs nginx

# Return snapshot logs of the ruby container in pod web-1
kubectl logs -f -c ruby web-1

# Return snapshot of previous terminated ruby container logs from pod web-1
kubectl logs -p -c ruby web-1

The kubectl cp command allows you to copy files and directories between your local filesystem and a container within a pod.

Important Requirements:

• The tar binary must be present in the container image. If tar is missing, kubectl cp will fail.
• For advanced use cases like symlinks, wildcard expansion, or preserving file modes, consider using kubectl exec with tar manually.

File Specification Format: Paths must follow the canonical format: [[namespace/]pod:]file/path.

Common Usage Patterns:

• Local to Pod: kubectl cp <local-path> <pod-name>:<remote-path>
• Pod to Local: kubectl cp <pod-name>:<remote-path> <local-path>
• Specifying Namespace: kubectl cp <local-path> <namespace>/<pod-name>:<remote-path>
• Specifying Container: kubectl cp <local-path> <pod-name>:<remote-path> -c <container-name>

# Copy /tmp/foo_dir local directory to /tmp/bar_dir in the default namespace
kubectl cp /tmp/foo_dir <some-pod>:/tmp/bar_dir

# Copy /tmp/foo local file to /tmp/bar in a remote pod in a specific container
kubectl cp /tmp/foo <some-pod>:/tmp/bar -c <specific-container>

# Copy /tmp/foo local file to /tmp/bar in a remote pod in namespace <some-namespace>
kubectl cp /tmp/foo <some-namespace>/<some-pod>:/tmp/bar

# Copy /tmp/foo from a remote pod to /tmp/bar locally
kubectl cp <some-namespace>/<some-pod>:/tmp/foo /tmp/bar