Simplify infrastructure self-service with Blueprints

→ Register for the webinar

Kubernetes

Kubectl cp – How to Copy File From Pod to Local (5 Examples)

kubectl cp

Spacelift and Kubernetes

Manage the challenges of Kubernetes with a GitOps flow, policies, and the ability to communicate between stacks from your choice of IaC tools.

Book a demo

In this article, we will look at the kubectl cp command, its definition, and syntax, before showing how to use it to perform practical everyday tasks, such as copying files from a pod to your local system. We will also take a look at some common errors associated with kubectl cp, explaining the common causes and how to go about troubleshooting them.

We will cover:

  1. What is the kubectl cp command
  2. How to use kubectl cp – examples
  3. Kubectl cp errors

What is the kubectl cp command

The kubectl cp  is a command-line utility in Kubernetes used to copy files and directories to and from a container in a Kubernetes pod. It allows you to transfer files between your local system and a running container within a pod without needing to set up additional tools or services.

kubectl cp is only available for pods running a compatible version of the K8S API server (v1.14+). It can be a convenient way to transfer files in and out of containers when needed for troubleshooting, debugging, or data exchange.

Command syntax

The example usage of the kubectl cp command is shown below:

kubectl cp <source> <destination> -n <namespace> <pod-name>:<path>
  • <source>: The source file or directory on your local system or in the container (use . to represent the current directory in the container).
  • <destination>: The destination on your local system or in the container.
  • -n <namespace>: Specifies the namespace in which the pod is running (optional).
  • <pod-name>: The name of the pod where you want to copy files.
  • <path>: The path within the container where you want to copy files or directories.

How to use kubectl cp — examples

Let’s look at some use case examples for the kubectl cp command.

Example 1 — Copying files from pod to local system

To copy files from a pod to the local system use:

kubectl cp -n <namespace> <pod-name>:<path> <destination-on-local-system>

For example, if you have a pod named “my-pod” in the “default” namespace and you want to copy a file named “file.txt” from the pod to your local system, you can use the following command:

kubectl cp -n default my-pod:/path/to/file.txt .

Note the . represents the current directory.

Example 2 — Copying files from local system to pod

Now, to copy files from the local system to a pod:

kubectl cp -n <namespace> <source> <pod-name>:<path>

For example, if you have a pod named “my-pod” in the “default” namespace and you want to copy a file named “file.txt” from your local system to the pod, you can use the following command:

kubectl cp -n default . my-pod:/path/to/file.txt

Example 3 — Copying files from a pod to a pod

To copy files from one pod to another pod in K8S using the kubectl cp command, you will need to copy the files to your local system as an intermediate step and then from your local system to the destination pod.

You can use the two examples above to achieve this.

Example 4 — Copying files from a pod in a specific namespace to local system

The -n option in the kubectl cp command is used to point out a specific namespace.

kubectl cp -n <namespace> <pod-name>:<path> <destination-on-local-system>

For example, if you have a pod named “my-pod” in the “test” namespace and you want to copy a file named “file.txt” from the pod to your local system, you can use the following command:

kubectl cp -n test my-pod:/path/to/file.txt .

Example 4 — Copying directories

Instead of specifying files to copy, you can also specify directories. For example, to copy a directory from your local system to a pod:

kubectl cp /path/to/local/directory <namespace>/<pod-name>:/path/in/pod

Example 5 — Copying from a specific container

You can also use kubectl cp to copy files between containers within the same pod.

kubectl cp -n <namespace> <pod-name>:<source-container>:<path> <destination-container>:<destination-path>

Kubectl cp errors

kubectl cp command errors can occur for various reasons, and troubleshooting them depends on the specific error message you encounter. Some common errors are described below.

Kubectl cp unexpected EOF error

The “unexpected EOF” error when using kubectl cp typically indicates that the kubectl cp command received an incomplete or unexpected response from the Kubernetes cluster. This can occur for various reasons but is commonly caused by network issues or unexpected interruptions in the transfer process.

How to fix it?

To resolve the issue, check the networking is configured correctly, that the cluster is healthy and responding correctly, and that the container and pod you are targeting are responding as expected. Also, check you have enough disk space available for the file transfer on the source and target.

Kubectl cp terminated with exit code 126

The “terminated with exit code 126” error when using kubectl cp usually indicates that the command failed because it was unable to find or execute a specific executable or script in the target container. Exit code 126 typically means “Permission denied”.

How to fix it?

To resolve the issue, check you have permissions on the file you’re trying to copy, that it is readable, or that the script you’re trying to run is executable. If the file or command you’re trying to access is not found in the specified path, you’ll encounter this error.

  • Double-check the paths and arguments in your kubectl cp command.
  • Verify that the file or command exists in the container.
  • Check the container is running and is responding correctly.
  • Also, check that the file you’re trying to copy or execute is in a compatible format with the container’s operating system. For example, a binary compiled for Linux won’t work in a Windows container.

Key points

The kubectl cp command can be used to transfer files and directories between your local machine and pods, or between pods running on your K8S cluster.

We encourage you to also check out how Spacelift helps you manage the complexities and compliance challenges of using Kubernetes. Anything that can be run via kubectl can be run within a Spacelift stack. Find out more about how Spacelift works with Kubernetes, and get started on your journey by creating a free trial account.

Manage Kubernetes Easier and Faster

Spacelift allows you to automate, audit, secure, and continuously deliver your infrastructure. It helps overcome common state management issues and adds several must-have features for infrastructure management.

Start free trial

The Practitioner’s Guide to Scaling Infrastructure as Code

Transform your IaC management to scale

securely, efficiently, and productively

into the future.

ebook global banner
Share your data and download the guide