S3 501 на query-параметр: шлюз не знает этот параметр

Коротко. HEAD или GET с дополнительным query-параметром отдаёт 501 Not Implemented, а тот же запрос без параметра — 200 или 404. Это не поломка S3 и не ошибка подписи: у шлюза есть список известных query-параметров, и незнакомый он не игнорирует, а отвергает. Штатный путь — добавить параметр в whitelist вендорским support-скриптом, а не «подкручивать» клиента наугад.

Симптом

Клиент получает 501 Not Implemented на запрос, который отличается от рабочего только query-параметром: HEAD /<BUCKET>/<KEY>?<PARAM>, GET …?<PARAM>.
Контрольный запрос без параметра проходит: объект есть — 200, объекта нет — 404.
Внешние проявления у клиента зависят от его логики: например, проверка «объект уже в облаке?» возвращает ошибку, и переход объекта не выполняется.
GUI зелёный, S3-фронт отвечает (307 на корень, Server: Quantum-ActiveScale), ключи и политика в порядке.
В логах шлюза/фронта видно 501 на этот путь и параметр — при том, что соседние запросы к тому же объекту отвечают нормально.

Что проверить первым (read-only)

Воспроизвести разницу «с параметром / без» (только чтение): bash curl -sk -o /dev/null -w '%{http_code}\n' \ "https://<DOMAIN>/<BUCKET>/<KEY>?<PARAM>" curl -sk -o /dev/null -w '%{http_code}\n' \ "https://<DOMAIN>/<BUCKET>/<KEY>" Ожидается: первый — 501, второй — 200/404. Такая пара — подпись причины.
Проверить, что дело не в подписи и не в правах: попробуйте параметр, который шлюз уже знает (например служебные параметры из текущего whitelist), и параметр-«мусор»: bash curl -sk -o /dev/null -w '%{http_code}\n' \ "https://<DOMAIN>/<BUCKET>/<KEY>?foo=bar" Ожидается 501. Если вместо этого приходит 403 SignatureDoesNotMatch — проблема в подписи; 403 AccessDenied — в правах (см. соседнюю статью).
Что сейчас в whitelist (консоль продукта, только чтение): python cli.get_configrule('scalerd', 's3_whitelist_additional_query_parameters') Ожидается строка со списком параметров. Нужного параметра в ней нет — причина найдена. Эквивалент через Model API: bash sudo curl -sk --cert /opt/ampli/cfg/marvin/ssl/machine.cert \ --key /opt/ampli/cfg/marvin/ssl/machine.key \ "https://127.0.0.1:8443/model/configrule/?name=s3_whitelist_additional_query_parameters"
Логи фронта и шлюза — тот ли код и тот ли путь: bash sudo grep -n ' 501 ' /opt/ampli/var/log/haproxy/*.log | tail -20 Ожидается: строки с 501 именно на проблемный путь с query. Если 501 идёт на другие пути — это другой класс проблемы.
Поведение до и после изменения клиента: сравните запрос клиента и свой curl (метод, путь, заголовки). Ожидается: разница только в дополнительном параметре.

Причина

У шлюза фиксированный список query-параметров

S3-совместимость не означает «любой параметр». Шлюз разбирает query и понимает ограниченный набор: подписанные/служебные параметры, список которых хранится в модели (scalerd, s3_whitelist_additional_query_parameters) и рендерится в конфиг. Незнакомый параметр не игнорируется молча — он даёт 501 Not Implemented. Это осознанное поведение: «мы такого не умеем», а не «мы не поняли запрос» (для последнего был бы 400).

Почему это не ошибка клиента «по спеке»

501 приходит и на параметр, который клиент шлёт штатно по своей логике. Пример из практики: клиент проверяет объект параметром ?rgwx-skip-decrypt и получает 501; для него это выглядит как «хранилище не поддерживает операцию», и переход объекта срывается. При этом подпись и права в порядке — клиент ничего не нарушил.

Границы: что `501` не значит

Не значит «S3 API не реализован»: базовые операции работают, контрольный запрос без параметра проходит.
Не значит «бакет/ключ неверны»: на неверный бакет был бы 404 NoSuchBucket.
Не значит «прав нет»: 403 AccessDenied — другой код и другая причина.
Не значит «часы уехали»: там 403 с текстом про разницу времени.

Что здесь гипотеза

Механизм whitelist подтверждён живыми пробами «с параметром / без» и значением модели. Если параметр уже в whitelist, а 501 остаётся — гипотеза: конфиг шлюза не перерисован на части нод (изменение модели применилось не везде) либо параметр приходит в другой форме (например с пустым значением). Проверяется значением configrule на каждой ноде и повтором проб с ?<PARAM> и ?<PARAM>=.

Решение (штатное)

Собрать список параметров клиента — какие именно он шлёт сверх стандартных. Не угадывать: взять из его логов/трассировки (tcpdump -A на исходящий 443 либо debug-лог клиента).
Сузить список. В whitelist добавляется только то, что действительно нужно; «разрешить всё» расширяет поверхность и маскирует будущие расхождения.
Снять текущее значение (п.3 проверки) и сохранить его в файл вне каталога продукта — это основа отката: bash sudo cp -a /opt/ampli/cfg/scalerd /root/scalerd-cfg.bak-$(date -u +%y%m%d-%H%M)
Добавить параметр штатным support-скриптом продукта: bash sudo /opt/ampli/scripts/supportability/add_s3_whitelist_query_parameter.py \ --query_parameter <PARAM> Скрипт правит модельный ConfigRule и по очереди перерисовывает конфиг и перезапускает все scalerd; ожидание — до 3600 с. Ожидается: значение модели содержит параметр, все scalerd переконфигурированы, задача configure — SUCCESS.
Проверить пробами (п.1): параметр → 200/404; «мусорный» параметр → по-прежнему 501 (это правильно); контроль без параметра → 200/404.
Проверить клиентом. Ожидается: его операция проходит, ошибка вида «не удалось проверить объект» исчезает.

Если штатный путь недоступен

Окно обслуживания недоступно: временная мера — попросить клиента не слать лишний параметр (если его логика это позволяет) либо использовать путь, где параметр не нужен. Пометка: не штатно, план замены — whitelist.
Скрипт недоступен/упал: эквивалент — правка значения через /model/internal/configrule/update?resourcetype=scalerd&key=s3_whitelist_additional_query_parameters&value=… с последующим переконфигурированием scalerd. Требует понимания формата строки; ошибка в значении ломает фронт, поэтому только с бэкапом и в окно.
Откат: тот же скрипт с --remove либо возврат прежней строки тем же способом + configure scalerd.

⚠️ Переконфигурирование scalerd — операция с риском: в нашей практике configure вскрыл битый плейбук scalerd.yml и уронил S3-фронт на части нод (исправлено в тот же вечер). Поэтому whitelist делается в окно обслуживания, по одной ноде, с готовым планом отката и бэкапом конфигов.

Проверка

?<PARAM> → 200 (объект есть) или 404 (объекта нет), но не 501.
?foo=bar → 501 — контроль, что whitelist не «разрешено всё».
GET …/model/configrule/?name=s3_whitelist_additional_query_parameters → значение содержит параметр.
Все scalerd переконфигурированы; задача configure → SUCCESS.
curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/ → 307, фронт жив.
У клиента операция проходит; ошибок вида «проверка объекта не выполнена» в его логе нет.

Профилактика

Собирать query-профиль клиента до миграции: какие параметры он шлёт, какие ответы ожидает. Это дешевле, чем разбирать 501 после переключения.
Держать список whitelist документированным (кто добавил, зачем, когда).
Проверять whitelist после каждого апгрейда: хук обновления переписывает список (вычищает часть параметров), и добавленное может исчезнуть. Проверка — тем же get_configrule и пробой.
Не путать 501 с 400/403: код ответа — первый диагностический признак, он определяет, какой раздел открывать.
Логи 501 — на мониторинг: регулярный 501 на один и тот же параметр означает клиента, которому нужен whitelist, а не «шум».

Источники и дата

Вендор: ActiveScale Software Release Notes 7.3 (дата доступа 2026-11-07)
Вендор: Software Documentation Center 7.3 (дата доступа 2026-11-07)
Наша практика (обезличено): класс «S3 501 на query-параметр»; штатный whitelist через support-скрипт продукта, проверка пробами «с параметром / без», грабли при переконфигурировании scalerd.
Обновлено: 2026-11-07.