Direktes Upgrade der Hauptversion von Amazon DocumentDB

Amazon DocumentDB stellt neue Versionen von Datenbank-Engines erst nach umfangreichen Tests allgemein zur Verfügung. Sie können wählen, wie und wann Sie Ihre Amazon DocumentDB-Cluster auf die neue Version aktualisieren möchten.

Derzeit unterstützt Amazon DocumentDB drei Hauptversionen: Amazon DocumentDB 3.6, 4.0 und 5.0. Sie können ein direktes Upgrade der Hauptversion (MVU) Ihrer Datenbank durchführen und dabei dieselben Endpunkte, Speicher und Tags der Cluster beibehalten und Ihre Anwendungen weiterhin ohne Änderungen verwenden. Diese Funktion ist in allen Regionen, in denen Amazon DocumentDB 5.0 verfügbar ist, kostenlos verfügbar.

Wichtig

Ihre Amazon DocumentDB-Cluster sind während des direkten Upgrades der Hauptversion nicht verfügbar und Ihre Cluster werden mehrfach neu gestartet. Die Ausfallzeit des Upgrades kann je nach Anzahl der Sammlungen, Indizes, Datenbanken und Instances von Cluster zu Cluster variieren. Wir empfehlen, das Upgrade während Ihres Wartungsfensters oder zu Zeiten mit geringer Auslastung durchzuführen. Sobald Ihr Cluster aktualisiert wurde, können Sie den Cluster nicht mehr auf die vorherige Version herunterstufen. Sie können sich jedoch dafür entscheiden, Ihren Snapshot vor dem Upgrade auf einem neuen Cluster wiederherzustellen.

MVUVoraussetzungen und Einschränkungen

Im Folgenden sind die Voraussetzungen und Einschränkungen für ein direktes Upgrade einer Hauptversion aufgeführt, mit denen Sie möglicherweise vertraut sein müssen und die Sie beachten müssen, bevor Sie das Upgrade durchführen:

• Instanztyp — Amazon DocumentDB 4.0/5.0 unterstützt keine r4.*-Instances. Um mit einem direkten Upgrade der Hauptversion fortzufahren, ändern Sie r4.*-Instances in r5.*-Instances. Weitere Informationen finden Sie unter Ändern einer Amazon DocumentDB DocumentDB-Instance. Informationen zu unterstützten Instances, Unterstützte Instance-Klassen nach Region die auf der Amazon DocumentDB DocumentDB-Engine-Version basieren, finden Sie unter.

• Instance-Betriebssystem-Patches — Für ein direktes Upgrade der Hauptversion ist der neueste Betriebssystem-Patch (OS) erforderlich, um fortzufahren. Bitte wenden Sie alle ausstehenden Betriebssystem-Wartungsmaßnahmen auf die Instanzen an, bevor Sie mit dem direkten Upgrade fortfahren. Weitere Informationen finden Sie unter Betriebssystem-Updates für Amazon DocumentDB.

  Anmerkung

  In manchen Situationen sind Instanz-Betriebssystem-Patches nicht sichtbar, wenn auf Cluster-Ebene Engine-Patches ausstehen. Möglicherweise müssen Sie Engine-Patches auf Clusterebene anwenden, bevor Sie mit der Installation von Instanz-Betriebssystem-Patches und anschließend mit dem direkten Upgrade der Hauptversion fortfahren können. Siehe Durchführen eines Patch-Updates für die Engine-Version eines Clusters.

• Ein direktes Upgrade der Hauptversion ist in allen Regionen verfügbar, in denen Amazon DocumentDB 5.0 verfügbar ist.

• Ein direktes Upgrade der Hauptversion wird mit Amazon DocumentDB 4.0 als Zielversion nicht unterstützt.

• Ab Amazon DocumentDB 4.0 wird „.“ in Benutzernamen nicht mehr unterstützt. Wenn Sie ein Upgrade von Amazon DocumentDB 3.6 auf 5.0 durchführen und einen Benutzernamen haben, der“ . „, bitte erstelle deinen Nutzernamen neu ohne“ . „, bevor Sie mit In-Place MVU fortfahren.

