Skip to main content

Acessar o Object Storage com uma Service Account

Objetivo​

Configure uma Service Account para que aplicações, scripts e pipelines acessem buckets do Object Storage com uma identidade própria, sem usar as credenciais de uma pessoa. Ao criar a API key da Service Account, a Magalu Cloud também gera um par de chaves, o Key Pair ID e o Key Pair Secret, que funciona como as credenciais de acesso S3 em qualquer ferramenta compatível. Ao final deste guia, a Service Account terá acesso apenas aos buckets que você liberar.

Pré-requisitos​

  • CLI da Magalu Cloud instalada e autenticada com uma conta que tenha permissão para gerenciar Service Accounts e permissões no IAM.
  • Um bucket existente no Object Storage, criado pelo tenant ao qual a Service Account vai pertencer.
  • Para acessar o bucket por uma ferramenta compatível com S3, a ferramenta instalada. Neste guia, usamos a AWS CLI.

Como fazer​

O acesso de uma Service Account ao Object Storage depende de três configurações, e todas são necessárias:

ConfiguraçãoOnde é feitaO que define
EscoposAPI key da Service AccountQuais produtos a credencial pode acessar (object-storage.read, object-storage.write)
PermissõesService Account, no IAMQuais ações a Service Account pode executar no Object Storage
Bucket policyBucketQuais buckets e quais operações a Service Account pode acessar

1. Criar a Service Account​

Crie a Service Account informando um nome, o prefixo do e-mail e uma descrição:

mgc iam service-accounts create \
    --name="app-object-storage" \
    --email="app-object-storage" \
    --description="Service Account para acesso ao Object Storage"

O retorno é semelhante a:

description: Service Account para acesso ao Object Storage
email: app-object-storage@COU-0000.sa.idmagalu.com
name: app-object-storage
tenant:
    legal_name: MINHA EMPRESA
    uuid: 00000000-0000-0000-0000-000000000002
uuid: 00000000-0000-0000-0000-000000000001

Anote os valores abaixo, que serão usados nos próximos passos:

  • uuid: o UUID da Service Account.
  • email: o e-mail completo da Service Account, usado na bucket policy.
  • tenant.uuid: o UUID do tenant ao qual a Service Account pertence, também usado na bucket policy.

2. Criar a API key da Service Account​

Crie a API key informando o UUID da Service Account:

mgc iam service-accounts api-keys create \
    --sa-uuid="00000000-0000-0000-0000-000000000001" \
    --name="chave-object-storage"

O retorno é semelhante a:

api_key: 00000000-0000-0000-0000-000000000004
description: ""
end_validity: null
key_pair_id: 00000000-0000-0000-0000-000000000005
key_pair_secret: 00000000-0000-0000-0000-000000000006
name: chave-object-storage
revoked_at: null
revoked_by: null
scopes: []
scopes_pending_approval: []
start_validity: null
uuid: 00000000-0000-0000-0000-000000000003

Os campos que importam para o Object Storage são:

  • key_pair_id: o Key Pair ID, usado como Access Key ID nas ferramentas compatíveis com S3.
  • key_pair_secret: o Key Pair Secret, usado como Secret Access Key nas ferramentas compatíveis com S3.
  • uuid: o UUID da API key, usado no próximo passo.
warning

Guarde o api_key, o Key Pair ID e o Key Pair Secret em um local seguro, como um gerenciador de secrets, logo após a criação. Quem tiver o Key Pair ID e o Key Pair Secret consegue acessar os buckets liberados para a Service Account.

3. Definir os escopos da API key​

Adicione à API key os escopos de leitura e escrita do Object Storage:

mgc iam service-accounts api-keys update \
    --sa-uuid="00000000-0000-0000-0000-000000000001" \
    --apikey-uuid="00000000-0000-0000-0000-000000000003" \
    --scopes="object-storage.read,object-storage.write"

Se a Service Account for apenas ler objetos, informe somente object-storage.read.

4. Conceder as permissões do Object Storage à Service Account​

Conceda à Service Account as permissões de leitura e escrita em buckets:

mgc iam members grants update \
    --uuid="00000000-0000-0000-0000-000000000001" \
    --operation="add" \
    --permissions="objs_bucket_read,objs_bucket_write"

No parâmetro uuid, informe o UUID da Service Account, e não o da API key. Para consultar as permissões disponíveis do Object Storage, execute mgc iam permissions list.

5. Liberar o acesso no bucket com uma bucket policy​

A bucket policy define quais buckets a Service Account pode acessar e quais operações ela pode executar. No Principal, identifique a Service Account no formato <UUID_DO_TENANT>:sa/<EMAIL_DA_SERVICE_ACCOUNT>.

