Elementos do arquivo de configuração de replicação - Amazon Simple Storage Service

Elementos do arquivo de configuração de replicação

O Amazon S3 armazena uma configuração de replicação como XML. Se estiver configurando a replicação programaticamente por meio da API REST do Amazon S3, você especificará os vários elementos da configuração de replicação nesse arquivo XML. Se estiver configurando a replicação por meio da AWS Command Line Interface (AWS CLI), especifique a configuração de replicação usando o formato JSON. Com relação a exemplos de JSON, consulte as demonstrações em Exemplos para configurar a replicação em tempo real.

nota

A versão mais recente do formato XML de configuração da replicação é V2. As configurações de replicação XML V2 são aquelas que contêm o elemento <Filter> para regras e regras que especificam o Controle do tempo de replicação do S3 (S3 RTC).

Para ver a versão da configuração de replicação, você pode usar a operação de API GetBucketReplication. Para obter mais informações, consulte GetBucketReplication na Referência da API do Amazon Simple Storage Service.

Para compatibilidade com versões anteriores, o Amazon S3 continua a permitir o formato de configuração de replicação XML V1. Se você usou o formato de configuração de replicação XML V1, consulte Considerações sobre a compatibilidade com versões anteriores para considerações sobre a compatibilidade com versões anteriores.

No arquivo XML de configuração de replicação, é necessário especificar um perfil do AWS Identity and Access Management (IAM) e uma ou mais regras, conforme mostrado no seguinte exemplo:

<ReplicationConfiguration> <Role>IAM-role-ARN</Role> <Rule> ... </Rule> <Rule> ... </Rule> ... </ReplicationConfiguration>

O Amazon S3 não pode replicar objetos sem sua permissão. Você concede permissões ao Amazon S3 com o perfil do IAM especificado na configuração de replicação. O Amazon S3 assume esse perfil do IAM para replicar objetos em seu nome. Primeiro você precisa fornecer as permissões necessárias à função do IAM. Para obter mais informações sobre como gerenciar permissões, consulte Configurar permissões para replicação em tempo real.

Você adiciona apenas uma regra na configuração da replicação nos seguintes cenários:

  • Você quer replicar todos os objetos.

  • Você quer replicar apenas um subgrupo de objetos. Você identifica o subgrupo do objeto adicionando um filtro à regra. No filtro, você especifica um prefixo de chaves do objeto, tags ou uma combinação de ambos, de maneira a identificar o subgrupo de objetos aos quais a regra se aplica. Os filtros têm como alvo objetos que correspondem aos valores exatos que você especifica.

Se quiser replicar subgrupos de objetos diferentes, adicione várias regras em uma configuração de replicação. Em cada regra, você especifica um filtro que seleciona um subgrupo diferente. Por exemplo, talvez você queira replicar objetos com os prefixos de chaves tax/ ou document/. Para fazer isso, você adiciona duas regras, uma que especifica o filtro de prefixo das chaves tax/ e outro que especifica o prefixo das chaves document/. Consulte mais informações sobre prefixos de chave de objeto em Organizar objetos usando prefixos.

As seções a seguir fornecem informações adicionais.

Configuração da regra básica

Cada regra deve incluir o status e a prioridade da regra. A regra também precisa indicar se os marcadores de exclusão devem ser replicados.

  • O elemento <Status> indica se a regra está habilitada ou desabilitada usando os valores Enabled ou Disabled. Se uma regra estiver desabilitada, o Amazon S3 não executará as ações especificadas nela.

  • O elemento <Priority> indica qual regra tem precedência sempre que duas ou mais regras de replicação entram em conflito. O Simple Storage Service (Amazon S3) tenta replicar objetos de acordo com todas as regras de replicação. Porém, se houver duas ou mais regras com o mesmo bucket de destino, os objetos serão replicados de acordo com a regra com a prioridade mais alta. Quanto maior o número, maior a prioridade.

  • O elemento <DeleteMarkerReplication> indica se os marcadores de exclusão devem ser replicados usando os valores Enabled ou Disabled.

