Migração simples do Amazon S3 para o Cloud Storage

Nesta página, descrevemos como concluir uma migração simples do Amazon Simple Storage Service (Amazon S3) para o Cloud Storage. Em uma migração simples, use as ferramentas e bibliotecas existentes para gerar solicitações REST autenticadas para o Amazon S3 e para enviar solicitações autenticadas para o Cloud Storage.

Migrar do Amazon S3 para o Cloud Storage em um cenário de migração simples

Para fazer solicitações ao Cloud Storage, siga estas etapas:

Depois de fazer essas mudanças, comece a usar suas ferramentas e bibliotecas existentes para enviar solicitações HMAC ao Cloud Storage.

Por exemplo: nas amostras a seguir, demonstramos como listar buckets do Cloud Storage usando o SDK do Amazon S3:

import (
	"context"
	"fmt"
	"io"
	"time"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/credentials"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/s3"
)

func listGCSBuckets(w io.Writer, googleAccessKeyID string, googleAccessKeySecret string) error {
	// googleAccessKeyID := "Your Google Access Key ID"
	// googleAccessKeySecret := "Your Google Access Key Secret"

	// Create a new client and do the following:
	// 1. Change the endpoint URL to use the Google Cloud Storage XML API endpoint.
	// 2. Use Cloud Storage HMAC Credentials.
	sess := session.Must(session.NewSession(&aws.Config{
		Region:      aws.String("auto"),
		Endpoint:    aws.String("https://storage.googleapis.com"),
		Credentials: credentials.NewStaticCredentials(googleAccessKeyID, googleAccessKeySecret, ""),
	}))

	client := s3.New(sess)
	ctx := context.Background()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()
	result, err := client.ListBucketsWithContext(ctx, &s3.ListBucketsInput{})
	if err != nil {
		return fmt.Errorf("ListBucketsWithContext: %w", err)
	}

	fmt.Fprintf(w, "Buckets:")
	for _, b := range result.Buckets {
		fmt.Fprintf(w, "%s\n", aws.StringValue(b.Name))
	}

	return nil
}

import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.Bucket;
import java.util.List;

public class ListGcsBuckets {
  public static void listGcsBuckets(String googleAccessKeyId, String googleAccessKeySecret) {

    // String googleAccessKeyId = "your-google-access-key-id";
    // String googleAccessKeySecret = "your-google-access-key-secret";

    // Create a BasicAWSCredentials using Cloud Storage HMAC credentials.
    BasicAWSCredentials googleCreds =
        new BasicAWSCredentials(googleAccessKeyId, googleAccessKeySecret);

    // Create a new client and do the following:
    // 1. Change the endpoint URL to use the Google Cloud Storage XML API endpoint.
    // 2. Use Cloud Storage HMAC Credentials.
    AmazonS3 interopClient =
        AmazonS3ClientBuilder.standard()
            .withEndpointConfiguration(
                new AwsClientBuilder.EndpointConfiguration(
                    "https://storage.googleapis.com", "auto"))
            .withCredentials(new AWSStaticCredentialsProvider(googleCreds))
            .build();

    // Call GCS to list current buckets
    List<Bucket> buckets = interopClient.listBuckets();

    // Print bucket names
    System.out.println("Buckets:");
    for (Bucket bucket : buckets) {
      System.out.println(bucket.getName());
    }

    // Explicitly clean up client resources.
    interopClient.shutdown();
  }

import boto3  # type: ignore


def list_gcs_buckets(
    google_access_key_id: str, google_access_key_secret: str
) -> List[str]:
    """Lists all Cloud Storage buckets using AWS SDK for Python (boto3)
    Positional arguments:
        google_access_key_id: hash-based message authentication code (HMAC) access ID
        google_access_key_secret: HMAC access secret

    Returned value is a list of strings, one for each bucket name.

    To use this sample:
    1. Create a Cloud Storage HMAC key: https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create
    2. Change endpoint_url to a Google Cloud Storage XML API endpoint.

    To learn more about HMAC: https://cloud.google.com/storage/docs/authentication/hmackeys#overview
    """
    client = boto3.client(
        "s3",
        region_name="auto",
        endpoint_url="https://storage.googleapis.com",
        aws_access_key_id=google_access_key_id,
        aws_secret_access_key=google_access_key_secret,
    )

    # Call GCS to list current buckets
    response = client.list_buckets()