O exemplo abaixo mantém o acesso total do tenant dono do bucket e libera apenas a leitura para a Service Account:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowOwnerFull",
            "Effect": "Allow",
            "Principal": {
                "MGC": ["00000000-0000-0000-0000-000000000002"]
            },
            "Action": "s3:*",
            "Resource": ["meu-bucket", "meu-bucket/*"]
        },
        {
            "Sid": "AllowServiceAccountReadOnly",
            "Effect": "Allow",
            "Principal": {
                "MGC": ["00000000-0000-0000-0000-000000000002:sa/app-object-storage@COU-0000.sa.idmagalu.com"]
            },
            "Action": ["s3:GetObject", "s3:ListBucket"],
            "Resource": ["meu-bucket", "meu-bucket/*"]
        }
    ]
}
warning

Não remova a declaração AllowOwnerFull. Quando um bucket tem bucket policy, o tenant que não estiver incluído nela perde o acesso ao bucket, mesmo sendo o dono.

Substitua:

  • 00000000-0000-0000-0000-000000000002 pelo UUID do seu tenant. Para consultá-lo, execute mgc auth tenant current.
  • app-object-storage@COU-0000.sa.idmagalu.com pelo e-mail da Service Account.
  • meu-bucket pelo nome do bucket.

Para que a Service Account também grave e exclua objetos, adicione s3:PutObject e s3:DeleteObject à lista Action da declaração dela. A lista completa de ações está em Bucket Policy.

Aplique a policy ao bucket:

mgc object-storage buckets policy set \
    --dst="meu-bucket" \
    --policy='{"Version":"2012-10-17","Statement":[{"Sid":"AllowOwnerFull","Effect":"Allow","Principal":{"MGC":["00000000-0000-0000-0000-000000000002"]},"Action":"s3:*","Resource":["meu-bucket","meu-bucket/*"]},{"Sid":"AllowServiceAccountReadOnly","Effect":"Allow","Principal":{"MGC":["00000000-0000-0000-0000-000000000002:sa/app-object-storage@COU-0000.sa.idmagalu.com"]},"Action":["s3:GetObject","s3:ListBucket"],"Resource":["meu-bucket","meu-bucket/*"]}]}'

Para conferir a policy aplicada, execute mgc object-storage buckets policy get informando o bucket na flag --dst.

6. Configurar as credenciais e acessar o bucket​

Use o Key Pair ID e o Key Pair Secret da API key como credenciais de acesso:

A CLI da Magalu Cloud não tem um comando para configurar o Key Pair ID e o Key Pair Secret de uma Service Account. Para usá-los, grave as credenciais nos campos access_key_id e secret_access_key do arquivo auth.yaml do workspace ativo.

warning

As credenciais gravadas substituem as credenciais do Object Storage do workspace ativo. A partir daí, os comandos do Object Storage executados nesse workspace usam a identidade da Service Account.

  1. Confira o nome do workspace ativo com o comando mgc workspace get. Nos exemplos abaixo, o workspace é o default.

  2. Grave o Key Pair ID e o Key Pair Secret no arquivo auth.yaml. Os comandos abaixo substituem os valores dos campos, adicionam os campos se eles não existirem e guardam uma cópia do arquivo original em auth.yaml.bak:

    KEY_PAIR_ID="00000000-0000-0000-0000-000000000005"
    KEY_PAIR_SECRET="00000000-0000-0000-0000-000000000006"
    AUTH_FILE="$HOME/.config/mgc/default/auth.yaml"

    sed -i.bak \
        -e "s|^access_key_id:.*|access_key_id: ${KEY_PAIR_ID}|" \
        -e "s|^secret_access_key:.*|secret_access_key: ${KEY_PAIR_SECRET}|" \
        "$AUTH_FILE"

    grep -q '^access_key_id:' "$AUTH_FILE" || echo "access_key_id: ${KEY_PAIR_ID}" >> "$AUTH_FILE"
    grep -q '^secret_access_key:' "$AUTH_FILE" || echo "secret_access_key: ${KEY_PAIR_SECRET}" >> "$AUTH_FILE"

    Se a variável XDG_CONFIG_HOME estiver definida, o arquivo fica em $XDG_CONFIG_HOME/mgc/default/auth.yaml.

    KEY_PAIR_ID="00000000-0000-0000-0000-000000000005"
    KEY_PAIR_SECRET="00000000-0000-0000-0000-000000000006"
    AUTH_FILE="$HOME/Library/Application Support/mgc/default/auth.yaml"

    sed -i.bak \
        -e "s|^access_key_id:.*|access_key_id: ${KEY_PAIR_ID}|" \
        -e "s|^secret_access_key:.*|secret_access_key: ${KEY_PAIR_SECRET}|" \
        "$AUTH_FILE"

    grep -q '^access_key_id:' "$AUTH_FILE" || echo "access_key_id: ${KEY_PAIR_ID}" >> "$AUTH_FILE"
    grep -q '^secret_access_key:' "$AUTH_FILE" || echo "secret_access_key: ${KEY_PAIR_SECRET}" >> "$AUTH_FILE"
    $KeyPairId = "00000000-0000-0000-0000-000000000005"
    $KeyPairSecret = "00000000-0000-0000-0000-000000000006"
    $AuthFile = "$env:APPDATA\mgc\default\auth.yaml"

    Copy-Item $AuthFile "$AuthFile.bak"
    $Content = Get-Content $AuthFile
    $Content = $Content -replace '^access_key_id:.*', "access_key_id: $KeyPairId"
    $Content = $Content -replace '^secret_access_key:.*', "secret_access_key: $KeyPairSecret"
    if (-not ($Content -match '^access_key_id:')) { $Content += "access_key_id: $KeyPairId" }
    if (-not ($Content -match '^secret_access_key:')) { $Content += "secret_access_key: $KeyPairSecret" }
    Set-Content $AuthFile $Content

    Substitua default pelo nome do workspace ativo, se for outro, e os valores de KEY_PAIR_ID e KEY_PAIR_SECRET (ou $KeyPairId e $KeyPairSecret) pelos valores retornados na criação da API key.

  3. Confira as credenciais configuradas:

    mgc object-storage api-key current

  4. Acesse o bucket informando o nome dele:

    mgc object-storage objects list --dst="meu-bucket"

