1. Introduction

In this tutorial, we’ll explore how to make copies between different Kubernetes pods. Firstly, we’ll understand the kubectl cp command. Then, we’ll see how it works in practice through some examples.

2. Understanding the kubectl cp Command

The kubectl cp command is a utility Kubernetes provides to copy files and directories between the local file system and Kubernetes pods. The syntax required to use the command is:

$ kubectl cp <file-spec-src> <file-spec-dest>

Here, and can either be local file paths or remote paths. The source and destination of the file determine the order specified. If we want to make a local-to-remote copy, the first path entered is the local one, and then the information for the remote path. To simplify things in this article, we’re only going to study copying a remote file to a local place:

$ kubectl cp <some-pod>:<some-dir-remote> <some-dir-local>

We need some basic information to make the copy correctly. The first information is the pod’s name where the source file resides (). Next is the source path of the file in the pod that we wish to copy (). Finally, we need the path in the directory of the local machine to which we want to copy the file ().

In cases where a pod has multiple containers, Kubernetes searches for the path specified in the first container of the pod by default. To designate the container, one can use the -c flag:

$ kubectl cp <some-pod>:<some-dir-remote> <some-dir-local> -c <specific-container>

Finally, if the pod that holds the file for copying is running in a specific namespace, the namespace must be in the source path:

$ kubectl cp <some-namespace>/<some-pod>:<some-dir-remote> <some-dir-local>

To ensure the valid execution of the copies, we need the correct access permissions for the Kubernetes resources and the files we’re copying. If necessary, check the role-based access control settings.

3. Examples

Now that we understand how the kubectl cp command functions, let’s see how it works in practice.

In the first example, we’ll copy the configuration file of an Nginx service that’s running on a remote pod and in the same namespace (default). To create a copy, we need the full path and filename of the remote file. Here, the file is in its default directory:

$ kubectl cp nginx:etc/nginx/nginx.conf /home/user/nginx/nginx.conf
$ ls nginx/
nginx.conf

After successfully executing the cp command, no output is generated. We can use the ls command to verify that the file transferred to the local directory correctly.

It’s important to note that the command requires the name and destination path of the file to know how to allocate it correctly:

$ kubectl cp nginx:etc/nginx/nginx.conf .
error: open .: is a directory

In a second example, we’ll study cases where we’d like to copy files between different namespaces. Therefore, we need to know which namespaces exist in the environment:

$ kubectl get namespaces
NAME              STATUS   AGE
default           Active   104d
kube-node-lease   Active   104d
kube-public       Active   104d
kube-system       Active   104d
multi-services    Active   55s

We’re currently in the default namespace and want to transfer the file of a Grafana pod allocated in the multi-services namespace. So, let’s examine the pod:

$ kubectl get pods --namespace=multi-services
NAME                      READY    STATUS    RESTARTS   AGE
grafana-68d7496c9b-mwhc9   1/1     Running   0          45s
nginx-redis-pod            2/2     Running   0          55s

The pod contains only one container and is working correctly. So, we can go ahead and copy the Grafana configuration file:

$ kubectl cp multi-services/grafana-68d7496c9b-mwhc9:etc/grafana/grafana.ini /home/user/grafana/grafana.ini 
$ ls grafana/
grafana.ini

Notice that in this command, we remove the leading slash from the remote path. That’s because tar is being used behind the scenes which recommends removing leading slashes from its inputs.

For the last example, let’s consider the scenario where we want to copy the file of a specific container. Previously, when we searched for pods in the multi-services namespace, we saw that in addition to the Grafana pod, there’s an nginx-redis-pod pod.

This pod contains two active services and containers. In cases where there’s more than one active container or service, it’s interesting to enter the name of the container from which the file to be copied originates:

$ kubectl cp multi-services/nginx-redis-pod:etc/nginx/nginx.conf /home/user/nginx/nginx.conf -c nginx
$ ls nginx/
nginx.conf

4. Conclusion

In this tutorial, we explore how to transfer files between Kubernetes pods and the local system using the kubectl cp command. Basically, we must specify the correct source and destination paths of the file to be copied and have the necessary permissions.