• Ein direktes Upgrade der Hauptversion wird derzeit auf globalen Clustern und Elastic Clustern von Amazon DocumentDB nicht unterstützt.

  Anmerkung

  Um Ihre globalen Cluster zu aktualisieren, löschen Sie Ihre sekundären Cluster aus dem globalen Cluster, konvertieren Sie den primären Cluster in einen regionalen Cluster, führen Sie ein direktes Upgrade der Hauptversion auf dem regionalen (primären) Cluster durch und erstellen Sie dann den globalen Cluster neu, indem Sie sekundäre Cluster mit demselben Namen hinzufügen, um dieselben Endpunkte wie zuvor beizubehalten. Beachten Sie, dass I/O-Gebühren anfallen, während Ihr aktualisierter primärer Cluster Daten auf Ihre neu hinzugefügten sekundären Cluster repliziert. Ausführliche Schritte zum Entfernen von sekundären Clustern vor dem Löschen aus dem globalen Cluster finden Sie unter. Einen Cluster aus einem globalen Amazon DocumentDB-Cluster entfernen

• Wenn Sie über eine große Anzahl von Indizes (> 3.000) verfügen, die in Instances mit hoher Leistung betrieben werden (z. B. t3.medium oder t4g.medium), müssen Sie Ihre primäre Instance auf eine größere Instance skalieren (z. B. mindestens r5.large), um das direkte Upgrade der Hauptversion durchzuführen. Sie können wählen, ob Sie die Instance-Größe verkleinern möchten, sobald Ihr direktes Upgrade der Hauptversion abgeschlossen ist. In der folgenden Tabelle finden Sie die maximale Anzahl von Indizes, die für die Instance-Typen db.t3 und db.t4g für ein direktes Upgrade der Hauptversion unterstützt werden:

  Instance	Maximale Anzahl unterstützter Indizes für In-Place-Anwendungen MVU
  db.t4g.medium	3.000
  db.t3.medium	10 K

Bewährte Methoden für direkte Upgrades von Hauptversionen

Testen Sie direkte Hauptversions-Upgrades mit geklonten Clustern

1. Um Hauptversionsupgrades vor Ort zu testen, empfehlen wir die Verwendung der Schnellklonfunktion, um einen Klon Ihres Zielclusters zu erstellen. Es fallen keine Speicherkosten an, wenn Sie das direkte Upgrade der Hauptversion auf einem geklonten Volume testen, es sei denn, Sie ändern Daten auf dem Cluster. Weitere Informationen zum Klonen von Volumes finden Sie unter. Klonen eines Volumes für einen Amazon DocumentDB-Cluster

2. Um eine realistischere Schätzung der Zeit zu erhalten, die für das direkte Upgrade der Hauptversion benötigt wird, ordnen Sie die Anzahl der Instanzen des geklonten Clusters dem Zielcluster zu.

3. Wir empfehlen, den neu aktualisierten Amazon DocumentDB 5.0-Cluster vollständig auf Funktionsunterschiede zu testen, um sicherzustellen, dass alles wie erwartet funktioniert.

Vor einem direkten Upgrade der Hauptversion

1. Halten Sie eine versionskompatible Cluster-Parametergruppe bereit.

   Verwenden Sie die standardmäßige Cluster-Parametergruppe von Amazon DocumentDB für die neue Engine-Version oder erstellen Sie Ihre eigene benutzerdefinierte Cluster-Parametergruppe für die neue Engine-Version.

   Wenn Sie im Rahmen der Upgrade-Anfrage eine Amazon DocumentDB-Cluster-Parametergruppe zuordnen, wird der Cluster beim direkten Upgrade der Hauptversion automatisch neu gestartet, um die neue Parametergruppe anzuwenden.

2. Stellen Sie sicher, dass Sie die Voraussetzungen für ein direktes Upgrade der Hauptversion erfüllen, wie im Abschnitt Voraussetzungen und Einschränkungen beschrieben.

3. Erstellen Sie einen manuellen Snapshot.

   Der Upgrade-Prozess erstellt während des Upgrades einen Snapshot Ihres Datenbank-Clusters. Es wird dringend empfohlen, vor dem Upgrade-Prozess einen eigenen manuellen Snapshot zu erstellen. Siehe Einen manuellen Cluster-Snapshot erstellen.

   Anmerkung

   Der durch den Upgrade-Prozess erstellte auto Snapshot wird nicht automatisch gelöscht, nachdem das direkte Upgrade der Hauptversion abgeschlossen ist. Für diesen Snapshot fallen keine Gebühren an, solange er sich innerhalb der Aufbewahrungsfrist befindet. Sie können sich dafür entscheiden, diesen Snapshot zu löschen, sobald Sie bestätigt haben, dass Ihr Cluster erfolgreich aktualisiert wurde.

   Der Snapshot ist benannt alspreupgrade-<name>-<version>-<timestamp>.

   