Na configuração o elemento <Destination>, é necessário fornecer o nome do bucket ou buckets de destino onde você deseja que o Amazon S3 replique objetos.

O exemplo a seguir mostra os requisitos mínimos para uma regra da V2. Para compatibilidade com versões anteriores, o Amazon S3 continua a oferecer compatibilidade com o formato XML V1. Para ter mais informações, consulte Considerações sobre a compatibilidade com versões anteriores.

... <Rule> <ID>Rule-1</ID> <Status>Enabled-or-Disabled</Status> <Filter> <Prefix></Prefix> </Filter> <Priority>integer</Priority> <DeleteMarkerReplication> <Status>Enabled-or-Disabled</Status> </DeleteMarkerReplication> <Destination>       <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> <Rule> ... </Rule> ... ...

Você também pode especificar outras opções de configuração. Por exemplo: você pode optar pelo uso de uma classe de armazenamento para réplicas de objetos diferentes da classe do objeto de origem.

Opcional: Especificação de um filtro

Para escolher um subgrupo de objetos aos quais a regra se aplique, adicione um filtro opcional. Você pode filtrar pelo prefixo das chaves do objeto, as etiquetas do objeto ou uma combinação de ambos. Se você filtrar tanto pelo prefixo das chaves quanto pelas etiquetas do objeto, o Amazon S3 combinará os filtros usando o operador lógico AND. Em outras palavras, a regra se aplica ao subgrupo de objetos com as etiquetas e o prefixo de chave específicos.

Filtro baseado no prefixo da chave de objeto

Para especificar uma regra com um filtro baseado no prefixo de chaves de um objeto, use o XML a seguir. É possível especificar apenas um prefixo por regra.

<Rule> ... <Filter> <Prefix>key-prefix</Prefix> </Filter> ... </Rule> ...
Filtrar com base em tags de objeto

Para especificar uma regra com um filtro baseado nas tags do objeto, use o XML a seguir. Você pode especificar uma ou mais tags de objeto.

<Rule> ... <Filter> <And> <Tag> <Key>key1</Key> <Value>value1</Value> </Tag> <Tag> <Key>key2</Key> <Value>value2</Value> </Tag> ... </And> </Filter> ... </Rule> ...
Filtrar com um prefixo de chave e tags de objeto

Para especificar um filtro de regra com uma combinação de um prefixo de chaves e tags de objeto, use o XML a seguir. Você envolve esses filtros em um elemento pai <And>. O Amazon S3 executa uma operação lógica AND para combinar esses filtros. Em outras palavras, a regra se aplica ao subgrupo de objetos com as etiquetas e o prefixo de chave específicos.

<Rule> ... <Filter> <And> <Prefix>key-prefix</Prefix> <Tag> <Key>key1</Key> <Value>value1</Value> </Tag> <Tag> <Key>key2</Key> <Value>value2</Value> </Tag> ... </Filter> ... </Rule> ...
nota
  • Se você especificar uma regra com um elemento <Filter> vazio, a regra será aplicada a todos os objetos do bucket.

  • Ao usar regras de replicação baseadas em etiquetas com replicação em tempo real, novos objetos precisam ser marcados com a etiqueta da regra de replicação correspondente na operação PutObject. Caso contrário, os objetos não serão replicados. Se os objetos forem marcados após a operação PutObject, esses objetos também não serão replicados.

    Para replicar objetos que foram marcados após a operação PutObject, use a funcionalidade Replicação em Lote do S3. Para obter mais informações sobre replicação em lote, consulte Replicar objetos existentes.

Configurações adicionais de destino

Na configuração de destino, especifique o bucket onde você quer que o Amazon S3 replique objetos. Você pode definir configurações para replicar objetos de um bucket de origem para um bucket de destino.

