O que é replicação?

A replicação copia objetos recém-criados e atualizações de objetos de um bucket de origem para um bucket de destino.

• Somente novos objetos ou novas versões dos objetos existentes (criados depois que a regra de replicação foi adicionada ao bucket) são copiados para o bucket de destino. Os objetos existentes podem ser replicados copiando-os sobre si mesmos, criando uma nova versão que é replicada.
• Os metadados do objeto de origem são aplicados ao objeto replicado.
• A replicação bidirecional entre dois buckets exige que as regras estejam ativas em ambos os buckets.
• Os filtros (compostos de prefixos e/ou tags) podem ser usados para que a regra de replicação seja aplicada somente a um subconjunto de objetos. Várias regras podem ser definidas em uma única política e essas regras podem especificar destinos diferentes. Dessa forma, diferentes objetos no mesmo bucket podem ser replicados para diferentes destinos.

Por que usar a replicação?

• Mantenha uma cópia dos dados em um bucket em uma localização geográfica diferente.
• Atenda às normas de conformidade para a soberania dos dados, definindo regras de replicação que armazenam réplicas somente dentro dos locais permitidos.
• Mantenha os dados de produção e de teste sincronizados, pois a replicação retém os metadados do objeto, como a hora da última modificação, o ID da versão e assim por diante.
• Gerencie a classe de armazenamento e as políticas de ciclo de vida dos objetos replicados independentemente da origem, definindo uma classe de armazenamento diferente e/ou regras de ciclo de vida para o bucket de destino. Da mesma forma, você pode armazenar réplicas em um bucket em uma instância de serviço separada ou até mesmo em uma conta IBM Cloud e também controlar independentemente o acesso às réplicas.

Primeiros passos com a replicação

Para começar, aqui estão alguns pré-requisitos que devem ser atendidos:

• Defina a função de plataforma Writer ou Manager no bucket de origem ou uma função personalizada com as ações de replicação apropriadas (como cloud-object-storage.bucket.put_replication) atribuídas.
• Você não precisa ter acesso ao bucket de destino, mas precisa ter funções de plataforma suficientes para criar novas políticas de IAM que permitam que o bucket de origem grave no bucket de destino.
• O bucket de destino não deve ter um firewall de bucket legado ativado, mas pode usar restrições baseadas em contexto.
• Os objetos criptografados usando SSE-C não podem ser replicados, embora a criptografia gerenciada(SSE-KMS), como Key Protect, seja totalmente compatível com a replicação.
• Os objetos em um estado arquivado não podem ser replicados.
• Se os buckets de origem e de destino estiverem em contas IBM diferentes, certifique-se de criar os buckets em cada conta.
• Habilite o controle de versão nos buckets de origem e de destino.

Como o controle de versão é um requisito para a replicação, é impossível replicar objetos em buckets configurados com uma política Immutable Object Storage.

Usando uma conta IBM

Para replicar objetos entre buckets na mesma conta IBM, faça o seguinte:

1. Depois de navegar até o bucket de origem escolhido, clique na guia Configuration (Configuração ).
2. Procure a replicação do Bucket e clique no botão Setup replication (Configurar replicação ).
3. Selecione a fonte de replicação e clique em Avançar.
4. Selecione a instância e o bucket nos menus suspensos. Como alternativa, alterne o botão de opção para Não e cole o CRN do bucket de destino.
5. Clique no botão “Verificar permissões ”.

Agora, você precisará conceder ao bucket de origem as permissões Writer no bucket de destino. Há várias maneiras de fazer isso, mas a mais fácil é usar o IBM Cloud Shell e a CLI do IBM Cloud.

1. Abra o site IBM Cloud Shell em uma nova janela ou guia.
2. Copie o comando IBM Cloud CLI mostrado no console do armazenamento de objetos e cole-o no novo shell.
3. Volte à janela ou aba de configuração do bucket e clique no botão “Verificar permissões” novamente.

Agora você criará uma regra de replicação.

