Cos'è la replica?

La replica copia gli oggetti appena creati e gli aggiornamenti degli oggetti da un bucket di origine a un bucket di destinazione.

• Solo i nuovi oggetti o le nuove versioni degli oggetti esistenti (creati dopo l'aggiunta della regola di replica al bucket) vengono copiati nel bucket di destinazione. Gli oggetti esistenti possono essere replicati copiandoli su se stessi, creando una nuova versione replicata.
• I metadati dell'oggetto sorgente vengono applicati all'oggetto replicato.
• La replica bidirezionale tra due bucket richiede che le regole siano attive su entrambi i bucket.
• I filtri (composti da prefissi e/o tag) possono essere usati per definire l'ambito della regola di replica in modo che si applichi solo a un sottoinsieme di oggetti. È possibile definire più regole in un singolo criterio e queste regole possono specificare destinazioni diverse. In questo modo, oggetti diversi dello stesso bucket possono essere replicati su destinazioni diverse.

Perché usare la replica?

• Conservare una copia dei dati in un bucket in una posizione geografica diversa.
• Soddisfate le norme di conformità per la sovranità dei dati definendo regole di replica che memorizzano le repliche solo nelle posizioni consentite.
• La replica conserva i metadati degli oggetti, come l'ora dell'ultima modifica, l'ID della versione e così via.
• Gestire la classe di archiviazione e i criteri di ciclo di vita degli oggetti replicati indipendentemente dall'origine, definendo una classe di archiviazione e/o regole di ciclo di vita diverse per il bucket di destinazione. Allo stesso modo, è possibile memorizzare le repliche in un bucket in un'istanza di servizio separata o persino in un account IBM Cloud e controllare in modo indipendente l'accesso alle repliche.

Come iniziare con la replica

Per iniziare, è necessario soddisfare alcuni prerequisiti:

• Impostare il ruolo della piattaforma Writer o Manager sul bucket di origine, oppure un ruolo personalizzato con le azioni di replica appropriate (come cloud-object-storage.bucket.put_replication).
• Non è necessario avere accesso al bucket di destinazione, ma è necessario avere ruoli di piattaforma sufficienti per creare nuovi criteri IAM che consentano al bucket di origine di scrivere sul bucket di destinazione.
• Il bucket di destinazione non deve avere un firewall del bucket legacy abilitato, ma può utilizzare restrizioni basate sul contesto.
• Gli oggetti crittografati con SSE-C non possono essere replicati, anche se la crittografia gestita(SSE-KMS)come Key Protect è pienamente compatibile con la replica.
• Gli oggetti in stato di archiviazione non possono essere replicati.
• Se i bucket di origine e di destinazione si trovano in account diversi di IBM, assicurarsi di creare i bucket in ciascun account.
• Abilitare il versioning su entrambi i bucket di origine e di destinazione.

Poiché il versionamento è un requisito per la replica, è impossibile replicare gli oggetti nei bucket configurati con un criterio Immutable Object Storage.

Utilizzo di un account IBM

Per replicare gli oggetti tra i bucket dello stesso account IBM, procedere come segue:

1. Dopo essersi spostati sul bucket di origine scelto, fare clic sulla scheda Configurazione.
2. Cercare la voce Bucket replication e fare clic sul pulsante Setup replication.
3. Selezionare l'origine della replica e fare clic su Avanti.
4. Selezionare l'istanza e il bucket dai menu a discesa. In alternativa, selezionare il pulsante di opzione su No e incollare il CRN del bucket di destinazione.
5. Fare clic sul pulsante Verifica autorizzazioni.

Ora è necessario concedere al bucket di origine Writer i permessi sul bucket di destinazione. Esistono diversi modi per farlo, ma il più semplice è quello di utilizzare IBM Cloud Shell e la CLI di IBM Cloud.

1. Aprire un IBM Cloud Shell in una nuova finestra o scheda.
2. Copiare il comando IBM Cloud CLI visualizzato nella console di archiviazione oggetti e incollarlo nella nuova shell.
3. Tornare alla finestra o alla scheda di configurazione del bucket e fare nuovamente clic sul pulsante Controlla autorizzazioni.

Ora si creerà una regola di replica.

1. Assicurarsi che il pulsante di opzione Stato della regola sia impostato su Abilitato.
2. Assegnare alla regola un nome e una priorità, nonché eventuali filtri di prefisso o di tag che limiteranno gli oggetti soggetti alla regola di replica.
3. Fai clic su Done.

Utilizzo di diversi account IBM

Per replicare gli oggetti tra i bucket di diversi account IBM, procedere come segue:

1. Impostare un criterio IAM sull'account di destinazione IBM. Per informazioni sulla creazione di un criterio IAM, vedere Cosa sono i criteri IAM e chi può assegnarli.
2. Individuare l'ID dell'account e l'ID dell'istanza di servizio in formato CRN nella pagina di configurazione del bucket.
3. Utilizzando l'interfaccia utente IBM Cloud dell'account di destinazione, fare clic su Gestione>Accesso**(IAM)**.
4. Fare clic su Autenticazione nel pannello di sinistra.
5. Fare clic su Crea per creare una nuova politica IAM.
6. Concedere la configurazione di una pagina di autorizzazione del servizio. Questa è la pagina in cui si arriva dopo aver creato un nuovo criterio IAM.
7. Selezionare Un altro account e fornire l'ID account dell'account di origine.
8. Fornire l'accesso al servizio come Cloud Object Storage.
9. Nell'Ambito di accesso, selezionare Risorse specifiche.
10. Selezionare Istanza di servizio di origine e inserire l'ID dell'istanza di servizio per il bucket di origine.
11. In Target, selezionare Cloud Object Storage per l'accesso al bucket sorgente.
12. Per l'ambito di destinazione, selezionare Risorse specifiche> Istanza di servizio**.
13. Selezionare l'ID dell'istanza di servizio dell'account di destinazione dal menu a discesa.
14. Selezionare il ruolo Object Writer o Writer come richiesto.

Il ruolo di Object writer è sufficiente per abilitare la replica.

Terminologia

Bucket di origine: Il bucket per il quale è configurato un criterio di replica. È l'origine degli oggetti replicati.

Bucket di destinazione: Il bucket definito come destinazione nel criterio di replica del bucket di origine. È la destinazione degli oggetti replicati. Anche detto secchio di "destinazione".

Replica: Il nuovo oggetto creato in un bucket di destinazione a seguito di una richiesta fatta a un bucket di origine.

Cosa viene replicato?

I nuovi oggetti creati tramite CopyObject, PutObject o CompleteMultipartUpload saranno replicati dal bucket di origine al bucket di destinazione. Gli oggetti replicati erediteranno i seguenti campi di metadati dall'oggetto sorgente: Etag, Last Modified Time, Version ID, user-attributes e Tags.

I marcatori di cancellazione saranno replicati se configurati dal criterio di replica.

Gli aggiornamenti dei tag di una versione saranno replicati dal bucket di origine al bucket di destinazione.

I seguenti non sono replicati:

• Azioni avviate da eventi del ciclo di vita
• Oggetti scritti direttamente nell'archivio
• Oggetti ripristinati da un livello di archivio
• Oggetti crittografati tramite SSE-C
• ACL degli oggetti

Utilizzo della replica per la continuità operativa e il disaster recovery

La replica può essere utilizzata per garantire la continuità del servizio in caso di interruzione:

• Assicurarsi che i bucket di origine e di destinazione si trovino in posizioni diverse.
• Verificare che le ultime versioni degli oggetti siano sincronizzate tra i due bucket. Uno strumento come Rclone (il comando rclone check ) può essere utile per verificare la sincronia dalla riga di comando.
• In caso di interruzione, il traffico di un'applicazione può essere reindirizzato al bucket di destinazione.

Coerenza e integrità dei dati

Mentre IBM Cloud Object Storage offre una forte coerenza per tutte le operazioni di IO dei dati, la configurazione dei bucket è eventualmente coerente. Dopo aver abilitato le regole di replica per la prima volta su un bucket, potrebbero essere necessari alcuni istanti affinché la configurazione si propaghi nel sistema e i nuovi oggetti inizino a essere replicati.

Gestione degli errori

Gli errori di replica possono verificarsi per molteplici ragioni, tra cui (a titolo esemplificativo ma non esaustivo) configurazioni errate dei bucket, interruzioni del servizio, interazioni degli utenti con il bucket di destinazione, ecc.

COS dispone di una resilienza integrata che consente di gestire gli errori di replica. Quando si verifica un errore, COS può riprovare per un massimo di 30 giorni. La frequenza dei tentativi può variare a seconda della natura dell'errore. Ad esempio, i tentativi falliti causati da rari errori di I/O possono essere ripetuti nel giro di poche ore, mentre quelli dovuti a configurazioni errate dei bucket da parte degli utenti possono essere ripetuti una volta al giorno. Se un errore non viene risolto entro 30 giorni, il sistema non effettua più tentativi automatici di risoluzione. Tutti i guasti a lungo termine possono essere elencati tramite ListBucketReplicationFailures.

Se desideri riprovare a risolvere errori "stantii" risalenti a più di 30 giorni fa, puoi avviare un nuovo tentativo utilizzando il PutBucketReplicationFailureReattempt.

Azioni IAM

Ci sono nuove azioni IAM associate alla replica.

Eventi Activity Tracker

La replica genera ulteriori eventi.

Per gli eventi cloud-object-storage.bucket-replication.create, i seguenti campi forniscono ulteriori informazioni:

Quando la replica è attiva, le operazioni sugli oggetti possono generare le seguenti informazioni aggiuntive:

È possibile tracciare un oggetto da quando viene scritto sull'origine fino a quando non viene scritto sulla destinazione. Ricercare l'ID richiesta associato alla scrittura dell'oggetto e visualizzare tre eventi:

• Il PUT originale.
• La richiesta di sincronizzazione dall'origine.
• La richiesta PUT sulla destinazione.

Uno di questi tre elementi mancanti indica un errore.

Utilizzo e contabilità

Tutte le repliche sono oggetti e contribuiscono all'utilizzo come qualsiasi altro dato. La replica eseguita correttamente risulta in richieste PUT, GET e HEAD fatturabili, anche se la larghezza di banda utilizzata nel processo di replica non viene fatturata.

La replica genera metriche aggiuntive da utilizzare con IBM Cloud Monitoring:

• ibm_cos_bucket_replication_sync_requests_issued
• ibm_cos_bucket_replication_sync_requests_received

Interazioni

Replica di oggetti esistenti

Una regola di replica può agire solo sugli oggetti scritti dopo che la regola è configurata e applicata a un bucket. Se ci sono oggetti esistenti in un bucket che devono essere replicati, i processi di replica devono essere resi consapevoli dell'esistenza degli oggetti. Ciò può essere facilmente realizzato utilizzando l'operazione PUT copy per copiare gli oggetti su se stessi.

Questo processo reimposterà alcuni metadati dell'oggetto, inclusi i timestamp di creazione. Ciò avrà un impatto sulle politiche del ciclo di vita e su tutti gli altri servizi che utilizzano la data / ora di creazione o di modifica (come le reti di distribuzione dei contenuti). Assicurarsi che tutte le interruzioni che possono derivare dalla reimpostazione dei metadati dell'oggetto siano gestite in maniera appropriata.

Il processo prevede:

1. Creazione di un elenco di tutti gli oggetti in un bucket che devono essere soggetti alle regole di replica,
2. Iterazione su tale elenco, eseguendo un'operazione PUT copy su ciascun oggetto con l'origine identica alla destinazione della richiesta.

Questo esempio replicherà solo la nuova versione dell'oggetto creata dalla richiesta PUT copy. Per replicare tutte le versioni dell'oggetto, è necessario copiare anche ogni singola versione.

Il seguente esempio è scritto in Python, ma l'algoritmo può essere applicato in qualsiasi linguaggio di programmazione o contesto.

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)

Esempi di API REST

I seguenti esempi vengono mostrati utilizzando cURL per facilità d'uso. Le variabili di ambiente vengono utilizzate per rappresentare elementi specifici dell'utente come $BUCKET, $TOKEN e $REGION. Tieni presente che $REGION includerà anche tutte le specifiche del tipo di rete, quindi l'invio di una richiesta a un bucket in us-south utilizzando la rete privata richiederebbe l'impostazione della variabile su 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

Esempi SDK

I seguenti esempi utilizzano gli SDK COS IBM per Python e Node.js, anche se l'implementazione della versione dell'oggetto deve essere completamente compatibile con qualsiasi libreria o strumento S3-compatible che consente l'impostazione di endpoint personalizzati. L'utilizzo di strumenti di terze parti richiede le credenziali HMAC per calcolare le firme AWS V4. Per ulteriori informazioni relative alle credenziali HMAC, consultare la documentazione.

#!/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
});