Файловая система S3#

CedrusData поддерживает работу с S3-совместимыми объектными хранилищами. Для этого вы можете использовать коннекторы Iceberg, Delta Lake, Hudi и Hive.

Для начала работы с объектным хранилищем, задайте параметр fs.native-s3.enabled=true в конфигурации соответствующего каталога.

Общая конфигурация#

Используйте параметры ниже для конфигурации доступа к S3-совместимому объектному хранилищу.

Название	Описание
`fs.native-s3.enabled`	Включает нативную поддержку S3. Установите значение в `true` для включения поддержки всех свойств, описанных ниже. Значение по умолчанию: `false`.
`s3.endpoint`	Адрес S3. Должен быть передан в формате `http[s]://host[:port]`. Обязательный параметр.
`s3.region`	Регион S3. Например, `us-east-1`. Обязательный параметр
`s3.path-style-access`	Использовать ли режим разрешения адресов path-style. Если значение равно `false`, будет использован режим virtual-hosted–style. Многие on-premises решения используют режим `path-style`. Значение по умолчанию: `false`.
`s3.exclusive-create`	Поддерживает ли S3-сервис conditional write. Значение по умолчанию: `true`.
`s3.canned-acl`	Canned ACL, который будет использован для загрузки файлов в S3-сервис. Допустимые значения: `NONE`, `PRIVATE`, `PUBLIC_READ`, `PUBLIC_READ_WRITE`, `AUTHENTICATED_READ`, `BUCKET_OWNER_READ`, or `BUCKET_OWNER_FULL_CONTROL`. Значение по умолчанию: `NONE`.
`s3.sse.type`	Задает тип server-side encryption (SSE). `NONE` - шифрование отключено; `S3` - шифровать данные с помощью S3 managed keys; `KMS` - шифровать данные с помощью AWS Key Management Service (KMS). При работе с AWS S3, значения `NONE` и `S3` эквивалентны. Значение по умолчанию: `NONE`.
`s3.sse.kms-key-id`	Идентификатор ключа KMS при использовании SSE.
`s3.streaming.part-size`	Размер частей файла при S3 streaming upload. Допустимые значения: от `5MB` до `256MB`. Значение по умолчанию: `16MB`.
`s3.requester-pays`	Включает опцию «requester pays». Значение по умолчанию: `false`.
`s3.max-connections`	Максимальное количество подключений к S3. Значение по умолчанию: `500`.
`s3.connection-ttl`	Максимальная длительность в течение которой возможно переиспользование уже открытого подключения к S3.
`s3.connection-max-idle-time`	Максимальная длительность в течение которой неиспользуемое подключение к S3 остается открытым.
`s3.socket-connect-timeout`	Максимальная длительность ожидания открытия подключения к S3.
`s3.socket-read-timeout`	Максимальная длительность ожидания чтения данных из S3.
`s3.tcp-keep-alive`	Включает опцию TCP keep alive для новых подключений к S3. Значение по умолчанию: `false`.
`s3.http-proxy`	URL прокси-сервера для подключения к S3.
`s3.http-proxy.secure`	Включает протокол HTTPS при подключении к прокси-серверу.
`s3.http-proxy.username`	Имя пользователя, которое будет использовано при подключении к прокси-серверу.
`s3.http-proxy.password`	Пароль, который будет использован при подключении к прокси-серверу.
`s3.http-proxy.non-proxy-hosts`	Список хостов, подключение к которым будет происходить, минуя прокси-сервер.
`s3.http-proxy.preemptive-basic-auth`	Следует ли осуществлять preemptive аутентификацию в прокси-сервере. Значение по умолчанию: `false`.
`s3.retry-mode`	Задает режим retry для AWS SDK. Допустимые значения: `STANDARD`, `ADAPTIVE`, `LEGACY`. Значение по умолчанию: `LEGACY`.
`s3.max-error-retries`	Максимальное количество retry. Значение по умолчанию: `10`.
`s3.use-web-identity-token-credentials-provider`	Установите в `true`, чтобы использовать web identity token credentials provider вместо credential provider chain по умолчанию. Данная опция может быть полезна, когда вы используете CedrusData в Amazon EKS совместно с IAM roles for service accounts (IRSA). Значение по умолчанию: `false`.

Аутентификация#

Используйте параметры ниже для аутентификации в S3 с помощью постоянных ключей, STS или IAM role.

Название	Описание
`s3.aws-access-key`	Постоянный AWS access key.
`s3.aws-secret-key`	Постоянный AWS secret key.
`s3.sts.endpoint`	URL AWS Security Token Service.
`s3.sts.region`	Регион AWS Security Token Service.
`s3.iam-role`	ARN IAM role, который будет использован при подключении к S3.
`s3.role-session-name`	Role session name, который будет использован при подключении к S3. Значение по умолчанию: `trino-filesystem`.
`s3.external-id`	External ID для IAM role trust policy.

