Копирование файлов между Pod и машиной

Графика с логотипом Kubernetes

Быстрые ссылки

Копирование на машину и с машины
Аргументы команды
Когда kubectl cp не работает
Альтернативы и методы
Чеклист и рекомендации
Краткое резюме

Копирование на машину и с машины

kubectl cp — самый простой способ перенести файлы между файловой системой контейнера и вашим компьютером. По сути он похож на знакомую команду docker cp из локальной разработки.

Формат аргументов требует указать источник и назначение. Одним из аргументов должен быть ссылочный путь на Pod. Ссылка на Pod выглядит как: :<путь-в-контейнере>

Пример копирования из Pod на локальную машину:

kubectl cp example-pod:/tmp/example-dir ./example-dir

Команда выше копирует содержимое каталога /tmp/example-dir из Pod с именем example-pod в локальную текущую директорию в папку example-dir. Если поменять местами аргументы, каталоги будут скопированы с локальной машины в Pod.

Определение: Pod — минимальная единица развертывания в Kubernetes, содержащая один или несколько контейнеров, которые разделяют сеть и тома.

Аргументы команды

Учтите, что один Pod может содержать несколько контейнеров. По умолчанию kubectl cp работает с первым контейнером в Pod. Чтобы указать конкретный контейнер, используйте флаг -c:

kubectl cp example-pod:/tmp/example-dir ./example-dir -c second-container

kubectl использует подключение, определённое вашим KUBECONFIG (обычно ~/.kube/config). При работе с namespaced Pod у вас есть два варианта: добавить флаг –namespace или указать полную ссылку на Pod в формате namespace/name:

kubectl cp example-namespace/example-pod:/tmp/example-dir ./example-dir

По умолчанию атрибуты файла сохраняются. Чтобы удалить информацию об владельцах и правах, передайте –no-preserve.

Отличие от unix cp: kubectl cp всегда рекурсивен — если вы указываете каталог, его содержимое будет включено автоматически.

Когда kubectl cp не работает

Главное ограничение: kubectl cp реализован через tar. Команда создаёт архив на стороне источника, передаёт его и распаковывает на стороне назначения. Для работы этого механизма в контейнере должен присутствовать tar в PATH.

Если образ минимален или собран с нуля, tar может отсутствовать. Популярные минимальные образы, такие как alpine, обычно содержат tar, но не все образы гарантируют это.

Ещё ограничения tar-подхода:

