Deploying apps on Kubernetes (K8) can feel like walking a tightrope. One wrong step and boom. Your app doesn’t work, your pod crashes, or your team’s stuck debugging for hours.If this sounds familiar, you’re not alone. A 2023 CNCF report found that 66% of consumers were using Kubernetes for production, and a majority of them were dealing with K8s’ complexities. But many errors are preventable if you know what to look for.Discover the most common deployment mistakes, what causes them, and how to fix or avoid them.Coming Up NextPrerequisites and ContextBasic Syntax of kubectl cpCommon Use CasesCopying Directories and Recursive TransfersWorking With Multicontainer PodsCopying Across Namespaces and ContextsDealing With Symlinks, Permissions, and Preserved MetadataTroubleshooting kubectl cp ErrorsPerformance Tips and AlternativesSecurity ConsiderationsAutomating File Copy in CI/CD PipelinesWrap-Up: Keep It Simple, Ship It SmoothPrerequisites and ContextBefore we dive in, let’s make sure you’re set up. You don’t need to be a Kubernetes expert, but a few basics will help you follow along. Here’s what you should have ready:A Kubernetes cluster (local or cloud-based)kubectl installed on your machineBasic understanding of YAML files (just the idea that they describe how things work in Kubernetes)An app to deploy — even a simple “Hello World” one worksA bit of command-line comfortThat’s it, and you’re good to go.Basic Syntax of kubectl cpThe kubectl cp command lets you copy files and folders between your local machine and your Kubernetes pods. It’s like using a USB stick, but for containers.Under the hood, it uses the tar command to package and transfer files between your system and the container. This means both your machine and the container need to support basic tar operations for it to work smoothly.Source and Destination PatternsThe basic pattern looks like this: kubectl cp But here’s the catch: When you’re copying to or from a pod, you need to include: /:Examples:Copy a file from your local machine to a pod: kubectl cp ./myfile.txt default/mypod:/app/myfile.txtCopy a file from a pod to your machine: kubectl cp default/mypod:/app/log.txt ./log.txtImportant Flags (-c, -n, –retries, –no-preserve)Here are the most useful flags for kubectl cp:FlagWhat it doesWhen to use itExample command-cPick a containerYour pod has more than one containerkubectl cp -c my-container ./file.txt default/mypod:/path/-nSet the namespaceYour pod is not in the default namespacekubectl cp -n my-namespace ./file.txt mypod:/path/–retries=3Retry the copy if it failsYou want Kubernetes to try again if something goes wrongkubectl cp –retries=3 ./file.txt default/mypod:/path/–no-preserveSkip keeping the original timestampsYou don’t care when the file was created or modifiedkubectl cp –no-preserve ./file.txt default/mypod:/path/Common Use CasesLet’s look at some everyday ways developers use kubectl cp. Whether you’re moving a config file into a pod, grabbing logs from one, or copying data between pods, this command can save time and headaches.Copying Local Files to a PodUse this command if you want to send a file from your laptop into a pod: kubectl cp ./myfile.txt default/mypod:/app/myfile.txtWith this command, we’re telling Kubernetes: “Hey, take this file on my computer and put it inside the pod at this path.”This is helpful when:You’re updating config filesYou need to drop in a script or binaryYou want to test something quicklyCopying Files From a Pod to LocalIf you need to download something from a pod, just flip the order: kubectl cp default/mypod:/app/log.txt ./log.txtThis is great for:Saving logs for debuggingGrabbing output filesBacking up config filesPod-to-Pod Copy via Local HopKubernetes doesn’t support direct pod-to-pod copy. But here’s a trick:Copy the file from Pod A to your local machine: kubectl cp default/pod-a:/data/file.txt ./file.txtThen copy it from your local machine to Pod B: kubectl cp ./file.txt default/pod-b:/data/file.txtIt’s a two-step process, but it works like a charm when:You’re migrating data between servicesYou need to sync the setup files or logsCopying Directories and Recursive TransfersSometimes, you need to move a bunch of files, not just one. And luckily, kubectl cp can handle directories, too. Here’s what you need to do:Point it to the folder you want to copy: kubectl cp ./myfolder default/mypod:/app/myfolderOr copy from the pod back to your machine: kubectl cp default/mypod:/app/myfolder ./myfolderHandling Large Directories EfficientlyBig directories can slow things down or cause timeouts. Here are a few tips to keep things smooth:StepWhat to doCommand example1. Compress the folderShrinks the size for faster transfertar -czf myfolder.tar.gz myfolder2. Copy the archiveMove the .tar.gz file to your podkubectl cp ./myfolder.tar.gz default/mypod:/app/3. Unpack inside the podExtracts the files once inside the podkubectl exec -it default/mypod — tar -xzf /app/myfolder.tar.gz -C /app/This method reduces the number of file transfers and speeds up the whole process and works especially well when:You’re moving lots of small files.You need to upload full project folders.You want to avoid transfer timeouts.Working With Multicontainer PodsSome pods have more than one container inside — kind of like a lunchbox with multiple compartments. By default, kubectl cp doesn’t know which one you want to copy to or from. So, you need to tell it.Selecting the Right ContainerUse the -c flag to name the container you want to work with.Example: kubectl cp -c my-container ./file.txt default/mypod:/app/This tells Kubernetes: “Hey, copy this file into the my-container inside mypod.”You’ll usually need this when:You’re working with sidecar containers, like one for logs and one for the app.You only want to target one specific container in the pod.Your kubectl cp command is failing without it.Copying Across Namespaces and ContextsKubernetes clusters often have multiple namespaces (like folders) and multiple contexts (like environments). If you don’t specify the right one, your command won’t find the pod.Here are a few ways to deal with it:Use -n to pick the right namespace: kubectl cp -n custom-namespace ./file.txt mypod:/app/Use –context if you’re working in a different cluster: kubectl –context=my-cluster cp ./file.txt default/mypod:/app/Check your current context and namespace: kubectl config get-contextskubectl config view –minify | grep namespaceThese small flags make a big difference when you’re juggling dev, staging, and production setups.Dealing With Symlinks, Permissions, and Preserved MetadataThe kubectl cp command tries to copy things as-is, but there are a few things that can cause problems if you’re not careful.Here’s what to look out for:Symlinks may break: Symlinks (shortcut files) might not work as expected after copying. If you’re relying on them, double-check their paths inside the pod.Permissions might not match: File permissions, such as who can read/write, may change after copying. Use kubectl exec and chmod inside the pod if needed.Timestamps are preserved by default: The file keeps its original “created” and “modified” times. To turn this off, use the –no-preserve flag:kubectl cp –no-preserve ./file.txt default/mypod:/app/Executable files might lose permissions: If your script or binary isn’t working inside the pod, check if it’s still marked as executable:kubectl exec -it mypod — chmod +x /app/myscript.shCopying files sounds simple, but the details matter, especially when you’re troubleshooting strange behavior.Troubleshooting kubectl cp ErrorsSometimes, kubectl cp doesn’t work the way you expect. Let’s break down some of the most common errors and exactly how to fix them.Permission Denied and Read-Only File SystemThe error:tar: ./file.txt: Cannot open: Permission deniedtar: Exiting with failure status due to previous errorsWhat it means:You’re trying to copy a file into a folder where the container doesn’t have write access.The container’s file system might be read-only, or your user inside the pod lacks permission.To fix it:Try copying to a different folder, like /tmp, which is usually writable: kubectl cp ./file.txt default/mypod:/tmp/Or, exec into the pod and change permissions (if allowed): kubectl exec -it mypod — chmod 777 /target/folderHeads-up: In production pods, changing permissions may not be allowed, and that’s by design for security.No Such File or DirectoryThe error:error: one of src or dest must be a local file specificationOr: tar: /app/file.txt: No such file or directoryWhat it means:The file or folder path doesn’t exist — either on your machine or inside the pod.Or, you misspelled the pod name, container name, or namespace.To fix it:Double-check your source and destination paths. Use kubectl exec to inspect the pod: kubectl exec -it mypod — ls /app/Make sure you’re targeting the right namespace: kubectl cp -n my-namespace ./file.txt mypod:/app/Use kubectl get pods to confirm the pod name.Unexpected Tar Format ErrorsThe error: unexpected tar header errorWhat it means: The kubectl cp command relies on tar under the hood. If tar isn’t installed in the container — or if the version is too different — things break.To fix it:Check if tar exists inside the pod: kubectl exec -it mypod — whichIf tar is missing, you won’t be able to use kubectl cp. You have two options:Install tar, if possible and safe to do so.Use an alternative like the tar + exec combo (explained below!)Performance Tips and AlternativesIf you’re moving large files or lots of files, kubectl cp can be slow. Or flaky. Here are a couple of tips that offer faster, more reliable alternatives.Using Tar Over kubectl exec for Big FilesInstead of kubectl cp, try creating a tar archive yourself and pushing it using kubectl exec. This avoids many of the bugs tied to kubectl cp.Example: Copying to a podCompress your files: tar -czf files.tar.gz myfolder/Copy the archive: kubectl cp ./files.tar.gz default/mypod:/tmp/Unpack it inside the pod: kubectl exec -it mypod — tar -xzf /tmp/files.tar.gz -C /app/This method works better because it: Has fewer files, which means faster transfersOffers more control over how things are unpackedWorks even if kubectl cp is flakyLeveraging rsync via kubectl port-forwardIf you want blazing-fast file sync, try rsync — a powerful file transfer tool. It’s not built into Kubernetes, but you can port-forward to a container running rsync, and then push files directly.Here’s how you can do it:Run rsync inside a container, either install it or use a custom image that has it.Port-forward to expose rsync: kubectl port-forward pod/mypod 8730:873Use rsync from your machine to push files: rsync -av ./myfolder rsync://localhost:8730/app/This method works well because it:Is fast and efficient for lots of filesOnly transfers what’s changed, which saves timeIs great for syncing folders during devThat said, you’ll need a container with rsync installed, and security rules that allow port-forwarding.Security ConsiderationsCopying files in and out of pods might seem harmless, but it can open doors to risks if you’re not careful. Let’s look at two key areas: Permissions and data safety.RBAC Rules for Copy OperationsKubernetes uses role-based access control (RBAC) to decide who can do what. Copying files with kubectl cp involves actions like:Reading from a podWriting to a podExecuting commands inside the container (via tar)So, to use kubectl cp, you must have permission to get, list, and exec pods in the right namespace.If you see access denied errors, it’s likely your user or service account doesn’t have these rights. An admin can fix this by updating the Role or ClusterRole bindings.Example Role:rules:- apiGroups: [""]resources: ["pods", "pods/exec"]verbs: ["get", "list", "create", "delete", "exec"]Pro tip: Always follow least privilege, i.e., give only the access that’s needed and nothing more.Avoiding Sensitive Data LeakageCopying files can accidentally expose secrets if you’re not paying attention. Here’s how to stay safe:Never copy files into a pod’s /etc, /secrets, or system directories unless you know what you’re doing.Don’t copy secrets out of pods, like TLS certificates, config files, or .envReview file contents before copying, especially when using wildcard commands or whole directories.Audit who has access to kubectl cp, and make sure devs aren’t copying sensitive files into shared or production pods.Pro tip: If you’re working with sensitive files (like keys, certs, or passwords), use Kubernetes Secrets instead. They’re made for that.Automating File Copy in CI/CD PipelinesIn a CI/CD pipeline, manual steps are the enemy. You want everything, including file transfers, to run automatically and reliably.Using kubectl cp in your pipeline works for basic tasks, but there are a few things to keep in mind to make it safe and stable.For instance, you need to know when to automate file copy. You might want to copy files during:Pre-deployment steps, such as injecting config files into a pod.Post-deployment tests, like pulling logs or results from a test container.Data migration between app versions.Sample command in a pipeline script:kubectl cp ./build/output.zip default/my-app-pod:/app/output.zipYou can drop this into a CI/CD job step — in GitHub Actions, GitLab CI, or Jenkins.And here are a few things to keep in mind when automating file copy:Always set the namespace with -n so the command doesn’t rely on local configs: kubectl cp -n staging ./file.txt mypod:/app/Set KUBECONFIG in your CI environment to point to the right cluster.Add retries or checks in case the pod isn’t ready yet: kubectl wait –for=condition=Ready pod/mypodUse tar + exec instead of kubectl cp if your container doesn’t have tar, or if kubectl cp is flaky in your setup.Remember to ensure that your CI runner only has access to what it needs. Don’t give it full admin rights just to copy files. Use a service account with the bare minimum permissions instead.Wrapping Up: Keep It Simple, Ship It SmoothCopying files in Kubernetes can be tricky, but with the right approach — using the correct flags, understanding pod/container setups, avoiding common errors, and optimizing for performance — it becomes a smooth part of your workflow. Whether you’re working in dev, CI/CD, or production, knowing how to handle file transfers gives you more control and fewer headaches.If you’re ready to automate even more of your Kubernetes tasks, check out our guide on how to run Kubernetes commands in Go. We talk about how to programmatically handle file operations, deployments, and more using Go.Primary sources: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_cp/https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/https://kubernetes.io/docs/concepts/workloads/pods/https://kubernetes.io/docs/reference/kubectl/The post kubectl cp: Copying Files to and From Kubernetes Pods appeared first on The New Stack.