Godwit Sync - On-the-Fly Object Storage Migration at Scale

Довідник конфігураційного файлу

Godwit Sync підтримує конфігураційні файли YAML як альтернативу прапорцям CLI. Використовуйте --config (-f) для завантаження конфігураційного файлу.

Базове використання

godwit sync --config my-sync.yml
godwit sync -f my-sync.yml

# Override a config value with a CLI flag
godwit sync -f my-sync.yml --parallel 8

Пріоритет CLI

Прапорці CLI завжди мають пріоритет над значеннями конфігураційного файлу. Якщо прапорець встановлено в командному рядку, відповідне значення конфігурації ігнорується.

Змінні середовища

Значення конфігураційного файлу підтримують підстановку змінних середовища. Використовуйте синтаксис $VAR або ${VAR} для посилання на змінні середовища. Змінні розгортаються під час завантаження конфігураційного файлу.

source:
  endpoint: minio.example.com:9000
  access_key: $AWS_ACCESS_KEY_ID
  secret_key: ${AWS_SECRET_ACCESS_KEY}
  session_token: ${AWS_SESSION_TOKEN}

Невстановлені змінні середовища розгортаються в порожній рядок.

Структура конфігураційного файлу

Конфігураційний файл використовує формат YAML з такими секціями верхнього рівня:

Джерело

Налаштування endpoint джерела — локальний шлях або S3 bucket.

