feat(spanner): add MR CMEK samples

spanner/src/copy_backup_with_mr_cmek.php

@@ -0,0 +1,110 @@
+<?php
+/**
+ * Copyright 2024 Google Inc.
+ *
+ * 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.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/spanner/README.md
+ */
+
+namespace Google\Cloud\Samples\Spanner;
+
+// [START spanner_copy_backup_with_MR_CMEK]
+use Google\Cloud\Spanner\Admin\Database\V1\Client\DatabaseAdminClient;
+use Google\Cloud\Spanner\Admin\Database\V1\CopyBackupRequest;
+use Google\Cloud\Spanner\Admin\Database\V1\CopyBackupEncryptionConfig;
+use Google\Protobuf\Timestamp;
+
+/**
+ * Copy a MR CMEK backup.
+ * Example:
+ * ```
+ * copy_backup_with_mr_cmek($projectId, $instanceId, $sourceBackupId, $backupId, $kmsKeyNames);
+ * ```
+ * @param string $projectId The Google Cloud project ID.
+ * @param string $instanceId The Spanner instance ID.
+ * @param string $sourceBackupId The Spanner source backup ID.
+ * @param string $backupId The Spanner backup ID.
+ * @param string[] $kmsKeyNames The KMS keys used for encryption.
+ */
+/**
+ * Create a copy MR CMEK backup from another source backup.
+ * Example:
+ * ```
+ * copy_backup_with_mr_cmek($projectId, $destInstanceId, $destBackupId, $sourceInstanceId, $sourceBackupId, $kmsKeyNames);
+ * ```
+ *
+ * @param string $projectId The Google Cloud project ID.
+ * @param string $destInstanceId The Spanner instance ID where the copy backup will reside.
+ * @param string $destBackupId The Spanner backup ID of the new backup to be created.
+ * @param string $sourceInstanceId The Spanner instance ID of the source backup.
+ * @param string $sourceBackupId The Spanner backup ID of the source.
+* @param string[] $kmsKeyNames The KMS keys used for encryption.
+ */
+function copy_backup_with_mr_cmek(
+    string $projectId,
+    string $destInstanceId,
+    string $destBackupId,
+    string $sourceInstanceId,
+    string $sourceBackupId,
+    array $kmsKeyNames
+): void {
+    $databaseAdminClient = new DatabaseAdminClient();
+
+    $destInstanceFullName = DatabaseAdminClient::instanceName($projectId, $destInstanceId);
+    $expireTime = new Timestamp();
+    $expireTime->setSeconds((new \DateTime('+8 hours'))->getTimestamp());
+    $sourceBackupFullName = DatabaseAdminClient::backupName($projectId, $sourceInstanceId, $sourceBackupId);
+    $request = new CopyBackupRequest([
+        'source_backup' => $sourceBackupFullName,
+        'parent' => $destInstanceFullName,
+        'backup_id' => $destBackupId,
+        'expire_time' => $expireTime,
+        'encryption_config' => new CopyBackupEncryptionConfig([
+            'kms_key_names' => $kmsKeyNames,
+            'encryption_type' => CopyBackupEncryptionConfig\EncryptionType::CUSTOMER_MANAGED_ENCRYPTION
+        ])
+    ]);
+
+    $operationResponse = $databaseAdminClient->copyBackup($request);
+    $operationResponse->pollUntilComplete();
+
+    if (!$operationResponse->operationSucceeded()) {
+        $error = $operationResponse->getError();
+        printf('Backup not created due to error: %s.' . PHP_EOL, $error->getMessage());
+        return;
+    }
+    $destBackupInfo = $operationResponse->getResult();
+    $kmsKeyVersions = [];
+    foreach ($destBackupInfo->getEncryptionInformation() as $encryptionInfo) {
+        $kmsKeyVersions[] = $encryptionInfo->getKmsKeyVersion();
+    }
+    printf(
+        'Backup %s of size %d bytes was copied at %d from the source backup %s using encryption keys %s' . PHP_EOL,
+        basename($destBackupInfo->getName()),
+        $destBackupInfo->getSizeBytes(),
+        $destBackupInfo->getCreateTime()->getSeconds(),
+        $sourceBackupId,
+        print_r($kmsKeyVersions, true)
+    );
+    printf('Version time of the copied backup: %d' . PHP_EOL, $destBackupInfo->getVersionTime()->getSeconds());
+}
+// [END spanner_copy_backup_with_MR_CMEK]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

spanner/src/create_backup_with_mr_cmek.php