    # Return list of bucket names
    results = []
    for bucket in response["Buckets"]:
        results.append(bucket["Name"])
        print(bucket["Name"])  # Can remove if not needed after development
    return results

Especificar um cabeçalho de projeto

Nas solicitações que exigem a especificação de um projeto, use o cabeçalho x-amz-project-id.

Observe que o Amazon S3 não tem projetos. Portanto, dependendo das ferramentas ou bibliotecas de cliente usadas, especificar um cabeçalho x-amz-project-id pode não ser uma opção.

Usar chaves HMAC

Para usar a API XML do Cloud Storage na migração simples, use as chaves de código de autenticação de mensagem com base em hash (HMAC) do Cloud Storage para as credenciais. Normalmente, é preciso criar uma chave HMAC que esteja associada a uma conta de serviço. No entanto, é possível usar uma conta associada a uma conta de usuário.

Autenticar no cenário de migração simples

Usar o cabeçalho de autorização

Na migração simples, para as operações que exigem autenticação, inclua um cabeçalho de solicitação Authorization do mesmo modo como é feito para solicitações ao Amazon S3. A sintaxe do cabeçalho Authorization na solicitação do Amazon S3 é:

Authorization: AWS4-HMAC-SHA256 Credential=AWS-ACCESS-KEY/CREDENTIAL_SCOPE, SignedHeaders=SIGNED_HEADERS, Signature=SIGNATURE

Em um cenário de migração simples, você só altera o cabeçalho para usar seu ID de acesso HMAC do Cloud Storage e verifica se a Signature anexada é calculada com sua chave secreta HMAC do Cloud Storage:

Authorization: ALGORITHM Credential=GOOG-ACCESS-ID/CREDENTIAL_SCOPE, SignedHeaders=SIGNED_HEADERS, Signature=SIGNATURE

As partes do cabeçalho Authorization são:

• ALGORITHM: o algoritmo de assinatura e a versão usada. Usar AWS4-HMAC-SHA256 indica que você está utilizando uma assinatura HMAC V4 e pretende enviar cabeçalhos x-amz-*. Também é possível usar GOOG4-HMAC-SHA256, que indica que você está usando uma assinatura HMAC V4 e pretende enviar cabeçalhos x-goog-*, ou GOOG4-RSA-SHA256, que indica que você está usando uma assinatura RSA V4 e pretende enviar cabeçalhos x-goog-*.

• GOOG-ACCESS-ID: o ID de acesso identifica a entidade que faz e assina a solicitação. Em uma migração simples, substitua o ID da chave de acesso da Amazon Web Service (AWS) que você usa para acessar o Amazon S3 pelo ID de acesso HMAC do Cloud Storage. Seu ID de acesso HMAC do Cloud Storage começa com GOOG.

• CREDENTIAL_SCOPE: o escopo da credencial, conforme definido na assinatura. Em uma migração simples, não é necessário alterar o escopo da credencial se você estiver usando AWS4-HMAC-SHA256 como valor ALGORITHM.

• SIGNED_HEADERS: uma lista separada por ponto-e-vírgula de nomes de cabeçalhos que precisam ser incluídos para assinar essa solicitação. Todos os cabeçalhos precisam ser em letra minúscula e classificados por código de caractere.

  Veja abaixo um exemplo de string de cabeçalho assinada no estilo do Amazon S3:

  content-type;host;x-amz-date

