diff --git a/spanner/backups/src/spanner_backups/restore_backup_with_mr_cmek.py b/spanner/backups/src/spanner_backups/restore_backup_with_mr_cmek.py new file mode 100644 index 0000000000..75dda5f061 --- /dev/null +++ b/spanner/backups/src/spanner_backups/restore_backup_with_mr_cmek.py @@ -0,0 +1,131 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# [START spanner_restore_backup_with_mr_cmek] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def restore_backup_with_mr_cmek( + project_id: str, + instance_id: str, + new_database_id: str, + backup_id: str, + kms_key_names: list[str], +) -> None: + """Restores a Spanner backup into a multi-region CMEK database. + + Args: + project_id: The Google Cloud project ID. + instance_id: The multi-region Spanner instance ID. + new_database_id: The new target database ID. + backup_id: The source backup ID on the multi-region instance. + kms_key_names: Regional Cloud KMS CryptoKey resource paths. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + parent = client.instance_path(project_id, instance_id) + backup_path = client.backup_path(project_id, instance_id, backup_id) + enc_type = ( + spanner_admin_database_v1.RestoreDatabaseEncryptionConfig.EncryptionType.CUSTOMER_MANAGED_ENCRYPTION + ) + encryption_config = spanner_admin_database_v1.RestoreDatabaseEncryptionConfig( + encryption_type=enc_type, + kms_key_names=kms_key_names, + ) + request = spanner_admin_database_v1.RestoreDatabaseRequest( + parent=parent, + database_id=new_database_id, + backup=backup_path, + encryption_config=encryption_config, + ) + + try: + operation = client.restore_database(request=request) + print( + f"Waiting for multi-region CMEK restore of '{backup_id}' to " + f"'{new_database_id}'..." + ) + restored = operation.result(timeout=1600) + except exceptions.AlreadyExists as err: + print( + f"error: target database '{new_database_id}' already exists on " + f"instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + except TimeoutError as err: + print( + f"error: timed out waiting for the operation on " + f"new database '{new_database_id}' " + f"to complete; the operation may still be running: {err}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: failed to restore multi-region CMEK database " + f"'{new_database_id}' from backup '{backup_id}': {err.message}", + file=sys.stderr, + ) + else: + key_count = len(restored.encryption_config.kms_key_names) + print(f"Resource ID: {new_database_id}") + print(f"Configured KMS Keys: {key_count}") + print(f"Restored From Backup: {backup_id}") + + +# [END spanner_restore_backup_with_mr_cmek] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Restore a Spanner backup into a multi-region CMEK database." + ) + parser.add_argument( + "--project-id", + default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"), + ) + parser.add_argument( + "--instance-id", + default=os.environ.get("SPANNER_MR_INSTANCE_ID", "example-mr-instance"), + ) + parser.add_argument( + "--new-database-id", + default="example-restored-mr-db", + ) + parser.add_argument( + "--backup-id", + default=os.environ.get("SPANNER_MR_BACKUP_ID", "example-mr-backup"), + ) + parser.add_argument( + "--kms-key-names", + default=os.environ.get( + "SPANNER_MR_KMS_KEY_NAMES", + "projects/example-project-id/locations/us-central1/keyRings/example-ring/cryptoKeys/example-key," + "projects/example-project-id/locations/us-east1/keyRings/example-ring/cryptoKeys/example-key," + "projects/example-project-id/locations/us-east4/keyRings/example-ring/cryptoKeys/example-key", + ), + ) + args = parser.parse_args() + + restore_backup_with_mr_cmek( + project_id=args.project_id, + instance_id=args.instance_id, + new_database_id=args.new_database_id, + backup_id=args.backup_id, + kms_key_names=[k.strip() for k in args.kms_key_names.split(",") if k.strip()], + ) diff --git a/spanner/backups/tests/restore_backup_with_mr_cmek_test.py b/spanner/backups/tests/restore_backup_with_mr_cmek_test.py new file mode 100644 index 0000000000..9ed283f17e --- /dev/null +++ b/spanner/backups/tests/restore_backup_with_mr_cmek_test.py @@ -0,0 +1,156 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import runpy +from unittest import mock +import uuid + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 +import pytest +from spanner_backups import restore_backup_with_mr_cmek + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-mr-instance" +NEW_DB_ID = "example-restored-mr-db" +BACKUP_ID = "example-mr-backup" +MR_KEYS = [ + f"projects/{PROJECT_ID}/locations/{loc}/keyRings/example-ring/cryptoKeys/example-key" + for loc in ("us-central1", "us-east1", "us-east4") +] +ADMIN_CLIENT = "google.cloud.spanner_admin_database_v1.DatabaseAdminClient" + + +def _setup_admin(mock_client_class: mock.MagicMock) -> None: + client = mock_client_class.return_value + client.instance_path.return_value = f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + client.backup_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/backups/{BACKUP_ID}" + ) + db_pb = mock.MagicMock() + db_pb.encryption_config.kms_key_names = MR_KEYS + client.restore_database.return_value.result.return_value = db_pb + + +@mock.patch(ADMIN_CLIENT) +def test_restore_backup_with_mr_cmek_success( + mock_client_class: mock.MagicMock, capsys: pytest.CaptureFixture[str] +) -> None: + _setup_admin(mock_client_class) + + restore_backup_with_mr_cmek.restore_backup_with_mr_cmek( + PROJECT_ID, INSTANCE_ID, NEW_DB_ID, BACKUP_ID, MR_KEYS + ) + + out, err = capsys.readouterr() + assert f"Resource ID: {NEW_DB_ID}" in out + assert "Configured KMS Keys: 3" in out + assert PROJECT_ID not in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + (TimeoutError("deadline"), "error: timed out waiting for the operation"), + ( + exceptions.AlreadyExists("dup"), + "error: target database 'example-restored-mr-db' already exists", + ), + ( + exceptions.FailedPrecondition("kms"), + "error: failed to restore multi-region CMEK database", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_restore_backup_with_mr_cmek_errors( + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + _setup_admin(mock_client_class) + mock_client_class.return_value.restore_database.side_effect = error + + restore_backup_with_mr_cmek.restore_backup_with_mr_cmek( + PROJECT_ID, INSTANCE_ID, NEW_DB_ID, BACKUP_ID, MR_KEYS + ) + + _out, err = capsys.readouterr() + assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + + +@mock.patch(ADMIN_CLIENT) +def test_restore_backup_with_mr_cmek_cli_entrypoint( + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + _setup_admin(mock_client_class) + monkeypatch.setattr( + "sys.argv", + [ + "restore_backup_with_mr_cmek.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--new-database-id", + NEW_DB_ID, + "--backup-id", + BACKUP_ID, + "--kms-key-names", + ",".join(MR_KEYS), + ], + ) + + runpy.run_module("spanner_backups.restore_backup_with_mr_cmek", run_name="__main__") + + assert "Configured KMS Keys: 3" in capsys.readouterr().out + + +@conftest.live_only +def test_restore_backup_with_mr_cmek_live(capsys: pytest.CaptureFixture[str]) -> None: + required = ( + "SPANNER_MR_INSTANCE_ID", + "SPANNER_MR_BACKUP_ID", + "SPANNER_MR_KMS_KEY_NAMES", + ) + missing = [name for name in required if not os.environ.get(name)] + if missing: + pytest.skip(f"Set {', '.join(missing)} to run this live test.") + mr_inst = os.environ["SPANNER_MR_INSTANCE_ID"] + mr_bkp = os.environ["SPANNER_MR_BACKUP_ID"] + mr_keys = [k for k in os.environ["SPANNER_MR_KMS_KEY_NAMES"].split(",") if k] + admin = spanner_admin_database_v1.DatabaseAdminClient() + new_db = f"example-rmr-{uuid.uuid4().hex[:6]}" + db_path = admin.database_path(conftest.LIVE_PROJECT_ID, mr_inst, new_db) + try: + restore_backup_with_mr_cmek.restore_backup_with_mr_cmek( + conftest.LIVE_PROJECT_ID, mr_inst, new_db, mr_bkp, mr_keys + ) + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert "Configured KMS Keys: 3" in out + finally: + try: + admin.drop_database(database=db_path) + except exceptions.NotFound: + pass