YAML ключ	Тип	Прапорець CLI	Опис
source.url	string	--source	Шлях джерела або S3 URI (s3://bucket/prefix)
source.endpoint	string	--source-endpoint	S3 API endpoint (host:port)
source.auth_mode	string	--source-auth	Режим облікових даних (static, env, profile, iam, assume-role, anonymous, auto)
source.access_key	string	--source-access-key	S3 ключ доступу
source.secret_key	string	--source-secret-key	S3 секретний ключ
source.session_token	string	--source-session-token	Необов’язковий токен сесії для тимчасових облікових даних
source.profile	string	--source-profile	Імʼя AWS-профілю (використовується з auth_mode: profile)
source.role_arn	string	--source-role-arn	IAM role ARN для STS AssumeRole
source.role_session	string	--source-role-session	Імʼя сесії для STS AssumeRole
source.region	string	--source-region	S3 регіон
source.secure	bool	--source-secure	Використовувати TLS для S3 з’єднань
source.disable_keepalive	bool	--source-disable-keepalive	Вимкнути HTTP keep-alive

Призначення

Налаштування endpoint призначення — локальний шлях або S3 bucket.

YAML ключ	Тип	Прапорець CLI	Опис
destination.url	string	--destination	Шлях призначення або S3 URI
destination.endpoint	string	--destination-endpoint	S3 API endpoint (host:port)
destination.auth_mode	string	--destination-auth	Режим облікових даних (static, env, profile, iam, assume-role, anonymous, auto)
destination.access_key	string	--destination-access-key	S3 ключ доступу
destination.secret_key	string	--destination-secret-key	S3 секретний ключ
destination.session_token	string	--destination-session-token	Необов’язковий токен сесії для тимчасових облікових даних
destination.profile	string	--destination-profile	Імʼя AWS-профілю (використовується з auth_mode: profile)
destination.role_arn	string	--destination-role-arn	IAM role ARN для STS AssumeRole
destination.role_session	string	--destination-role-session	Імʼя сесії для STS AssumeRole
destination.region	string	--destination-region	S3 регіон
destination.secure	bool	--destination-secure	Використовувати TLS для S3 з’єднань
destination.disable_keepalive	bool	--destination-disable-keepalive	Вимкнути HTTP keep-alive

Політика

Політики порівняння та пропуску для фільтрації об’єктів.

YAML ключ	Тип	Прапорець CLI	Опис
policy.compare	string	--compare-policy	Політика порівняння (size,etag або size,mtime)
policy.skip	string[]	--skip	Список суфіксів або шаблонів для пропуску
policy.match	string	--match	Регулярний вираз для включення лише відповідних ключів обʼєктів джерела

Параметри

Налаштування поведінки передачі — паралелізм, повтори, перезапис.

YAML ключ	Тип	Прапорець CLI	Опис
options.parallel	int	--parallel	Кількість паралельних воркерів синхронізації
options.plan_parallel	int	--plan-parallel	Кількість паралельних воркерів планування
options.buffer_multiplier	int	--buffer-multiplier	Множник довжини черги копіювання
options.multipart_threshold	int64	--multipart-threshold	Поріг multipart завантаження в байтах
options.override	bool	--override	Перезаписати існуючі об’єкти призначення
options.skip_tags	bool	--skip-tags	Пропустити читання тегів об’єктів з джерела
options.unsupported_key_action	string	--unsupported-key-action	Дія для непідтримуваних ключів обʼєктів S3: fail, skip або warn
options.retry	int	--retry	Максимум повторів на об’єкт
options.retry_backoff	string	--retry-backoff	Базова затримка між повторами
options.ram_conflict_check	bool	--ram-conflict-check	Використовувати оперативну пам'ять для виявлення конфліктів регістру (швидше, але необмежена RAM)

Запуск

Відстеження запуску — ID запуску, драйвер стану та шлях до файлу стану.

YAML ключ	Тип	Прапорець CLI	Опис
run.run_id	string	--run-id	Ідентифікатор запуску для відстеження
run.state_driver	string	--state-driver	Драйвер бекенду стану
run.state_path	string	--state-path	Шлях до файлу бази даних стану
run.logs_dir	string	--logs-dir	Директорія для логів спостережуваності

Вивід

Режим виводу в консоль — UI, стислий або тихий.

YAML ключ	Тип	Прапорець CLI	Опис
output.ui	bool	--ui	Увімкнути детальне логування в консолі
output.brief	bool	--brief	Показувати лише основні повідомлення прогресу
output.silent	bool	--silent	Придушити весь вивід консолі

Ліцензія

Шлях до файлу ліцензії або рядок ліцензії.

YAML ключ	Тип	Прапорець CLI	Опис
license.file	string	--license-file	Шлях до файлу ліцензії
license.inline	string	--license	Base64-рядок ліцензії

Обмеження швидкості

Контроль дросселювання — RPS, ширина каналу та одночасність.

YAML ключ	Тип	Прапорець CLI	Опис
rate_limit.rps	float64	--rps	Ліміт запитів на секунду (0 = вимкнено)
rate_limit.read_bps	int64	--read-bps	Ліміт байтів читання на секунду (0 = вимкнено)
rate_limit.max_inflight	int	--max-inflight	Максимум одночасних завантажень (0 = вимкнено)

Статус

HTTP-адреса сервера метрик та статус-ендпоінту.

YAML ключ	Тип	Прапорець CLI	Опис
status.addr	string	--status-addr	HTTP-адреса для сервера статусу/метрик
status.drain_timeout	int	--drain-timeout	Секунди утримання сервера статусу/метрик активним після завершення операції, щоб читачі могли зібрати фінальні дані (за замовчуванням: 15)

Версіонування

Налаштування списку версій і фільтрації ключів джерела.

YAML ключ	Тип	Прапорець CLI	Опис
versioning.mode	string	--version-mode	Режим списку версій (latest, all, since:<RFC3339>)

Object Lock

Налаштування реплікації Object Lock для retention та legal hold.

YAML ключ	Тип	Прапорець CLI	Опис
object_lock.enabled	bool	--object-lock	Реплікувати налаштування Object Lock (retention та legal hold) з джерела на призначення

Приклади конфігурацій

Локальна файлова система → S3

Завантаження локальної директорії до S3-сумісного bucket.

source:
  url: "./data"

destination:
  url: "s3://my-bucket/backup"
  endpoint: localhost:9001
  access_key: access_key
  secret_key: secret_key
  secure: false

options:
  parallel: 3

output:
  ui: true

status:
  addr: ":8080"

S3 → Локальна файлова система

Завантаження об’єктів з S3 bucket до локальної директорії.

source:
  url: "s3://my-bucket/data"
  endpoint: localhost:9001
  access_key: access_key
  secret_key: secret_key
  secure: false

destination:
  url: "./downloads"

policy:
  skip:
    - .md5

options:
  parallel: 6

output:
  ui: true

S3 → S3

Копіювання даних між двома S3-сумісними endpoints.

source:
  url: "s3://source-bucket/data"
  endpoint: localhost:9001
  access_key: access_key
  secret_key: secret_key
  secure: false

destination:
  url: "s3://dest-bucket/backup"
  endpoint: localhost:9101
  access_key: access_key
  secret_key: secret_key
  secure: false

policy:
  skip:
    - .md5

options:
  parallel: 9

output:
  ui: true

status:
  addr: ":8080"

Повний приклад (усі секції)

Повний конфігураційний файл з усіма доступними параметрами.

source:
  url: "s3://source-bucket/prefix"
  endpoint: source.storage.example.com
  access_key: SOURCE_ACCESS_KEY
  secret_key: SOURCE_SECRET_KEY
  region: us-east-1
  secure: true

destination:
  url: "s3://dest-bucket/backup"
  endpoint: localhost:9000
  access_key: access_key
  secret_key: secret_key
  secure: false

policy:
  compare: "size,etag"
  skip:
    - .md5
    - .tmp
  match: "^data/.*\.txt$"

options:
  parallel: 4
  plan_parallel: 8
  buffer_multiplier: 4
  multipart_threshold: 67108864
  override: false
  skip_tags: false
  unsupported_key_action: "skip"
  retry: 3
  retry_backoff: "1s"

run:
  run_id: "daily-backup"
  state_driver: sqlite
  state_path: "./godwit-sync.state.db"
  logs_dir: "./logs"

output:
  ui: true
  brief: false
  silent: false

license:
  file: "./license.json"

rate_limit:
  rps: 50
  read_bps: 104857600
  max_inflight: 10

versioning:
  mode: "all"

object_lock:
  enabled: true

status:
  addr: ":8080"

Прапорці лише для CLI

Ці прапорці не мають еквіваленту в конфігураційному файлі та мають передаватися в командному рядку:

Прапорець	Опис
--config (-f)	Вибирає конфігураційний файл для завантаження
--plan-only	Планування передачі без копіювання даних
--resume	Відновлення раніше запланованої передачі
--register	Реєстрація ліцензії на диск

Довідник CLI

Перегляньте повний список усіх прапорців CLI з типами, значеннями за замовчуванням та описами.

Переглянути довідник CLI

← Посібники Довідник CLI →