... <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> ...

Você pode adicionar as seguintes opções no elemento <Destination>.

Especificar classe de armazenamento

Você pode especificar a classe de armazenamento para as réplicas do objeto. Por padrão, o Amazon S3 usa a classe de armazenamento do objeto de origem para criar as réplicas do objeto.

... <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> <StorageClass>storage-class</StorageClass> </Destination> ...

Adicionar vários buckets de destino

Você pode adicionar vários buckets de destino em uma única configuração de replicação, como segue.

... <Rule> <ID>Rule-1</ID> <Status>Enabled-or-Disabled</Status> <Priority>integer</Priority> <DeleteMarkerReplication> <Status>Enabled-or-Disabled</Status> </DeleteMarkerReplication> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket1</Bucket> </Destination> </Rule> <Rule> <ID>Rule-2</ID> <Status>Enabled-or-Disabled</Status> <Priority>integer</Priority> <DeleteMarkerReplication> <Status>Enabled-or-Disabled</Status> </DeleteMarkerReplication> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket2</Bucket> </Destination> </Rule> ...

Especificar parâmetros diferentes para cada regra de replicação com vários buckets de destino

Ao adicionar vários buckets de destino em uma única configuração de replicação, você pode especificar parâmetros diferentes para cada regra de replicação, da seguinte forma.

... <Rule> <ID>Rule-1</ID> <Status>Enabled-or-Disabled</Status> <Priority>integer</Priority> <DeleteMarkerReplication> <Status>Disabled</Status> </DeleteMarkerReplication> <Metrics> <Status>Enabled</Status> <EventThreshold> <Minutes>15</Minutes> </EventThreshold> </Metrics> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket1</Bucket> </Destination> </Rule> <Rule> <ID>Rule-2</ID> <Status>Enabled-or-Disabled</Status> <Priority>integer</Priority> <DeleteMarkerReplication> <Status>Enabled</Status> </DeleteMarkerReplication> <Metrics> <Status>Enabled</Status> <EventThreshold> <Minutes>15</Minutes> </EventThreshold> </Metrics> <ReplicationTime> <Status>Enabled</Status> <Time> <Minutes>15</Minutes> </Time> </ReplicationTime> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket2</Bucket> </Destination> </Rule> ...

Alterar a propriedade da réplica

Quando os buckets de origem e de destino não pertencem às mesmas contas, você pode alterar a propriedade da réplica para a Conta da AWS que for a proprietária do bucket de destino. Para fazer isso, adicione o elemento <AccessControlTranslation>. Esse elemento assume o valor de Destination.

... <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> <Account>destination-bucket-owner-account-id</Account> <AccessControlTranslation> <Owner>Destination</Owner> </AccessControlTranslation> </Destination> ...

Se você não adicionar o elemento <AccessControlTranslation> à configuração de replicação, as réplicas pertencerão à mesma Conta da AWS que for a proprietária do objeto de origem. Para ter mais informações, consulte Alterar o proprietário da réplica.

Ativar o controle do tempo de replicação do S3

Você pode habilitar o Controle do tempo de replicação do S3 (S3 RTC) na configuração de replicação. O S3 RTC replica a maioria dos objetos em segundos e 99,99 por cento dos objetos em 15 minutos (baseado em um acordo de nível de serviço).

nota

Somente um valor de <Minutes>15</Minutes> é aceito para os elementos <EventThreshold> e <Time>.

... <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> <Metrics> <Status>Enabled</Status> <EventThreshold> <Minutes>15</Minutes> </EventThreshold> </Metrics> <ReplicationTime> <Status>Enabled</Status> <Time> <Minutes>15</Minutes> </Time> </ReplicationTime> </Destination> ...

Para ter mais informações, consulte Atender aos requisitos de conformidade com o Controle do Tempo de Replicação do S3. Consulte exemplos de API em PutBucketReplication na Referência de API do Amazon Simple Storage Service.

