> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Acessando dados do S3 com segurança

> Este artigo mostra como os clientes do ClickHouse Cloud podem usar o controle de acesso baseado em função para se autenticar no Amazon Simple Storage Service(S3) e acessar seus dados com segurança.

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>;
};

Este guia mostra como clientes do ClickHouse Cloud podem usar o controle de acesso baseado em função para se autenticar no Amazon Simple Storage Service (S3) e acessar seus dados com segurança.
Antes de partir para a configuração do acesso seguro ao S3, é importante entender como isso funciona. Abaixo está uma visão geral de como os serviços do ClickHouse podem acessar buckets privados do S3 assumindo uma função na conta da AWS dos clientes.

<Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/secures3.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=a93586ecf89dd83ef46eb037010c326e" size="lg" alt="Visão geral do acesso seguro ao S3 com ClickHouse" width="1218" height="674" data-path="images/cloud/security/secures3.webp" />

<br />

Essa abordagem permite que os clientes gerenciem todo o acesso aos seus buckets do S3 em um único lugar (a política do IAM da função assumida), sem precisar revisar todas as políticas de bucket para adicionar ou remover acessos.
Na seção abaixo, você aprenderá a configurar isso.

<div id="obtaining-the-clickhouse-service-iam-role-arn">
  ## Obtenha o ARN da função do IAM do seu serviço ClickHouse
</div>

1. Faça login na sua conta do ClickHouse Cloud.

2. Selecione o serviço ClickHouse para o qual você deseja criar a integração

3. Selecione a guia **Configurações**

4. Role para baixo até a seção **Informações de segurança da rede**, na parte inferior da página

5. Copie o valor de **Service role ID (IAM)** do serviço, como mostrado abaixo.

<Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/secures3_arn.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=1b8e4dd1eccec32d9a7308147df29e06" size="lg" alt="Obtendo o ARN da função do IAM do serviço ClickHouse" border width="1222" height="254" data-path="images/cloud/security/secures3_arn.webp" />

<div id="setting-up-iam-assume-role">
  ## Configurar a assunção de função do IAM
</div>

A assunção de função do IAM pode ser configurada de duas maneiras:

* [Usando uma stack do CloudFormation](#option-1-deploying-with-cloudformation-stack)
* [Criando manualmente uma função do IAM](#option-2-manually-create-iam-role)

<div id="option-1-deploying-with-cloudformation-stack">
  ### Implantação com stack do CloudFormation
</div>

1. Faça login na sua conta da AWS no navegador com um usuário do IAM que tenha permissão para criar e gerenciar função do IAM.

2. Acesse a seguinte [URL do 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) para preencher a stack do CloudFormation.

3. Digite (ou cole) o **Service role ID (IAM)** do seu serviço, obtido anteriormente, no campo intitulado "ClickHouse Instance Roles"
   Você pode colar o ID da service role exatamente como ele aparece no Cloud Console.

4. Digite o nome do seu bucket no campo intitulado "Bucket Names". Se a URL do seu bucket for `https://ch-docs-s3-bucket.s3.eu-central-1.amazonaws.com/clickhouseS3/`, então o nome do bucket será `ch-docs-s3-bucket`.

<Note>
  Não informe o ARN completo do bucket; informe apenas o nome do bucket.
</Note>

5. Configure a stack do CloudFormation. Veja abaixo informações adicionais sobre esses parâmetros.

| Parameter                 |     Default Value    | Description                                                                                                                                                     |
| :------------------------ | :------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RoleName                  | ClickHouseAccess-001 | Nome da nova função do IAM que o ClickHouse Cloud usará para acessar seu bucket do S3.                                                                          |
| Role Session Name         |          \*          | Role Session Name pode ser usado como um segredo compartilhado para proteger ainda mais seu bucket.                                                             |
| ClickHouse Instance Roles |                      | Lista separada por vírgulas de funções do IAM de serviço do ClickHouse que podem usar esta integração segura com S3.                                            |
| Bucket Access             |         Read         | Define o nível de acesso aos buckets informados.                                                                                                                |
| Bucket Names              |                      | Lista separada por vírgulas dos nomes dos buckets aos quais esta função do IAM terá acesso. **Observação:** use o nome do bucket, não o ARN completo do bucket. |

6. Marque a caixa de seleção **I acknowledge that AWS CloudFormation might create IAM resources with custom names.**

7. Clique no botão **Create stack**, no canto inferior direito

8. Verifique se a stack do CloudFormation é concluída sem erro.

9. Selecione a Stack recém-criada e, em seguida, selecione a guia **Outputs** da stack do CloudFormation

10. Copie o valor de **RoleArn** desta integração, que é o que você precisará para acessar seu bucket do S3.

<Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/secures3_output.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=d8590aa21135ba9c750bb579b139d0eb" size="lg" alt="Saída da stack do CloudFormation mostrando o ARN da função do IAM" border width="2020" height="422" data-path="images/cloud/security/secures3_output.webp" />

<div id="option-2-manually-create-iam-role">
  ### Criar função do IAM manualmente
</div>

1. Faça login na sua conta da AWS no navegador com um usuário do IAM que tenha permissão para criar e gerenciar funções do IAM.

2. Acesse o Console do serviço IAM

3. Crie uma nova função do IAM com a seguinte política de IAM e de confiança. Substitua `{ClickHouse_IAM_ARN}` pelo ARN da função do IAM pertencente à sua instância do ClickHouse.

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

**Política de 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. Copie o novo **ARN da função do IAM** após a criação, pois ele é necessário para acessar seu bucket do S3.

<div id="access-your-s3-bucket-with-the-clickhouseaccess-role">
  ## Acesse seu bucket do S3 com a role ClickHouseAccess
</div>

O ClickHouse Cloud permite especificar `extra_credentials` como parte da função de tabela S3.
Abaixo está um exemplo de como executar uma consulta usando a role recém-criada, copiada acima.

```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'))
```

Abaixo está um exemplo de consulta que usa `role_session_name` como segredo compartilhado para consultar dados de um bucket.
Se `role_session_name` não estiver correto, essa operação falhará.

```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>
  Recomendamos que o S3 de origem esteja na mesma região que o seu ClickHouse Cloud Service para reduzir os custos de transferência de dados.
  Para mais informações, consulte [os preços do S3](https://aws.amazon.com/s3/pricing/)
</Note>

<div id="advanced-action-control">
  ## Controle avançado de ações
</div>

Para um controle de acesso mais rigoroso, é possível restringir a política do bucket para aceitar apenas solicitações originadas dos endpoints da VPC do ClickHouse Cloud usando a [condição `aws:SourceVpce`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies-vpc-endpoint.html#example-bucket-policies-restrict-accesss-vpc-endpoint). Para obter os endpoints da VPC da sua região do ClickHouse Cloud, abra um terminal e execute:

```bash theme={null}
# Replace <your-region> with your ClickHouse Cloud region
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'
```

Em seguida, adicione uma regra de negação à política do IAM com os endpoints retornados:

```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}"
                        ]
                    }
                }
            }
        ]
}
```

Para mais detalhes sobre o acesso aos endpoints dos serviços do ClickHouse Cloud, consulte [Endereços IP da Cloud](/docs/pt-BR/products/cloud/guides/data-sources/cloud-endpoints-api).