1. Certifique-se de que o botão de rádio de status da regra esteja definido como Ativado.
2. Atribua um nome e uma prioridade à regra, bem como quaisquer filtros de prefixo ou tag que limitem os objetos sujeitos à regra de replicação.
3. Clique em Pronto.

Usando diferentes contas IBM

Para replicar objetos entre buckets em diferentes contas IBM, faça o seguinte:

1. Configure uma política de IAM na conta de destino IBM. Para obter informações sobre como criar uma política de IAM, consulte O que são políticas de IAM e quem pode atribuí-las.

2. Localize o ID da conta e o ID da instância do serviço no formato CRN na página Configuração do Bucket.

3. Usando a interface do usuário IBM Cloud da conta de destino, clique em Manage>Access**(IAM)**.

4. Clique em Authentication (Autenticação ) no painel esquerdo.

5. Clique em “Criar” para criar uma nova política de IAM.

6. Conceder uma configuração de página de autorização de serviço. Esta é a página na qual você é direcionado após criar uma nova política de IAM.

7. Selecione Outra conta e forneça o ID da conta de origem.

8. Fornecer acesso ao serviço como Cloud Object Storage.

9. Em Escopo de acesso, selecione Recursos específicos.

10. Selecione Source Service Instance (Instância de serviço de origem) e insira o ID da instância de serviço do bucket de origem.

11. Em Target (Destino), selecione Cloud Object Storage para o acesso ao bucket de origem.

12. Em Target Scope (Escopo de destino), selecione Recursos específicos>**Service Instance (Instância de serviço).

13. Selecione o ID da instância de serviço da conta de destino no menu suspenso.

14. Selecione a função Object Writer ou Writer, conforme necessário.

    A função de escritor de objetos é suficiente para ativar a replicação.

Terminologia

Bucket de origem: O bucket para o qual uma política de replicação está configurada. É a origem dos objetos replicados.

Compartimento de destino: O bucket definido como o destino na política de replicação do bucket de origem. É o destino dos objetos replicados. Também chamado de balde de "destino".

Réplica: O novo objeto criado em um bucket de destino devido a uma solicitação feita a um bucket de origem.

O que é replicado?

Novos objetos criados usando CopyObject, PutObject, ou CompleteMultipartUpload são replicados do bucket de origem para o bucket de destino. Os objetos replicados herdam os seguintes campos de metadados do objeto de origem: Etag, Last Modified Time, Version ID, user-attributes, e Tags.

Os marcadores de exclusão são replicados se configurados pela política de replicação.

As atualizações nas tags de uma versão são replicadas do bucket de origem para o bucket de destino.

Os itens a seguir não são replicados:

• Ações iniciadas por eventos do ciclo de vida
• Objetos gravados diretamente no arquivo
• Objetos restaurados de uma camada de arquivo
• Objetos criptografados usando SSE-C
• ACLs de objeto

Utilização da replicação para continuidade de negócios e recuperação de desastres

A replicação pode ser usada para fornecer continuidade de serviço em caso de interrupção:

• Certifique-se de que os buckets de origem e de destino estejam em locais diferentes.
• Verifique se as versões mais recentes dos objetos estão sincronizadas entre os dois buckets. Uma ferramenta como o Rclone (o comando rclone check ) pode ser útil para verificar a sincronicidade a partir da linha de comando.
• No caso de uma interrupção, o tráfego de um aplicativo pode ser redirecionado para o bucket de destino.

Consistência e integridade dos dados

Embora o site IBM Cloud Object Storage ofereça uma consistência forte para todas as operações de E/S de dados, a configuração do bucket acaba sendo consistente. Depois de ativar as regras de replicação pela primeira vez em um bucket, pode levar alguns instantes para que a configuração se propague pelo sistema e novos objetos comecem a ser replicados.

Tratamento de erros

Falhas na replicação podem ocorrer por diversos motivos, incluindo (mas não se limitando a) configurações incorretas do bucket, interrupções no serviço e interações do usuário com o bucket de destino.