Replicar objetos criados com criptografia do lado do servidor com o uso do AWS KMS.

Seu bucket de origem pode conter objetos que foram criados com criptografia no servidor usando as chaves do AWS Key Management Service (AWS KMS) (SSE-KMS). Por padrão, o Amazon S3 não replica esses objetos. Opcionalmente, você pode direcionar o Amazon S3 para replicar esses objetos. Para fazer isso, primeiro opte explicitamente por esse recurso adicionando o elemento <SourceSelectionCriteria>. Depois, forneça a AWS KMS key (para a Região da AWS do bucket de destino) a ser usada para criptografar réplicas de objetos. Os exemplo a seguir mostra como especificar esses elementos.

... <SourceSelectionCriteria> <SseKmsEncryptedObjects> <Status>Enabled</Status> </SseKmsEncryptedObjects> </SourceSelectionCriteria> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> <EncryptionConfiguration> <ReplicaKmsKeyID>AWS KMS key ID to use for encrypting object replicas</ReplicaKmsKeyID> </EncryptionConfiguration> </Destination> ...

Para obter mais informações, consulte Replicar objetos criptografados (SSE-S3, SSE-KMS, DSSE-KMS, SSE-C).

Exemplo de configurações de replicação

Para começar, você pode adicionar os seguintes exemplos de configuração de replicação ao bucket, conforme adequado.

Importante

Para adicionar uma configuração de replicação a um bucket, é preciso ter a permissão iam:PassRole. Com essa permissão, você pode aprovar a função do IAM que concede as permissões de replicação do Amazon S3. Você especifica a função do IAM ao fornecer o nome de recurso da Amazon (ARN) usado no elemento <Role> na configuração de replicação XML. Para obter mais informações, consulte Conceder permissões ao usuário para transmitir uma função a um AWS service (Serviço da AWS) no Guia do usuário do IAM.

exemplo 1: Configuração de replicação com uma regra

A configuração de replicação básica a seguir especifica uma regra. A regra especifica uma função do IAM que o Amazon S3 pode assumir e um bucket de destino para único para réplicas de objetos. O valor do elemento <Status> de Enabled indica que a regra está em vigor.

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>

Para escolher um subgrupo de objetos a serem replicados, adicione um filtro. Na configuração a seguir, o filtro especifica um prefixo de chaves do objeto. Essa regra se aplica aos objetos que têm o prefixo Tax/ no nome da chave.

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>Tax/</Prefix> </Filter> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>

Se você especificar o elemento <Filter>, inclua também os elementos <Priority> e <DeleteMarkerReplication>. Neste exemplo, o valor que você define para o elemento <Priority> é irrelevante, pois há somente uma regra.

Na configuração a seguir, o filtro especifica um prefixo e duas tags. A regra se aplica ao subgrupo de objetos com o prefixo de chaves e as tags especificados. Mais especificamente, ela se aplica aos objetos com o prefixo Tax/ nos nomes de chave e às duas tags de objeto especificadas. Neste exemplo, o valor que você define para o elemento <Priority> é irrelevante, pois há somente uma regra.

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <And> <Prefix>Tax/</Prefix> <Tag> <Tag> <Key>tagA</Key> <Value>valueA</Value> </Tag> </Tag> <Tag> <Tag> <Key>tagB</Key> <Value>valueB</Value> </Tag> </Tag> </And> </Filter> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>

Você pode especificar uma classe de armazenamento para as réplicas, da seguinte forma:

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> <StorageClass>storage-class</StorageClass> </Destination> </Rule> </ReplicationConfiguration>

Você pode especificar uma classe de armazenamento à qual o Amazon S3 ofereça suporte.

exemplo 2: Configuração de replicação com duas regras