Невозможно разрешать символьные ссылки (в некоторых сценариях).
Нельзя использовать оболочковые шаблоны (wildcards) типа /tmp/*.log при передаче через kubectl cp.
Проблемы с правами и владельцами при разных UID/GID между хостом и контейнером.

Обходные пути и альтернативы

Ниже — проверенные варианты, если kubectl cp недоступен или ведёт себя не так, как нужно.

1) kubectl exec + cat (для отдельных небольших файлов)

Подходит для нескольких небольших файлов. Вы запускаете команду внутри контейнера и перенаправляете вывод в локальный файл:

kubectl exec --namespace example-namespace example-pod -c second-container -- cat /tmp/example-file > local-file

Пояснения:

Всё после двойного дефиса (–) выполняется внутри контейнера.
Вывод команды cat выводится в STDOUT и перенаправляется в локальный файл на вашей машине.

Ограничение: неудобно для больших директорий и большого количества файлов.

2) tar через kubectl exec (для каталогов и расширенных опций)

Если у вас есть tar внутри контейнера, но kubectl cp слишком ограничен по синтаксису, вы можете сами запустить tar и пропустить данные через STDOUT/STDIN:

На локальной машине:

kubectl exec --namespace example-namespace example-pod -c second-container -- tar -cf - /tmp/example-dir | tar -xf - -C ./extracted-dir

Объяснение:

tar -cf - создаёт архив и пишет его в STDOUT (символ - означает STDOUT).
Локальный tar -xf - читает из STDIN и распаковывает в ./extracted-dir.
Этот метод даёт полный контроль над опциями tar (сжатие, исключения, фильтрация).

Если вам нужно скопировать из локали в контейнер, поменяйте порядок и используйте tar в контейнере с опцией -x:

tar -cf - ./local-dir | kubectl exec --namespace example-namespace -i example-pod -c second-container -- tar -xf - -C /target-dir

Замечание: флаг -i для kubectl exec включает stdin.

3) Установить SSH и использовать scp (не рекомендуется на проде)

Можно установить SSH-сервер в контейнер и скопировать файлы через scp. Это даёт удобный опыт, но влечёт дополнительные риски:

Нужно запускать процесс sshd в контейнере (демон). Это нарушает принцип «один процесс на контейнер».
Увеличивается поверхность атаки. Требуется настройка ключей и защиты.

Рассматривайте этот вариант только в изолированных средах или во время отладки, не на production кластерах.

4) Добавление tar в образ (рекомендуется)

Лучшее долгосрочное решение — включить tar в образ. Это компактно и не добавляет демонов. После этого kubectl cp заработает корректно и вы получите гибкость tar через kubectl exec.

Пример Dockerfile для добавления tar (Alpine):

FROM alpine:3.18
RUN apk add --no-cache tar

Для Debian/Ubuntu:

FROM debian:stable-slim
RUN apt-get update && apt-get install -y --no-install-recommends tar && rm -rf /var/lib/apt/lists/*

Практическая методология: шаги при копировании файлов

Определите, что нужно скопировать: один файл, набор файлов или целый каталог.
Проверьте: присутствует ли tar в контейнере? (kubectl exec … – tar –version)
Если tar есть, используйте kubectl cp или tar через kubectl exec для точного контроля.
Если tar нет и нужен один файл — используйте kubectl exec + cat.
Если требуется регулярная синхронизация или массовая передача — добавьте tar в образ или примените безопасный переносной сервер файлов (не sshd в проде).
После копирования проверьте целевой файл: размеры, контрольные суммы (sha256sum), права.

Чеклист по ролям

Разделяйте обязанности и используйте чеклист для ускорения работы.

Для разработчика:

Убедиться, что файлы для передачи корректны.
Проверить наличие tar в локальном образе.
По необходимости собрать образ с tar.

Для инженера DevOps:

Проверить политики безопасности кластера перед установкой демонов.
Рассмотреть временное решение через kubectl exec для отладки.
Оценить необходимость добавления утилит в базовые образы.

Для инженера по безопасности:

Проверить, нет ли в образе лишних сетевых сервисов (SSH).
Убедиться, что передача не раскрывает секреты (логи, конфиги).
При использовании SCP/SSH применить ключи, ограничить доступ по IP.

Отладка и распространённые ошибки

Ошибка: No such file or directory: tar
- Причина: tar отсутствует в контейнере. Решение: добавьте tar в образ или используйте kubectl exec + cat.
Ошибка при попытке использовать шаблоны (*.log)
- Kubectl cp не поддерживает shell-glob внутри пути. Используйте tar с фильтром или kubectl exec и find + tar.
Проблемы с правами/владельцами
- Если владельцы меняются, используйте –no-preserve при необходимости или корректируйте права после копирования (chown/chmod).
Большие данные: тайм-аут или обрывы
- При передаче больших архивов используйте стабильное сетевое соединение и рассмотрите сжатие tar (tar -czf) для сокращения объёма.

Безопасность и соответствие

Не развертывайте SSH-сервер в контейнере без строгой настройки и аудита.
Логи и конфигурации могут содержать чувствительные данные. Передавать их стоит только по защищённым каналам и с учётом политик конфиденциальности.
Если вы работаете с пользовательскими данными EU/EEA, проверьте требования локальной политики и GDPR перед переносом данных между средами.

Сравнение подходов (коротко)

kubectl cp: просто, двунаправленно, требует tar, ограничен синтаксисом.
kubectl exec + tar: гибко, можно настроить фильтры и сжатие, требует tar.
kubectl exec + cat: работает без tar, подходит для отдельных файлов.
SSH/SCP: полный функционал, но риск и сложность.

Критерии приёмки

Файл/каталог успешно скопированы в целевую локацию.
Контрольная сумма (sha256) совпадает между источником и копией.
Права и владельцы соответствуют требованиям (или явно изменены с документированным объяснением).
Процесс передачи не нарушил политики безопасности и доступа.

Глоссарий в одну строку

kubectl: CLI-инструмент для управления Kubernetes.
Pod: минимальная единица развертывания в Kubernetes, содержащая один или несколько контейнеров.
tar: утилита архивации в UNIX-подобных системах.

Краткое резюме

kubectl cp — быстрый способ переносить файлы между Pod и локальной машиной, но он опирается на tar внутри контейнера. Если tar отсутствует, используйте kubectl exec + cat для отдельных файлов или запускайте tar вручную через kubectl exec для каталогов. Установка tar в образ — наиболее безопасное и практичное долгосрочное решение.

Важно: избегайте запуска SSHd в контейнере в production-средах без тщательной оценки безопасности.