@@ -0,0 +1,101 @@
+<?php
+/**
+ * Copyright 2024 Google Inc.
+ *
+ * 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.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/spanner/README.md
+ */
+
+namespace Google\Cloud\Samples\Spanner;
+
+// [START spanner_create_backup_with_MR_CMEK]
+use Google\Cloud\Spanner\Admin\Database\V1\Backup;
+use \Google\Cloud\Spanner\Admin\Database\V1\Backup\State;
+use Google\Cloud\Spanner\Admin\Database\V1\Client\DatabaseAdminClient;
+use Google\Cloud\Spanner\Admin\Database\V1\CreateBackupEncryptionConfig;
+use Google\Cloud\Spanner\Admin\Database\V1\CreateBackupRequest;
+use Google\Cloud\Spanner\Admin\Database\V1\GetBackupRequest;
+use Google\Protobuf\Timestamp;
+
+/**
+ * Create a CMEK backup.
+ * Example:
+ * ```
+ * create_backup_with_mr_cmek($projectId, $instanceId, $databaseId, $backupId, $kmsKeyNames);
+ * ```
+ *
+ * @param string $projectId The Google Cloud project ID.
+ * @param string $instanceId The Spanner instance ID.
+ * @param string $databaseId The Spanner database ID.
+ * @param string $backupId The Spanner backup ID.
+ * @param string[] $kmsKeyNames The KMS keys used for encryption.
+ */
+function create_backup_with_mr_cmek(
+    string $projectId,
+    string $instanceId,
+    string $databaseId,
+    string $backupId,
+    array $kmsKeyNames
+): void {
+    $databaseAdminClient = new DatabaseAdminClient();
+    $instanceFullName = DatabaseAdminClient::instanceName($projectId, $instanceId);
+    $databaseFullName = DatabaseAdminClient::databaseName($projectId, $instanceId, $databaseId);
+    $expireTime = new Timestamp();
+    $expireTime->setSeconds((new \DateTime('+14 days'))->getTimestamp());
+    $request = new CreateBackupRequest([
+        'parent' => $instanceFullName,
+        'backup_id' => $backupId,
+        'encryption_config' => new CreateBackupEncryptionConfig([
+            'kms_key_names' => $kmsKeyNames,
+            'encryption_type' => CreateBackupEncryptionConfig\EncryptionType::CUSTOMER_MANAGED_ENCRYPTION
+        ]),
+        'backup' => new Backup([
+            'database' => $databaseFullName,
+            'expire_time' => $expireTime
+        ])
+    ]);
+
+    $operation = $databaseAdminClient->createBackup($request);
+
+    print('Waiting for operation to complete...' . PHP_EOL);
+    $operation->pollUntilComplete();
+
+    $request = new GetBackupRequest();
+    $request->setName($databaseAdminClient->backupName($projectId, $instanceId, $backupId));
+    $info = $databaseAdminClient->getBackup($request);
+    if (State::name($info->getState()) == 'READY') {
+        $kmsKeyVersions = [];
+        foreach ($info->getEncryptionInformation() as $encryptionInfo) {
+            $kmsKeyVersions[] = $encryptionInfo->getKmsKeyVersion();
+        }
+        printf(
+            'Backup %s of size %d bytes was created at %d using encryption keys %s' . PHP_EOL,
+            basename($info->getName()),
+            $info->getSizeBytes(),
+            $info->getCreateTime()->getSeconds(),
+            print_r($kmsKeyVersions, true)
+        );
+    } else {
+        print('Backup is not ready!' . PHP_EOL);
+    }
+}
+// [END spanner_create_backup_with_MR_CMEK]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

spanner/src/create_database_with_mr_cmek.php

