> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Безопасный доступ к данным в S3

> В этой статье показано, как клиенты ClickHouse Cloud могут использовать ролевой доступ для аутентификации в Amazon Simple Storage Service (S3) и безопасного доступа к своим данным.

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

В этом руководстве показано, как клиенты ClickHouse Cloud могут использовать ролевой доступ для аутентификации в Amazon Simple Storage Service (S3) и безопасного доступа к своим данным.
Прежде чем переходить к настройке безопасного доступа к S3, важно понять, как это работает. Ниже приведен обзор того, как сервисы ClickHouse могут получать доступ к приватным S3 бакетам, принимая на себя роль в аккаунте AWS клиента.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/secures3.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=e2be247e06f4b03ed1598e110c0a9a01" size="lg" alt="Обзор безопасного доступа к S3 с ClickHouse" width="1218" height="674" data-path="images/cloud/security/secures3.webp" />

<br />

Этот подход позволяет клиентам управлять всем доступом к своим S3 бакетам в одном месте (в политике IAM для принимаемой роли), не просматривая все политики бакетов, чтобы добавить или удалить доступ.
В разделе ниже вы узнаете, как это настроить.

<div id="obtaining-the-clickhouse-service-iam-role-arn">
  ## Получение ARN роли IAM вашего сервиса ClickHouse
</div>

1. Войдите в свою учетную запись ClickHouse Cloud.

2. Выберите сервис ClickHouse, для которого хотите создать интеграцию.

3. Выберите вкладку **Settings**.

4. Прокрутите страницу вниз до раздела **Network security information** в нижней части страницы.

5. Скопируйте значение **Service role ID (IAM)** для сервиса, как показано ниже.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/secures3_arn.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=a182505cd64ba79fe3334d4aedb29534" size="lg" alt="Получение ARN роли IAM сервиса ClickHouse" border width="1222" height="254" data-path="images/cloud/security/secures3_arn.webp" />

<div id="setting-up-iam-assume-role">
  ## Настройка IAM Assume Role
</div>

IAM Assume Role можно настроить одним из двух способов:

* [С помощью стека CloudFormation](#option-1-deploying-with-cloudformation-stack)
* [Создав роль IAM вручную](#option-2-manually-create-iam-role)

<div id="option-1-deploying-with-cloudformation-stack">
  ### Развертывание с помощью стека CloudFormation
</div>

1. Войдите в свою учетную запись AWS в браузере под пользователем IAM, у которого есть права на создание роли IAM и управление ею.

2. Перейдите по следующему [URL CloudFormation](https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/quickcreate?templateURL=https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/secure-s3.yaml\&stackName=ClickHouseSecureS3), чтобы заполнить параметры стека CloudFormation.

3. Введите (или вставьте) **Service role ID (IAM)** для вашего сервиса, который вы получили ранее, в поле "ClickHouse Instance Roles"
   ID сервисной роли можно вставить в точности так, как он отображается в консоли Cloud.

4. Введите имя вашего бакета в поле "Bucket Names". Если URL вашего бакета — `https://ch-docs-s3-bucket.s3.eu-central-1.amazonaws.com/clickhouseS3/`, то имя бакета — `ch-docs-s3-bucket`.

<Note>
  Указывайте не полный ARN бакета, а только имя бакета.
</Note>

5. Настройте стек CloudFormation. Ниже приведена дополнительная информация об этих параметрах.

| Параметр                  | Значение по умолчанию | Описание                                                                                                                                          |
| :------------------------ | :-------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| RoleName                  |  ClickHouseAccess-001 | Имя новой роли, которую ClickHouse Cloud будет использовать для доступа к вашему S3 бакету.                                                       |
| Role Session Name         |           \*          | Role Session Name можно использовать как общий секрет для дополнительной защиты вашего бакета.                                                    |
| ClickHouse Instance Roles |                       | Список ролей IAM сервиса ClickHouse, разделенных запятыми, которые могут использовать эту защищенную интеграцию с S3.                             |
| Bucket Access             |          Read         | Задает уровень доступа для указанных бакетов.                                                                                                     |
| Bucket Names              |                       | Список имен бакетов, разделенных запятыми, к которым эта роль будет иметь доступ. **Примечание:** используйте имя бакета, а не полный ARN бакета. |

6. Установите флажок **I acknowledge that AWS CloudFormation might create IAM resources with custom names.**

7. Нажмите кнопку **Create stack** в правом нижнем углу

8. Убедитесь, что создание стека CloudFormation завершилось без ошибок.

9. Выберите только что созданный Stack, затем откройте вкладку **Outputs** этого стека CloudFormation

10. Скопируйте значение **RoleArn** для этой интеграции — оно потребуется для доступа к вашему S3 бакету.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/secures3_output.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=116ce2c5deb380366090189bc04cc806" size="lg" alt="Вывод стека CloudFormation с IAM Role ARN" border width="2020" height="422" data-path="images/cloud/security/secures3_output.webp" />

<div id="option-2-manually-create-iam-role">
  ### Создайте роль IAM вручную
</div>

1. Войдите в свой аккаунт AWS в браузере под пользователем IAM, у которого есть права на создание и управление ролью IAM.

2. Перейдите в консоль сервиса IAM

3. Создайте новую роль IAM со следующими политиками IAM и доверия. Замените `{ClickHouse_IAM_ARN}` на ARN роли IAM, относящейся к вашему экземпляру ClickHouse.

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "{ClickHouse_IAM_ARN}"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

**Политика IAM**

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:GetBucketLocation",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::{BUCKET_NAME}"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Resource": [
                "arn:aws:s3:::{BUCKET_NAME}/*"
            ],
            "Effect": "Allow"
        }
    ]
}
```

4. После создания скопируйте новый **ARN роли IAM** — он понадобится для доступа к вашему **S3 бакету**.

<div id="access-your-s3-bucket-with-the-clickhouseaccess-role">
  ## Получите доступ к S3 бакету с ролью ClickHouseAccess
</div>

ClickHouse Cloud позволяет указывать `extra_credentials` в табличной функции S3.
Ниже приведён пример выполнения запроса с использованием только что созданной роли, скопированной выше.

```sql theme={null}
DESCRIBE TABLE s3('https://s3.amazonaws.com/BUCKETNAME/BUCKETOBJECT.csv','CSVWithNames',extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001'))
```

Ниже приведён пример запроса, в котором `role_session_name` используется в качестве общего секрета для запроса данных из бакета.
Если `role_session_name` указан неверно, эта операция завершится ошибкой.

```sql theme={null}
DESCRIBE TABLE s3('https://s3.amazonaws.com/BUCKETNAME/BUCKETOBJECT.csv','CSVWithNames',extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001', role_session_name = 'secret-role-name'))
```

<Note>
  Мы рекомендуем размещать исходный S3 в том же регионе, что и ваш сервис ClickHouse Cloud, чтобы сократить расходы на передачу данных.
  Подробнее см. в разделе [Тарифы S3](https://aws.amazon.com/s3/pricing/)
</Note>

<div id="advanced-action-control">
  ## Расширенный контроль действий
</div>

Для более строгого управления доступом можно ограничить политику бакета так, чтобы она принимала только запросы, поступающие через конечные точки VPC ClickHouse Cloud, с помощью условия [`aws:SourceVpce`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies-vpc-endpoint.html#example-bucket-policies-restrict-accesss-vpc-endpoint). Чтобы получить конечные точки VPC для вашего региона ClickHouse Cloud, откройте терминал и выполните:

```bash theme={null}
# Замените <your-region> на регион вашего ClickHouse Cloud
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'
```

Затем добавьте в политику IAM запрещающее правило с полученными конечными точками:

```json theme={null}
{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "s3:List*",
                    "s3:Get*"
                ],
                "Resource": [
                    "arn:aws:s3:::{BUCKET_NAME}",
                    "arn:aws:s3:::{BUCKET_NAME}/*"
                ]
            },
            {
                "Sid": "VisualEditor3",
                "Effect": "Deny",
                "Action": [
                    "s3:GetObject"
                ],
                "Resource": "*",
                "Condition": {
                    "StringNotEquals": {
                        "aws:SourceVpce": [
                            "{ClickHouse VPC ID from your S3 region}",
                            "{ClickHouse VPC ID from your S3 region}",
                            "{ClickHouse VPC ID from your S3 region}"
                        ]
                    }
                }
            }
        ]
}
```

Подробнее о доступе к конечным точкам сервисов ClickHouse Cloud см. в разделе [Cloud IP Addresses](/ru/products/cloud/guides/data-sources/cloud-endpoints-api).