O Object Storage possui resiliência integrada para lidar com falhas de replicação. Quando ocorre uma falha, Object Storage pode tentar novamente por até 30 dias. A frequência das tentativas pode variar dependendo da natureza da falha. Por exemplo, falhas causadas por erros raros de E/S podem ser repetidas em questão de horas, enquanto falhas decorrentes de configurações incorretas do bucket do usuário podem ser repetidas uma vez por dia. Se uma falha não for resolvida em até 30 dias, o sistema não tentará mais corrigi-la automaticamente. Todas as falhas de longo prazo podem ser listadas usando o método [_ListBucketReplicationFailures_](#replication-apis-list-failures).

Se você desejar tentar novamente falhas “antigas” que ocorreram há mais de 30 dias, é possível acionar uma nova tentativa usando o PutBucketReplicationFailureReattempt.

Ações do IAM

Há novas ações de IAM associadas à replicação.

Eventos do Activity Tracker

A replicação gera eventos adicionais..

Para eventos cloud-object-storage.bucket-replication.create, os campos a seguir fornecem informações extras:

Quando a replicação está ativa, as operações em objetos podem gerar as seguintes informações extras:

É possível rastrear um objeto a partir de quando ele é gravado na origem até ser gravado no destino. Procure o ID de solicitação associado à gravação do objeto e três eventos devem aparecer:

• O PUT original..
• A solicitação de sincronização da origem.
• A solicitação PUT no destino..

Qualquer um desses três ausentes indica uma falha

Uso e contabilidade

Todas as réplicas são objetos em si e contribuem com o uso como qualquer outro dado. A replicação bem-sucedida resulta em solicitações PUT, GET e HEAD faturáveis, embora qualquer largura da banda consumida no processo de réplica não seja faturado

A replicação gera métricas adicionais para uso com IBM Cloud Monitoring:

• ibm_cos_bucket_replication_sync_requests_issued
• ibm_cos_bucket_replication_sync_requests_received

Interações

Replicando objetos existentes

Uma regra de réplica só pode agir em objetos que são gravados após a regra ser configurada e aplicada a um depósito Se houver objetos existentes em um depósito que devem ser replicados, os processos de replicação precisam ser informados sobre a existência dos objetos. Isso pode ser facilmente realizado usando a operação PUT copy para copiar objetos para si mesmos

Esse processo redefine alguns metadados do objeto, incluindo os carimbos de data e hora de criação. Isso afeta as políticas de ciclo de vida e quaisquer outros serviços que utilizem carimbos de data e hora de criação ou modificação (como redes de distribuição de conteúdo). Assegure-se de que quaisquer interrupções que possam surgir da reconfiguração de metadados do objeto sejam tratadas apropriadamente.

O processo envolve:

1. Criando uma lista de todos os objetos em um depósito que devem estar sujeitos a regras de replicação,
2. Iterando sobre essa lista, executando uma operação PUT copy em cada objeto com a origem sendo idêntica ao destino da solicitação

Este exemplo replica apenas a nova versão do objeto criado pela solicitação PUT copy. Para replicar todas as versões do objeto, seria necessário copiar cada versão individualmente também.

O exemplo a seguir é gravado em Python, mas o algoritmo poderia ser aplicado em qualquer linguagem de programação ou contexto

import os
import sys
import ibm_boto3
from ibm_botocore.config import Config
# Create client connection
cos = ibm_boto3.client("s3",
                       ibm_api_key_id=os.environ.get('IBMCLOUD_API_KEY'),
                       ibm_service_instance_id=os.environ['SERVICE_INSTANCE_ID'],
                       config=Config(signature_version="oauth"),
                       endpoint_url=os.environ['US_GEO']
                       )
# Define the bucket with existing objects for replication
bucket = os.environ['BUCKET']
def copy_in_place(BUCKET_NAME):
    print("Priming existing objects in " + bucket + " for replication...")
    paginator = cos.get_paginator('list_objects_v2')
    pages = paginator.paginate(Bucket=bucket)
    for page in pages:
        for obj in page['Contents']:
            key = obj['Key']
            print("  * Copying " + key + " in place...")
            try:
                headers = cos.head_object(
                    Bucket=bucket,
                    Key=key
                    )
                md = headers["Metadata"]
                cos.copy_object(
                    CopySource={
                        'Bucket': bucket,
                        'Key': key
                        },
                    Bucket=bucket,
                    Key=key,
                    TaggingDirective='COPY',
                    MetadataDirective='REPLACE',
                    Metadata=md
                    )
                print("    Success!")
            except Exception as e:
                print("    Unable to copy object: {0}".format(e))
    print("Existing objects in " + bucket + " are now subject to replication rules.")
copy_in_place(bucket)

Exemplos da API REST

Os exemplos a seguir são mostrados usando cURL para facilidade de uso.. Variáveis de ambiente são usadas para representar elementos específicos do usuário, como $BUCKET, $TOKEN e $REGION. Observe que o $REGION também incluiria quaisquer especificações de tipo de rede, portanto, enviar uma solicitação para um depósito no us-south usando a rede privada exigiria a configuração da variável como private.us-south.

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN' \
     -H 'Content-MD5: exuBoz2kFBykNwqu64JZuA==' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
            <Rule>
              <ID>SimpleReplication</ID>
              <Priority>1</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Disabled</Status>
              </DeleteMarkerReplication>
              <Filter/>
              <Destination>
                <Bucket>$DESTINATION_CRN</Bucket>
              </Destination>
          	</Rule>
          </ReplicationConfiguration>'

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN' \
     -H 'Content-MD5: exuBoz2kFBykNwqu64JZuA==' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
            <Rule>
              <ID>ProjectA</ID>
              <Priority>10</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Enabled</Status>
              </DeleteMarkerReplication>
              <Filter>
                <Prefix>project_a/</prefix>
              </Filter>
              <Destination>
                <Bucket>$DESTINATION_CRN_A</Bucket>
              </Destination>
          	</Rule>
            <Rule>
              <ID>ProjectB</ID>
              <Priority>5</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Enabled</Status>
              </DeleteMarkerReplication>
              <Filter>
                <Prefix>project_b/</prefix>
              </Filter>
              <Destination>
                <Bucket>$DESTINATION_CRN_B</Bucket>
              </Destination>
          	</Rule>
            <Rule>
              <ID>AcmeCorp</ID>
              <Priority>20</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Enabled</Status>
              </DeleteMarkerReplication>
              <Filter>
                <Tag>
                  <Key>Client</Key>
                  <Value>ACME</Value>
                </Tag>
              </Filter>
              <Destination>
                <Bucket>$DESTINATION_CRN_C</Bucket>
              </Destination>
          	</Rule>
          </ReplicationConfiguration>'

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN'

<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Rule>
    <ID>SimpleReplication</ID>
    <Status>ENABLED</Status>
    <DeleteMarkerReplication>
      <Status>DISABLED</Status>
    </DeleteMarkerReplication>
    <Destination>
      <Bucket>crn:v1:bluemix:public:cloud-object-storage:global:a/9978e07eXXXXXXXX66c89c428028654:ef1c725e-XXXX-4967-bcc1-734c03a2b846:bucket:replication-destination</Bucket>
    </Destination>
    <Priority>1</Priority>
    <Filter/>
  </Rule>
</ReplicationConfiguration>

curl -X "DELETE" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN'

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?ibm-replication-failures" \
     -H 'Authorization: bearer $TOKEN'

<ListReplicationFailureResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>example</Name>
    <FirstSyncAttemptedBefore>2025-12-15T00:00:00.000Z</FirstSyncAttemptedBefore>
    <MaxKeys>10</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <EncodingType>false</EncodingType>
    <KeyCount>2</KeyCount>
    <Contents>
        <Key>test-obj+*1765434016787</Key>
        <VersionId>00000000-0000-0000-0000-019b0c114413</VersionId>
        <SyncType>Content</SyncType>
        <FirstSyncAttempted>2025-12-11T06:20:16.787Z</FirstSyncAttempted>
        <LastSyncAttempted>2025-12-11T06:20:16.787Z</LastSyncAttempted>
        <SyncFailureCause>Versioning disabled on destination bucket</SyncFailureCause>
    </Contents>
    <Contents>
        <Key>test-obj+*1765434016786</Key>
        <VersionId>00000000-0000-0000-0000-019b0c114412</VersionId>
        <SyncType>Content</SyncType>
        <FirstSyncAttempted>2025-12-11T06:20:16.786Z</FirstSyncAttempted>
        <LastSyncAttempted>2025-12-11T06:20:16.786Z</LastSyncAttempted>
        <SyncFailureCause>Replication operation not authorized on target bucket</SyncFailureCause>
    </Contents>
</ListReplicationFailureResult>

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?ibm-replication-reattempt" \
     -H 'Authorization: bearer $TOKEN'

HTTP/1.1 204 No Content
Connection: close
...
x-ibm-replication-reattempt-scheduled-time: Fri, 12 Dec 2025 00:00:00 GMT

Exemplos SDK

Os exemplos a seguir utilizam os SDKs IBM Cloud Object Storage para Python e Node.js, embora a implementação do controle de versão de objetos deva ser totalmente compatível com qualquer biblioteca ou ferramenta S3-compatible que permita a configuração de endpoints personalizados. O uso de ferramentas de terceiros requer credenciais HMAC para calcular assinaturas do AWS V4. Para obter mais informações sobre credenciais HMAC, consulte a documentação.

#!/usr/bin/env python3
import ibm_boto3
from ibm_botocore.config import Config
from ibm_botocore.exceptions import ClientError
# Define constants
API_KEY = os.environ.get('IBMCLOUD_API_KEY')
SERVICE_INSTANCE = os.environ.get('SERVICE_INSTANCE_ID')
ENDPOINT = os.environ.get('ENDPOINT')
BUCKET = "my-replication-bucket" # The bucket that will enable replication.
# Create resource client with configuration info pulled from environment variables.
cosClient = ibm_boto3.client("s3",
                         ibm_api_key_id=API_KEY,
                         ibm_service_instance_id=SERVICE_INSTANCE,
                         config=Config(signature_version="oauth"),
                         endpoint_url=ENDPOINT
                         )
response = cosClient.put_bucket_versioning(
    Bucket=BUCKET,
    ReplicationConfiguration={
        'Rules': [
            {
                'ID': 'string',
                'Priority': 123,
                'Filter': {
                    'Prefix': 'string',
                    'Tag': {
                        'Key': 'string',
                        'Value': 'string'
                    },
                    'And': {
                        'Prefix': 'string',
                        'Tags': [
                            {
                                'Key': 'string',
                                'Value': 'string'
                            },
                        ]
                    }
                },
                'Status': 'Enabled'|'Disabled',
                'Destination': {
                    'Bucket': 'string',
                },
                'DeleteMarkerReplication': {
                    'Status': 'Enabled'|'Disabled'
                }
            },
        ]
    }
)

resp = cosClient.list_object_versions(Prefix='some-prefix', Bucket=BUCKET)

const IBM = require('ibm-cos-sdk');
var config = {
    endpoint: '<endpoint>',
    apiKeyId: '<api-key>',
    serviceInstanceId: '<resource-instance-id>',
};
var cos = new IBM.S3(config);
var params = {
  Bucket: 'STRING_VALUE', /* required */
  ReplicationConfiguration: { /* required */
    Role: 'STRING_VALUE', /* required */
    Rules: [ /* required */
      {
        Destination: { /* required */
          Bucket: 'STRING_VALUE', /* required */
        },
        Status: Enabled | Disabled, /* required */
        Filter: {
          And: {
            Prefix: 'STRING_VALUE',
            Tags: [
              {
                Key: 'STRING_VALUE', /* required */
                Value: 'STRING_VALUE' /* required */
              },
              /* more items */
            ]
          },
          Prefix: 'STRING_VALUE',
          Tag: {
            Key: 'STRING_VALUE', /* required */
            Value: 'STRING_VALUE' /* required */
          }
        },
        ID: 'STRING_VALUE',
        Prefix: 'STRING_VALUE',
        Priority: 'NUMBER_VALUE',
        }
      }
    ]
  },
  ContentMD5: 'STRING_VALUE',
};
cos.putBucketReplication(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});