Para voltar a usar as credenciais anteriores, restaure a cópia auth.yaml.bak no lugar do auth.yaml.

  1. Configure as credenciais em um perfil próprio para a Service Account, para não substituir as credenciais que você já usa:

    aws configure --profile service-account

    Informe os valores solicitados:

    AWS Access Key ID [None]: <KEY_PAIR_ID>
    AWS Secret Access Key [None]: <KEY_PAIR_SECRET>
    Default region name [None]: br-se1
    Default output format [None]: json

  2. Adicione o endpoint da região do bucket ao perfil, no arquivo ~/.aws/config:

    [profile service-account]
    region = br-se1
    endpoint_url = https://br-se1.magaluobjects.com

    Os endpoints de cada região estão em Endpoints S3 Magalu Cloud.

  3. Acesse o bucket informando o nome dele:

    aws s3 ls s3://meu-bucket --profile service-account

O mesmo par de chaves funciona em outras ferramentas compatíveis com S3, como o rclone e o boto3: informe o Key Pair ID como Access Key ID e o Key Pair Secret como Secret Access Key.

info

A Service Account acessa apenas os buckets liberados na bucket policy, mas não os lista. Comandos que listam todos os buckets, como aws s3 ls sem o nome do bucket, não retornam os buckets liberados. Sempre informe o nome do bucket nos comandos.

Detalhes técnicos​

Campo da API keyUso no Object Storage
api_keyAutentica a CLI da Magalu Cloud e as APIs da Magalu Cloud, pela flag --api-key. Não é usado nas ferramentas compatíveis com S3.
key_pair_idKey Pair ID: Access Key ID nas ferramentas compatíveis com S3 e campo access_key_id do auth.yaml da CLI.
key_pair_secretKey Pair Secret: Secret Access Key nas ferramentas compatíveis com S3 e campo secret_access_key do auth.yaml da CLI.
uuidIdentifica a API key nos comandos de gerenciamento, como a definição de escopos.

Perguntas frequentes​

Por que recebo AccessDenied ao acessar o bucket?
Confira as três configurações de acesso. A API key precisa ter o escopo object-storage.read (e object-storage.write, para gravar), a Service Account precisa ter as permissões do Object Storage no IAM e a bucket policy precisa incluir a Service Account no Principal, no formato <UUID_DO_TENANT>:sa/<EMAIL_DA_SERVICE_ACCOUNT>, com as ações e o bucket corretos.

Por que o aws s3 ls não mostra o bucket liberado para a Service Account?
A listagem de buckets não inclui os buckets liberados por bucket policy. Informe o nome do bucket no comando, como em aws s3 ls s3://meu-bucket.

Posso usar a mesma Service Account em vários buckets?
Sim. Inclua a Service Account na bucket policy de cada bucket, ou liste os vários buckets no campo Resource de uma mesma declaração.

Como revogo o acesso da Service Account?
Para revogar o acesso a um bucket específico, remova a declaração da Service Account da bucket policy. Para invalidar a credencial em todos os buckets, exclua a API key da Service Account:

mgc iam service-accounts api-keys delete \
    --sa-uuid="00000000-0000-0000-0000-000000000001" \
    --apikey-uuid="00000000-0000-0000-0000-000000000003"

Próximos passos​