4. Überprüfen Sie, ob Sie bereits ein direktes Upgrade der Hauptversion Ihres Clusters geplant haben.

   Wenn Sie den Cluster geändert und ausgewählt haben, dass er im nächsten Wartungsfenster angewendet wird, ist der Zeitplan für das direkte Upgrade der Hauptversion nicht auf der Konsole sichtbar, Sie können ihn jedoch in der einsehen. CLI Sie können den folgenden Befehl ausführen, um zu überprüfen, ob ein direktes Upgrade der Hauptversion bereits geplant ist:

   aws docdb describe-db-cluster \
   --region $REGION \
   --db-cluster-identifier $CLUSTER_NAME
      
   "PendingModifiedValues": {
       "EngineVersion": "5.0.0"
   },

5. Führen Sie mehrere Testläufe mithilfe von Volume Clone in niedrigeren Umgebungen durch, um den Cluster nach dem direkten Upgrade der Hauptversion auf etwaige Ausführungspläne und funktionale Unterschiede zu testen. Wir empfehlen das Klonen mit derselben Anzahl und Größe von Instanzen, um eine bessere Schätzung der Laufzeit des direkten Upgrades der Hauptversion zu erhalten. Weitere Informationen finden Sie unter Klonen eines Volumes für einen Amazon DocumentDB-Cluster.

6. Wenn der vorherige Schritt erfolgreich war, fahren Sie mit dem direkten Upgrade der Hauptversion auf dem Produktionscluster fort.

Während eines direkten Hauptversions-Upgrades

Sie können den Fortschritt Ihres direkten Hauptversions-Upgrades überwachen, indem Sie Cluster-Wartungsereignisse abonnieren. Wenn das Upgrade abgeschlossen ist, erhalten Sie die Meldung „Die Datenbankcluster-Hauptversion wurde aktualisiert“. Dieses und andere Ereignisse, die während des Upgrades auftreten, werden im Abschnitt „Ereignisse und Tags“ der Cluster-Detailseite in der Amazon DocumentDB DocumentDB-Konsole angezeigt. Der Cluster-Status ändert sich dann von „Upgrade“ zu „Verfügbar“.

Von aus können Sie ausführenCLI, um Ereignisse aws docdb create-event-subscription zu erstellen und aws docdb describe-events den Fortschritt zu überwachen. Sie können auch Ereignisbenachrichtigungen für die oben genannten Ereignisse an Amazon SNS als Ziel einrichten, das per E-Mail, Push-Nachrichten und anderen Methoden benachrichtigt werden soll. Weitere Informationen finden Sie unter Amazon DocumentDB DocumentDB-Veranstaltungen abonnieren.

Ein direktes Upgrade der Hauptversion generiert während des Upgrades die folgenden Ereignisse:

• <cluster-name><timestamp>Aktualisierung läuft: Snapshot vor dem Upgrade wird erstellt [Preupgrade- -]

• Aktualisierung läuft: Volume wird geklont.

• Aktualisierung läuft: Writer wird aktualisiert.

• Aktualisierung läuft: Lesegeräte werden aktualisiert.

• Die Hauptversion des Datenbank-Clusters wurde aktualisiert.

Ereignisse sind auch auf der Konsole unter der Seite Ereignisse sichtbar:

In der können Sie die folgenden Befehle verwenden AWS CLI, um den Fortschritt zu verfolgen:

aws docdb describe-events --source-identifier $CLUSTER_NAME --source-type db-cluster
{
    "Events": [
        {
            "SourceIdentifier": "mycluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster engine version upgrade started.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2023-07-11T23:20:32.444000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:xxxx:cluster:mycluster"
        }
    ]
}

Nach einem direkten Upgrade der Hauptversion

Fügen Sie für Amazon DocumentDB 3.6 dem Cluster ein Tag hinzu, um zu unterscheiden, dass der Cluster von Amazon DocumentDB 3.6 auf Amazon DocumentDB 5.0 aktualisiert wurde und nicht ein neu erstellter Amazon DocumentDB 5.0-Cluster. Weitere Informationen finden Sie im Abschnitt zu den Unterschieden zwischen einem aktualisierten Amazon DocumentDB 5.0-Cluster und einem neuen Amazon DocumentDB 5.0-Cluster.

