How to Transfer Files to Kubernetes Pods (and Bypass NAS Permissions)
When hosting applications like Jellyfin in Kubernetes, you often need to move gigabytes of media files from your local machine (like a MacBook) to the storage array backing the pods.
If your storage array (like TrueNAS) is blocking your SMB/NFS connections due to strict ACLs, you can bypass the array entirely and push the files through the Kubernetes API directly into the running container.
1. Using kubectl cp
The kubectl cp command allows you to copy files from your local machine to a specific path inside a pod.
Syntax
Example: Copying a Movie
If you have a movie file on your Mac desktop and want to put it into the Jellyfin movies folder:
# 1. Find the pod name
kubectl get pods -n media
# 2. Copy the file
kubectl cp ~/Desktop/Inception.mkv media/jellyfin-d6cf794b5-t5tl6:/data/media/movies/
The macOS Spaces Bug
Warning: kubectl cp uses the tar command under the hood. There is a known bug where it silently fails if the source path on macOS contains spaces (e.g., untitled folder). It will return instantly, output nothing, and copy nothing.
Fix: Rename the folder to remove spaces before copying, or manually bundle it into a .tar file on macOS, copy the .tar file, and unpack it inside the pod using kubectl exec.
2. Unlocking Permissions with kubectl exec
Sometimes you successfully connect your Mac to the TrueNAS share via SMB, but when you try to paste a file into the /movies folder, macOS says Permission Denied.
This happens because the folder was created by the Jellyfin container, which runs as a specific user (usually abc or UID 1000). Your external SMB user does not map to UID 1000, so Linux permissions (755) block you.
Because the container owns the folder, you can use the container to unlock it.
Step 1: Open a Shell or Run a Command
Use kubectl exec to run the chmod command as the container's privileged user:
-n media: The namespace.deploy/jellyfin: You can target the Deployment directly instead of finding the exact pod name.--: Indicates the start of the command to run inside the pod.chmod -R 777: Recursively grants Read, Write, and Execute permissions to everyone.
Step 2: Retry the SMB Copy
Now that the folder is fully unlocked, your external SMB user will be able to paste files into it without issue.
3. Advanced Alternative: rsync
For massive media libraries or slow network connections, kubectl cp is inefficient because it doesn't show progress bars and cannot resume broken transfers.
In these cases, if your storage array's ACLs are blocking you, you can spin up a temporary "transfer pod" with an SSH server and rsync installed, mount the PVC to it, and use native rsync from your Mac. However, for most one-off file transfers, kubectl cp and chmod are much faster.