Динамическая аутентификация#

CedrusData позволяет задавать разные механизмы аутентификации в S3 для различных пользователей и путей. IAM role для конкретного запроса может быть передана с помощью extra credential.

Конфигурация динамической аутентификации должна быть задана в виде JSON, который может быть прочитан из файловой системы (параметр конфигурации s3.security-mapping.config-file) или через HTTP (параметр конфигурации s3.security-mapping.config-uri).

JSON содержит список правил выбора механизма аутентификации для конкретного пользователя или пути. Сопоставление правил происходит в соответствии с порядком их указания в JSON. Если для заданного пользователя или пути подходит несколько правил, то будет использовано правило, которое указано ранее. Если не подходит ни одно правило, то доступ будет запрещен.

Выбор механизма аутентификации происходит в соответствии со следующими критериями:

user: Регулярное выражение для имени пользователя. Например: alice|bob
group: Регулярное выражение для имени группы пользователей. Например: finance|sales
prefix: Префикс S3 URL. Должен начинаться с s3://. Например: s3://bucket-name/abc/xyz/

Если вы не укажите ни один критерий, то текущее правило будет использовано как правило по умолчанию.

Правило должно предоставлять информацию об одном или нескольких механизмах аутентификации:

accessKey и secretKey: Статические AWS access key и secret key.
iamRole: IAM role по умолчанию, которая будет использована, если иная роль не задана через extra credential.
roleSessionName: Необязательное значение role session name, которое будет использовано совместно с iamRole. Может включать шаблон ${USER}, который будет заменен на имя текущего пользователя. Значение по умолчанию: trino-session.
allowedIamRoles: Список IAM role, которые могут быть использованы в качестве extra credential. Данный параметр может быть полезен, когда S3 позволяет использовать несколько IAM role, но вы хотите, чтобы конкретный пользователь использовал только определенные IAM role.
kmsKeyId: Идентификатор ключа KMS для client-side encryption.
allowedKmsKeyIds: Допустимые идентификаторы ключа KMS, которые могут быть использованы в качестве extra credential. Если список содержит значение *, то любые ключи могут быть использованы в качестве extra credential.
endpoint: Адрес S3. Должен быть передан в формате http[s]://host[:port].
region: Регион S3.
useClusterDefault: Использовать параметры аутентификации из конфигурации каталога. Данный флаг может быть указан только для правила по умолчанию.

Пример JSON:

{
  "mappings": [
    {
      "prefix": "s3://bucket-name/abc/",
      "iamRole": "arn:aws:iam::123456789101:role/test_path"
    },
    {
      "user": "bob|charlie",
      "iamRole": "arn:aws:iam::123456789101:role/test_default",
      "allowedIamRoles": [
        "arn:aws:iam::123456789101:role/test1",
        "arn:aws:iam::123456789101:role/test2",
        "arn:aws:iam::123456789101:role/test3"
      ]
    },
    {
      "prefix": "s3://special-bucket/",
      "accessKey": "AKIAxxxaccess",
      "secretKey": "iXbXxxxsecret"
    },
    {
      "prefix": "s3://regional-bucket/",
      "iamRole": "arn:aws:iam::123456789101:role/regional-user",
      "endpoint": "https://bucket.vpce-1a2b3c4d-5e6f.s3.us-east-1.vpce.amazonaws.com",
      "region": "us-east-1"
    },
    {
      "prefix": "s3://encrypted-bucket/",
      "kmsKeyId": "kmsKey_10"
    },
    {
      "user": "test.*",
      "iamRole": "arn:aws:iam::123456789101:role/test_users"
    },
    {
      "group": "finance",
      "iamRole": "arn:aws:iam::123456789101:role/finance_users"
    },
    {
      "iamRole": "arn:aws:iam::123456789101:role/default"
    }
  ]
}

Параметры конфигурации динамической аутентификации:

Название	Описание
`s3.security-mapping.enabled`	Включает динамическую аутентификацию. Значение по умолчанию: `false`.
`s3.security-mapping.config-file`	Путь к файлу с JSON в локальной файловой системе координатора.
`s3.security-mapping.config-uri`	HTTP URI, который возвращает JSON.
`s3.security-mapping.json-pointer`	Необязательный JSON pointer (RFC 6901) для получения узла, содержащего конфигурацию динамической аутентификации.
`s3.security-mapping.iam-role-credential-name`	Имя extra credential, который будет использован для передачи IAM role.
`s3.security-mapping.kms-key-id-credential-name`	Имя extra credential, который будет использован для идентификатора KMS ключа.
`s3.security-mapping.refresh-period`	Как часто обновлять JSON конфигурацию. Например: `1m` (раз в минуту).
`s3.security-mapping.colon-replacement`	Символ, который будет использован вместо символа `:` при передаче IAM role через extra credential. Необходимо выбрать символ, который не встречается ни в одной IAM role.