  Na migração simples, não é necessário fazer qualquer alteração na string de cabeçalho assinada.

• SIGNATURE: a assinatura que permite que a solicitação seja autenticada. Em uma migração simples, substitua as informações da chave de acesso da AWS pelas informações equivalentes da chave HMAC do Cloud Storage.

Exemplo de solicitação de autenticação

Os exemplos a seguir fazem upload de um objeto chamado /europe/france/paris.jpg em um bucket chamado my-travel-maps, aplicam a ACL public-read predefinida e definem um cabeçalho de metadados personalizado para revisores. Veja abaixo uma solicitação para um bucket no Amazon S3:

PUT europe/france/paris.jpg HTTP/1.1
Host: my-travel-maps.s3.amazonaws.com
Date: Mon, 11 Mar 2019 23:46:19 GMT
Content-Length: 888814
Content-Type: image/jpg
x-amz-acl: public-read
x-amz-date:20190311T192918Z
x-amz-meta-reviewer: joe,jane
Authorization: AWS4-HMAC-SHA256 Credential=AWS-ACCESS-KEY/20190311/us-east-1/s3/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-acl;x-amz-date;x-amz-meta-reviewer, Signature=SIGNATURE

Esta é uma solicitação para um bucket no Cloud Storage:

PUT europe/france/paris.jpg HTTP/1.1
Host: my-travel-maps.storage.s3nsapis.fr
Date: Mon, 11 Mar 2019 23:46:19 GMT
Content-Length: 888814
Content-Type: image/jpg
x-amz-acl: public-read
x-amz-date:20190311T192918Z
x-amz-meta-reviewer: joe,jane
Authorization: AWS4-HMAC-SHA256 Credential=GOOG-ACCESS-ID/20190311/us-east-1/s3/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-acl;x-amz-date;x-amz-meta-reviewer, Signature=SIGNATURE

Esta é uma solicitação canônica correspondente que foi criada para a solicitação acima:

PUT
/europe/france/paris.jpg

content-length:888814
content-type:image/jpg
host:my-travel-maps.storage.s3nsapis.fr
x-amz-acl:public-read
x-amz-date:20190311T192918Z
x-amz-meta-reviewer:joe,jane

content-length,content-type,host,x-amz-acl,x-amz-date,x-amz-meta-reviewer
82e3da8b3f35989512e8d428add7eca73ab0e5f36586e66fbad8e1051343cbd2

Esta é a string a ser assinada correspondente, criada para a solicitação:

AWS4-HMAC-SHA256
20190311T192918Z
20190311/us-east-1/s3/aws4_request
73918a5ff373d7a03e406fbf9ea35675396b06fca2af76c27a5c451fa783ef65

A solicitação não forneceu um cabeçalho Content-MD5, portanto, uma string vazia é mostrada na segunda linha da mensagem.

Controle de acesso na migração simples

Para possibilitar as migrações simples, o Cloud Storage aceita ACLs produzidas pelo Amazon S3. Na migração simples, use AWS como o identificador de assinatura, para que o Cloud Storage saiba que receberá a sintaxe XML de ACL do Amazon S3. É necessário garantir que as ACLs do Amazon S3 usadas sejam mapeadas para o modelo de ACLs do Cloud Storage. Por exemplo, se suas ferramentas e bibliotecas usarem a sintaxe de ACL do Amazon S3 para conceder permissão WRITE ao bucket, elas também precisarão conceder permissão READ ao bucket, já que as permissões do Cloud Storage são concêntricas. Não é necessário especificar as duas permissões WRITE e READ ao conceder permissão WRITE usando a sintaxe do Cloud Storage.

O Cloud Storage aceita a sintaxe de ACL do Amazon S3 nos cenários a seguir:

• Na solicitação ao Cloud Storage para recuperar ACLs (por exemplo, uma solicitação de objeto GET ou bucket GET), o Cloud Storage retorna a sintaxe de ACL do Amazon S3.
• Na solicitação ao Cloud Storage para aplicar ACLs (por exemplo, uma solicitação de objeto PUT ou bucket PUT), o Cloud Storage espera receber a sintaxe de ACL do Amazon S3.

O cabeçalho Authorization na migração simples usa AWS para o identificador de assinatura, mas com seu ID de acesso HMAC do Cloud Storage.

Authorization: AWS4-HMAC-SHA256 Credential=GOOG-ACCESS-ID/CREDENTIAL_SCOPE, SignedHeaders=SIGNED_HEADERS, Signature=SIGNATURE

O exemplo a seguir mostra uma solicitação GET ao Cloud Storage para retornar as ACLs de um objeto.

GET europe/france/paris.jpg?acl HTTP/1.1
Host: my-travel-maps.storage.s3nsapis.fr
Date: Thu, 21 Feb 2019 23:50:10 GMT
Content-Type: application/xml
X-Amz-Date: 20190221T235010Z
Authorization: AWS4-HMAC-SHA256 Credential=GOOGMC5PDPA5JLZYQMHQHRAX/20190221/region/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=29088b1d6dfeb2549f6ff67bc3744abb7e45475f0ad60400485805415bbfc534

A resposta à solicitação inclui a ACL usando a sintaxe de ACL do Amazon S3.

<?xml version='1.0' encoding='UTF-8'?>
<AccessControlPolicy>
    <Owner>
        <ID>00b4903a972faa8bcce9382686e9129676f1cd6e5def1f5663affc2ba4652490
        </ID>
        <DisplayName>OwnerName</DisplayName>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
                xsi:type='CanonicalUser'>
                <ID>00b4903a972faa8bcce9382686e9129676f1cd6e5def1f5663affc2ba4652490</ID>
                <DisplayName>UserName</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>

O exemplo a seguir mostra uma solicitação PUT ao Cloud Storage para definir as ACLs de um objeto. O exemplo mostra um corpo de solicitação com a sintaxe de ACL do Amazon S3.

PUT europe/france/paris.jpg?acl HTTP/1.1
Host: my-travel-maps.storage.s3nsapis.fr
Date: Thu, 21 Feb 2019 23:50:10 GMT
Content-Type: application/xml
Content-Length: 337
X-Amz-Date: 20190221T235010Z
Authorization: AWS4-HMAC-SHA256 Credential=GOOGMC5PDPA5JLZYQMHQHRAX/20190221/region/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=29088b1d6dfeb2549f6ff67bc3744abb7e45475f0ad60400485805415bbfc534

<?xml version='1.0' encoding='utf-8'?>
<AccessControlPolicy>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail">
        <EmailAddress>example-service-account@example-project.s3ns-system.iam.gserviceaccount.com</EmailAddress>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Por fim, na migração simples, também é possível usar o identificador de assinatura GOOG1 no cabeçalho Authorization. Nesse caso, é necessário usar a sintaxe de Access Control List do Cloud Storage e garantir que todos os cabeçalhos x-amz-* sejam alterados para x-goog-*. Embora isso seja possível, recomendamos que você escolha uma migração completa para usar todos os benefícios do Cloud Storage.

Compatibilidade da API XML com o Amazon S3

Para discussões sobre a interoperabilidade da API XML, consulte o Stack Overflow usando a tag google-cloud-storage.