Erstellen Sie nach Abschluss des direkten Upgrades der Hauptversion einen manuellen Snapshot für den Fall, dass Sie den Status nach dem Upgrade wiederherstellen müssen. Der automatische Snapshot-Vorgang wird fortgesetzt, sobald das direkte Upgrade der Hauptversion abgeschlossen ist. Für den manuellen Snapshot fallen keine Gebühren an, solange er sich innerhalb der Aufbewahrungsfrist befindet.

Um die neuen Funktionen von Amazon DocumentDB 5.0 nutzen zu können, z. B. die clientseitige Verschlüsselung auf Feldebene, empfehlen wir, Ihre Treiberversion auf die MongoDB 5.0-Version zu aktualisieren. API Weitere Informationen finden Sie unter Was ist neu in Amazon DocumentDB 5.0 eine Liste der Funktionen von Amazon DocumentDB 5.0.

Wichtig

Unmittelbar nach der Durchführung eines direkten Hauptversions-Upgrades (MVU) füllt Ihr Amazon DocumentDB 5.0-Cluster die Index-Metadaten erneut auf, auf deren Grundlage die Datenbank-Engine die Abfrageausführungspläne optimiert. Die erwartete Abfrageleistung auf Ihrem Amazon DocumentDB-Cluster wird wieder aufgenommen, nachdem die Neuberechnung der Index-Metadaten abgeschlossen ist. In der Regel ist dieser Vorgang in wenigen Minuten abgeschlossen, kann aber je nach Anzahl der Indizes in Ihrem Cluster bis zu zwei Stunden dauern.

Darüber hinaus kann ein sofortiger Neustart, ein Failover oder ein Hoch-/Herunterskalieren Ihrer Writer-Instance nach der Installation den Berechnungsprozess MVU der Index-Metadaten auf Ihrem Cluster stören. Nach MVU Abschluss der Installation empfehlen wir, solche Änderungen vorzunehmen, sobald Sie die erwartete Abfrageleistung auf Ihrem Amazon DocumentDB 5.0-Cluster beobachtet haben.

Bitte wenden Sie sich an den AWS Support, wenn Sie feststellen, dass dieser vorübergehende Leistungsabfall nach der Installation länger als zwei Stunden anhält. MVU

Testen Sie den aktualisierten Amazon DocumentDB 5.0-Cluster vollständig, um sicherzustellen, dass alles wie erwartet funktioniert.

Anmerkung

Nach der Durchführung eines MVU In-Place-Vorgangs auf einem Amazon DocumentDB-Cluster mit aktivierten Change-Streams werden die vorherigen Change-Stream-Ereignisse beibehalten und können mit oder wieder aufgenommen werden. resumeToken startAtOperationTime Wie bei jedem neu erstellten Amazon DocumentDB-Cluster gelten auch hier die Änderungsstream-Ereignisprotokolle, die älter change_stream_log_retention_duration sind als gelöscht, wenn die Protokollgröße mehr als 51.200 MB beträgt.

Durchführung eines direkten Hauptversions-Upgrades

Using the AWS Management Console

Um ein direktes Upgrade der Hauptversion durchzuführen, verwenden Sie: AWS Management Console

1. Melden Sie sich bei der Amazon DocumentDB DocumentDB-Konsole an AWS Management Consoleund öffnen Sie sie.

2. Wählen Sie in der Cluster-Tabelle den Quell-Cluster aus, klicken Sie auf Aktionen und dann auf Ändern.

   

3. Wählen Sie im Dialogfeld „Cluster ändern“ im Abschnitt „Clusterspezifikationen“ die Zieldatenbankversion (5.0) aus dem Dropdownmenü Engine-Version aus.

   

4. Wählen Sie im Abschnitt Clusteroptionen die entsprechende Cluster-Parametergruppe (default.docdb5.0) oder eine benutzerdefinierte Parametergruppe aus.

   

5. Wenn Sie fertig sind, scrollen Sie nach unten und wählen Sie Weiter.

6. Wählen Sie im Abschnitt Planung von Änderungen Ihren bevorzugten Terminplan aus: sofort anwenden oder im nächsten Wartungsfenster anwenden.

   Wählen Sie Cluster ändern aus.

   

7. Notieren Sie sich in der Clustertabelle den Status Ihres Clusters während der Aktualisierung:

   

Using the AWS CLI

Verwenden Sie die Option modify-db-cluster API mit der gewünschten Engine-Version und dem gewünschten allow-major-version-upgrade Flaggensatz:

aws docdb modify-db-cluster \
 ‐‐db-cluster-identifier $CLUSTER_NAME \
 ‐‐allow-major-version-upgrade \
 ‐‐engine-version 5.0 \
 ‐‐apply-immediately \
 ‐‐cluster-parameter-group $PARAMETER_GROUP \
 ‐‐region $REGION

Unterschiede zwischen auf Amazon DocumentDB 3.6/4.0 auf 5.0 aktualisierten Clustern und neuen Amazon DocumentDB 5.0-Clustern

• Vergleiche von Unterdokumenten für mehrere numerische Datentypen:

  • Wenn der Cluster von Amazon DocumentDB 3.6 migriert wird, erbt er das Verhalten beim Vergleich von Amazon DocumentDB 3.6-Unterdokumenten. Der funktionale Unterschied ist auf numerische Typen (wie Long, Double, Decimal128) in einem Unterdokument beschränkt. {a: {b: {NumberLong(1)}}Ist beispielsweise {a: {b: 1}} in Amazon DocumentDB 3.6 nicht identisch, während sie in Amazon DocumentDB 4.0 und höher als identisch verglichen werden.

  • Dieses Verhalten beim Vergleich von Unterdokumenten gibt es nur in Amazon DocumentDB 3.6 und in Amazon DocumentDB 5.0-Clustern, die von Version 3.6 mithilfe eines direkten Hauptversions-Upgrades aktualisiert wurden. Dies gilt nicht für neu erstellte Amazon DocumentDB 5.0-Cluster.

• Bei einem direkten Upgrade der Hauptversion werden die ursprünglichen Indizes auf dem aktualisierten Cluster beibehalten. Als allgemeine bewährte Methode empfehlen wir, Ihre Indizes zu löschen und neu zu erstellen, nachdem das In-Place-Verfahren erfolgreich abgeschlossen wurde. MVU Mit Amazon DocumentDB 5.0 haben wir die Gesamteffizienz des Garbage-Collection-Prozesses verbessert, insbesondere für Indizes mit niedriger Kardinalität. Wenn Sie in der Vergangenheit Probleme mit der Garbage-Collection auf Ihren Amazon DocumentDB 3.6- oder 4.0-Clustern hatten, profitieren diese Cluster davon, Indizes nach dem Löschen und Neuerstellen von Indizes zu löschen. MVU Die Neuerstellung von Indizes ist keine Voraussetzung. Die Neuerstellung eines Indexes kann jedoch zusätzliche I/O und Zeit erfordern. Weitere Informationen finden Sie unter Amazon DocumentDB DocumentDB-Indizes verwalten.

Anmerkung

Eine Liste der Funktionsunterschiede zwischen Amazon DocumentDB 3.6/4.0 und Amazon DocumentDB 5.0 finden Sie unter. Amazon DocumentDB DocumentDB-Kompatibilität mit MongoDB

Fehlerbehebung bei einem direkten Upgrade der Hauptversion

• Im Falle eines Fehlers versucht das direkte Upgrade der Hauptversion, das Upgrade rückgängig zu machen, um den letzten Betriebszustand des Clusters vor dem Start des Upgrades anzunehmen. Ein erfolgreicher Rollback generiert ein Ereignis: „Der Datenbank-Cluster befindet sich in einem Zustand, der nicht aktualisiert werden kann: Der DocumentDB-Cluster befindet sich in einem Zustand, in dem das Upgrade der Hauptversion nicht erfolgreich abgeschlossen werden kann.“ An diesem Punkt sollten Sie sich an das AWS Support-Team wenden, um das Problem zu beheben und das Versionsupgrade erneut zu versuchen. Sie können Ihren Workload wie bisher weiterverwenden. In allen anderen seltenen Fällen, in denen das Upgrade länger als erwartet dauert, wenden Sie sich bitte an das AWS Support-Team, um Unterstützung zu erhalten.

• Sobald die MVU In-Place-Installation erfolgreich abgeschlossen wurde, kann es bei Ihrem aktualisierten Cluster zu vorübergehenden Leistungseinbußen und einer hohen CPU Auslastung für einen kurzen Zeitraum kommen, während der Aktualisierungsprozess der Index-Metadaten ausgeführt wird. Wenn Sie länger als 2 Stunden weiterhin Leistungseinbußen feststellen, wenden Sie sich bitte an den AWS Support.