Na configuração de replicação a seguir, as regras especificam o seguinte:

  • Cada regra filtra em um prefixo de chave diferente para que cada regra se aplique a um subconjunto distinto de objetos. Nesse exemplo, o Simple Storage Service (Amazon S3) replica objetos com os nomes de chave Tax/doc1.pdf e Project/project1.txt, mas não replica objetos com o nome da chave PersonalDoc/documentA.

  • Embora ambas as regras especifiquem um valor para o elemento <Priority>, a prioridade da regra é irrelevante, pois as regras se aplicam a dois grupos distintos de objetos. O exemplo a seguir mostra o que acontece quando aplicamos uma prioridade de regras.

  • A segunda regra especifica uma classe de armazenamento S3 Standard – IA para réplicas de objetos. O Amazon S3 usa a classe de armazenamento especificada para essas réplicas de objetos.

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>Tax</Prefix> </Filter> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> ... </Rule> <Rule> <Status>Enabled</Status> <Priority>2</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>Project</Prefix> </Filter> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> <StorageClass>STANDARD_IA</StorageClass> </Destination> ... </Rule> </ReplicationConfiguration>
exemplo 3: Configuração da replicação com duas regras e prefixos sobrepostos

Nessa configuração, as duas regras especificam filtros com os prefixos das chaves sobrepostos, star/ e starship/. As duas regras se aplicam aos objetos com o nome de chave starship-x. Nesse caso, o Amazon S3 usa a prioridade da regra para determinar qual regra deve ser aplicada. Quanto maior o número, maior a prioridade.

<ReplicationConfiguration> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>star</Prefix> </Filter> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> <Rule> <Status>Enabled</Status> <Priority>2</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>starship</Prefix> </Filter> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>
exemplo 4: Demonstrações de exemplo

Para obter exemplos de demonstrações, consulte Exemplos para configurar a replicação em tempo real.

Para obter mais informações sobre a estrutura XML da configuração de replicação, consulte PutBucketReplication na Referência da API do Amazon Simple Storage Service.

Considerações sobre a compatibilidade com versões anteriores

A versão mais recente do formato XML de configuração da replicação é V2. As configurações de replicação XML V2 são aquelas que contêm o elemento <Filter> para regras e regras que especificam o Controle do tempo de replicação do S3 (S3 RTC).

Para ver a versão da configuração de replicação, você pode usar a operação de API GetBucketReplication. Para obter mais informações, consulte GetBucketReplication na Referência da API do Amazon Simple Storage Service.

Para compatibilidade com versões anteriores, o Amazon S3 continua a permitir o formato de configuração de replicação XML V1. Se você usou o formato de configuração da replicação XML V1, leve em consideração as seguintes questões que afetam a compatibilidade com versões anteriores:

  • O formato XML V2 da configuração de replicação inclui o elemento <Filter> para regras. Com o elemento <Filter>, você pode especificar filtros de objeto com base no prefixo de chaves do objeto, tags ou ambos para colocar dentro do escopo os objetos aos quais a regra se aplica. O formato XML V1 da configuração de replicação permite a filtragem com base apenas no prefixo da chave. Nesse caso, você adiciona o elemento <Prefix> diretamente como elemento-filho do elemento <Rule>, conforme o seguinte exemplo:

    <?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Prefix>key-prefix</Prefix> <Destination> <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>
  • Ao excluir um objeto do bucket de origem sem especificar um ID da versão do objeto, o Amazon S3 adicionar um marcador de exclusão. Se você usar o formato XML V1 da configuração de replicação, o Amazon S3 replicará somente os marcadores de exclusão resultantes das ações do usuário. Em outras palavras: o Amazon S3 só replica o marcador de exclusão se um usuário excluir um objeto. Se um objeto expirado for removido pelo Amazon S3 (como parte de uma ação de ciclo de vida), ele não replicará o marcador de exclusão.

    No formato XML V2 da configuração de replicação, é possível habilitar a replicação do marcador de exclusão para regras que não se baseiam em tags. Para ter mais informações, consulte Replicação de marcadores de exclusão entre intervalos.