@@ -0,0 +1,97 @@
+<?php
+/**
+ * Copyright 2024 Google Inc.
+ *
+ * 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.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/spanner/README.md
+ */
+
+namespace Google\Cloud\Samples\Spanner;
+
+// [START spanner_create_database_with_MR_CMEK]
+use Google\Cloud\Spanner\Admin\Database\V1\Client\DatabaseAdminClient;
+use Google\Cloud\Spanner\Admin\Database\V1\CreateDatabaseRequest;
+use Google\Cloud\Spanner\Admin\Database\V1\EncryptionConfig;
+
+/**
+ * Creates a MR CMEK database with tables for sample data.
+ * Example:
+ * ```
+ * create_database_with_mr_cmek($projectId, $instanceId, $databaseId, $kmsKeyNames);
+ * ```
+ *
+ * @param string $projectId The Google Cloud project ID.
+ * @param string $instanceId The Spanner instance ID.
+ * @param string $databaseId The Spanner database ID.
+ * @param string[] $kmsKeyNames The KMS keys used for encryption.
+ */
+function create_database_with_mr_cmek(
+    string $projectId,
+    string $instanceId,
+    string $databaseId,
+    array $kmsKeyNames
+): void {
+    $databaseAdminClient = new DatabaseAdminClient();
+    $instanceName = DatabaseAdminClient::instanceName($projectId, $instanceId);
+
+    $createDatabaseRequest = new CreateDatabaseRequest();
+    $createDatabaseRequest->setParent($instanceName);
+    $createDatabaseRequest->setCreateStatement(sprintf('CREATE DATABASE `%s`', $databaseId));
+    $createDatabaseRequest->setExtraStatements([
+        'CREATE TABLE Singers (
+            SingerId     INT64 NOT NULL,
+            FirstName    STRING(1024),
+            LastName     STRING(1024),
+            SingerInfo   BYTES(MAX)
+        ) PRIMARY KEY (SingerId)',
+        'CREATE TABLE Albums (
+            SingerId     INT64 NOT NULL,
+            AlbumId      INT64 NOT NULL,
+            AlbumTitle   STRING(MAX)
+        ) PRIMARY KEY (SingerId, AlbumId),
+        INTERLEAVE IN PARENT Singers ON DELETE CASCADE'
+    ]);
+
+    if (!empty($kmsKeyNames)) {
+        $encryptionConfig = new EncryptionConfig();
+        $encryptionConfig->setKmsKeyNames($kmsKeyNames);
+        $createDatabaseRequest->setEncryptionConfig($encryptionConfig);
+    }
+
+    $operationResponse = $databaseAdminClient->createDatabase($createDatabaseRequest);
+    printf('Waiting for operation to complete...' . PHP_EOL);
+    $operationResponse->pollUntilComplete();
+
+    if ($operationResponse->operationSucceeded()) {
+        $database = $operationResponse->getResult();
+        printf(
+            'Created database %s on instance %s with encryption keys %s' . PHP_EOL,
+            $databaseId,
+            $instanceId,
+            print_r($database->getEncryptionConfig()->getKmsKeyNames(), true)
+        );
+    } else {
+        $error = $operationResponse->getError();
+        printf('Failed to create encrypted database: %s' . PHP_EOL, $error->getMessage());
+    }
+}
+// [END spanner_create_database_with_MR_CMEK]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

spanner/src/restore_backup_with_mr_cmek.php

@@ -0,0 +1,85 @@
+<?php
+/**
+ * Copyright 2024 Google Inc.
+ *
+ * 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.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/spanner/README.md
+ */
+
+namespace Google\Cloud\Samples\Spanner;
+
+// [START spanner_restore_backup_with_MR_CMEK]
+use Google\Cloud\Spanner\Admin\Database\V1\Client\DatabaseAdminClient;
+use Google\Cloud\Spanner\Admin\Database\V1\RestoreDatabaseEncryptionConfig;
+use Google\Cloud\Spanner\Admin\Database\V1\RestoreDatabaseRequest;
+
+/**
+ * Restore a MR CMEK database from a backup.
+ * Example:
+ * ```
+ * restore_backup_with_mr_cmek($projectId, $instanceId, $databaseId, $backupId, $kmsKeyNames);
+ * ```
+ * @param string $projectId The Google Cloud project ID.
+ * @param string $instanceId The Spanner instance ID.
+ * @param string $databaseId The Spanner database ID.
+ * @param string $backupId The Spanner backup ID.
+ * @param string[] $kmsKeyNames The KMS keys used for encryption.
+ */
+function restore_backup_with_mr_cmek(
+    string $projectId,
+    string $instanceId,
+    string $databaseId,
+    string $backupId,
+    array $kmsKeyNames
+): void {
+    $databaseAdminClient = new DatabaseAdminClient();
+    $instanceFullName = DatabaseAdminClient::instanceName($projectId, $instanceId);
+    $backupFullName = DatabaseAdminClient::backupName($projectId, $instanceId, $backupId);
+    $request = new RestoreDatabaseRequest([
+        'parent' => $instanceFullName,
+        'database_id' => $databaseId,
+        'backup' => $backupFullName,
+        'encryption_config' => new RestoreDatabaseEncryptionConfig([
+            'kms_key_names' => $kmsKeyNames,
+            'encryption_type' => RestoreDatabaseEncryptionConfig\EncryptionType::CUSTOMER_MANAGED_ENCRYPTION
+        ])
+    ]);
+
+    // Create restore operation
+    $operation = $databaseAdminClient->restoreDatabase($request);
+
+    print('Waiting for operation to complete...' . PHP_EOL);
+    $operation->pollUntilComplete();
+
+    // Reload new database and get restore info
+    $database = $operation->operationSucceeded() ? $operation->getResult() : null;
+    $restoreInfo = $database->getRestoreInfo();
+    $backupInfo = $restoreInfo->getBackupInfo();
+    $sourceDatabase = $backupInfo->getSourceDatabase();
+    $sourceBackup = $backupInfo->getBackup();
+    $encryptionConfig = $database->getEncryptionConfig();
+    printf(
+        'Database %s restored from backup %s using encryption keys %s' . PHP_EOL,
+        $sourceDatabase, $sourceBackup, print_r($encryptionConfig->getKmsKeyNames(), true)
+    );
+}
+// [END spanner_restore_backup_with_MR_CMEK]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);