docs: Samples and tests for Instance Admin Client APIs (#1987)

This PR contains sample files and their integration tests for the instance admin client APIs.

Author: alkatrivedi

samples/system-test/v2/spanner.test.js

@@ -0,0 +1,309 @@
+// Copyright 2024 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.
+
+'use strict';
+
+const {Spanner} = require('@google-cloud/spanner');
+const pLimit = require('p-limit');
+const {describe, it, before, after, afterEach} = require('mocha');
+const {assert} = require('chai');
+const cp = require('child_process');
+
+const execSync = cmd => cp.execSync(cmd, {encoding: 'utf-8'});
+const instanceCmd = 'node v2/instance.js';
+
+const CURRENT_TIME = Math.round(Date.now() / 1000).toString();
+const PROJECT_ID = process.env.GCLOUD_PROJECT;
+const PREFIX = 'test-instance';
+const SAMPLE_INSTANCE_ID = `${PREFIX}-my-sample-instance-${CURRENT_TIME}`;
+const SAMPLE_INSTANCE_CONFIG_ID = `custom-my-sample-instance-config-${CURRENT_TIME}`;
+const BASE_INSTANCE_CONFIG_ID = 'regional-us-central1';
+const INSTANCE_ID =
+  process.env.SPANNERTEST_INSTANCE || `${PREFIX}-${CURRENT_TIME}`;
+const DATABASE_ID = `test-database-${CURRENT_TIME}`;
+const INSTANCE_ALREADY_EXISTS = !!process.env.SPANNERTEST_INSTANCE;
+const PG_DATABASE_ID = `test-pg-database-${CURRENT_TIME}`;
+const RESTORE_DATABASE_ID = `test-database-${CURRENT_TIME}-r`;
+const ENCRYPTED_RESTORE_DATABASE_ID = `test-database-${CURRENT_TIME}-r-enc`;
+const BACKUP_ID = `test-backup-${CURRENT_TIME}`;
+const COPY_BACKUP_ID = `test-copy-backup-${CURRENT_TIME}`;
+const ENCRYPTED_BACKUP_ID = `test-backup-${CURRENT_TIME}-enc`;
+const CANCELLED_BACKUP_ID = `test-backup-${CURRENT_TIME}-c`;
+const LOCATION_ID = 'regional-us-central1';
+
+const spanner = new Spanner({
+  projectId: PROJECT_ID,
+});
+
+const LABEL = 'node-sample-tests';
+const GAX_OPTIONS = {
+  retry: {
+    retryCodes: [4, 8, 14],
+    backoffSettings: {
+      initialRetryDelayMillis: 1000,
+      retryDelayMultiplier: 1.3,
+      maxRetryDelayMillis: 32000,
+      initialRpcTimeoutMillis: 60000,
+      rpcTimeoutMultiplier: 1,
+      maxRpcTimeoutMillis: 60000,
+      totalTimeoutMillis: 600000,
+    },
+  },
+};
+
+const delay = async test => {
+  const retries = test.currentRetry();
+  // No retry on the first failure.
+  if (retries === 0) return;
+  // See: https://cloud.google.com/storage/docs/exponential-backoff
+  const ms = Math.pow(2, retries) + Math.random() * 1000;
+  return new Promise(done => {
+    console.info(`retrying "${test.title}" in ${ms}ms`);
+    setTimeout(done, ms);
+  });
+};
+
+async function deleteStaleInstances() {
+  let [instances] = await spanner.getInstances({
+    filter: `(labels.${LABEL}:true) OR (labels.cloud_spanner_samples:true)`,
+  });
+  const old = new Date();
+  old.setHours(old.getHours() - 4);
+
+  instances = instances.filter(instance => {
+    return (
+      instance.metadata.labels['created'] &&
+      new Date(parseInt(instance.metadata.labels['created']) * 1000) < old
+    );
+  });
+  const limit = pLimit(5);
+  await Promise.all(
+    instances.map(instance =>
+      limit(() => setTimeout(deleteInstance, delay, instance))
+    )
+  );
+}
+
+async function deleteInstance(instance) {
+  const [backups] = await instance.getBackups();
+  await Promise.all(backups.map(backup => backup.delete(GAX_OPTIONS)));
+  return instance.delete(GAX_OPTIONS);
+}
+
+describe('Autogenerated Admin Clients', () => {
+  const instance = spanner.instance(INSTANCE_ID);
+
+  before(async () => {
+    await deleteStaleInstances();
+
+    if (!INSTANCE_ALREADY_EXISTS) {
+      const [, operation] = await instance.create({
+        config: LOCATION_ID,
+        nodes: 1,
+        labels: {
+          [LABEL]: 'true',
+          created: CURRENT_TIME,
+        },
+        gaxOptions: GAX_OPTIONS,
+      });
+      return operation.promise();
+    } else {
+      console.log(
+        `Not creating temp instance, using + ${instance.formattedName_}...`
+      );
+    }
+  });
+
+  after(async () => {
+    const instance = spanner.instance(INSTANCE_ID);
+
+    if (!INSTANCE_ALREADY_EXISTS) {
+      // Make sure all backups are deleted before an instance can be deleted.
+      await Promise.all([
+        instance.backup(BACKUP_ID).delete(GAX_OPTIONS),
+        instance.backup(ENCRYPTED_BACKUP_ID).delete(GAX_OPTIONS),
+        instance.backup(COPY_BACKUP_ID).delete(GAX_OPTIONS),
+        instance.backup(CANCELLED_BACKUP_ID).delete(GAX_OPTIONS),
+      ]);
+      await instance.delete(GAX_OPTIONS);
+    } else {
+      await Promise.all([
+        instance.database(DATABASE_ID).delete(),
+        instance.database(PG_DATABASE_ID).delete(),
+        instance.database(RESTORE_DATABASE_ID).delete(),
+        instance.database(ENCRYPTED_RESTORE_DATABASE_ID).delete(),
+        instance.backup(BACKUP_ID).delete(GAX_OPTIONS),
+        instance.backup(COPY_BACKUP_ID).delete(GAX_OPTIONS),
+        instance.backup(ENCRYPTED_BACKUP_ID).delete(GAX_OPTIONS),
+        instance.backup(CANCELLED_BACKUP_ID).delete(GAX_OPTIONS),
+      ]);
+    }
+    await spanner.instance(SAMPLE_INSTANCE_ID).delete(GAX_OPTIONS);
+  });
+  describe('instance', () => {
+    afterEach(async () => {
+      const sample_instance = spanner.instance(SAMPLE_INSTANCE_ID);
+      await sample_instance.delete();
+    });
+
+    // create_instance_using_instance_admin_client
+    it('should create an example instance', async () => {
+      const output = execSync(
+        `${instanceCmd} createInstance "${SAMPLE_INSTANCE_ID}" ${PROJECT_ID}`
+      );
+      assert.match(
+        output,
+        new RegExp(
+          `Waiting for operation on ${SAMPLE_INSTANCE_ID} to complete...`
+        )
+      );
+      assert.match(
+        output,
+        new RegExp(`Created instance ${SAMPLE_INSTANCE_ID}.`)
+      );
+    });
+
+    // create_instance_with_processing_units
+    it('should create an example instance with processing units', async () => {
+      const output = execSync(
+        `${instanceCmd} createInstanceWithProcessingUnits "${SAMPLE_INSTANCE_ID}" ${PROJECT_ID}`
+      );
+      assert.match(
+        output,
+        new RegExp(
+          `Waiting for operation on ${SAMPLE_INSTANCE_ID} to complete...`
+        )
+      );
+      assert.match(
+        output,
+        new RegExp(`Created instance ${SAMPLE_INSTANCE_ID}.`)
+      );
+      assert.match(
+        output,
+        new RegExp(`Instance ${SAMPLE_INSTANCE_ID} has 500 processing units.`)
+      );
+    });
+  });
+
+  describe('leader options', () => {
+    before(async () => {
+      const instance = spanner.instance(SAMPLE_INSTANCE_ID);
+      const [, operation] = await instance.create({
+        config: 'nam6',
+        nodes: 1,
+        displayName: 'Multi-region options test',
+        labels: {
+          ['cloud_spanner_samples']: 'true',
+          created: Math.round(Date.now() / 1000).toString(), // current time
+        },
+      });
+      await operation.promise();
+    });
+
+    after(async () => {
+      const instance = spanner.instance(SAMPLE_INSTANCE_ID);
+      await instance.delete();
+    });
+
+    // create_instance_config
+    it('should create an example custom instance config', async () => {
+      const output = execSync(
+        `node v2/instance-config-create.js ${SAMPLE_INSTANCE_CONFIG_ID} ${BASE_INSTANCE_CONFIG_ID} ${PROJECT_ID}`
+      );
+      assert.match(
+        output,
+        new RegExp(
+          `Waiting for create operation for ${SAMPLE_INSTANCE_CONFIG_ID} to complete...`
+        )
+      );
+      assert.match(
+        output,
+        new RegExp(`Created instance config ${SAMPLE_INSTANCE_CONFIG_ID}.`)
+      );
+    });
+
+    // update_instance_config
+    it('should update an example custom instance config', async () => {
+      const output = execSync(
+        `node v2/instance-config-update.js ${SAMPLE_INSTANCE_CONFIG_ID} ${PROJECT_ID}`
+      );
+      assert.match(
+        output,
+        new RegExp(
+          `Waiting for update operation for ${SAMPLE_INSTANCE_CONFIG_ID} to complete...`
+        )
+      );
+      assert.match(
+        output,
+        new RegExp(`Updated instance config ${SAMPLE_INSTANCE_CONFIG_ID}.`)
+      );
+    });
+
+    // delete_instance_config
+    it('should delete an example custom instance config', async () => {
+      const output = execSync(
+        `node instance-config-delete.js ${SAMPLE_INSTANCE_CONFIG_ID} ${PROJECT_ID}`
+      );
+      assert.match(
+        output,
+        new RegExp(`Deleting ${SAMPLE_INSTANCE_CONFIG_ID}...`)
+      );
+      assert.match(
+        output,
+        new RegExp(`Deleted instance config ${SAMPLE_INSTANCE_CONFIG_ID}.`)
+      );
+    });
+
+    // list_instance_config_operations
+    it('should list all instance config operations', async () => {
+      const output = execSync(
+        `node v2/instance-config-get-operations.js ${PROJECT_ID}`
+      );
+      assert.match(
+        output,
+        new RegExp(
+          `Getting list of instance config operations on project ${PROJECT_ID}...\n`
+        )
+      );
+      assert.match(
+        output,
+        new RegExp(
+          `Available instance config operations for project ${PROJECT_ID}:`
+        )
+      );
+      assert.include(output, 'Instance config operation for');
+      assert.include(
+        output,
+        'type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata'
+      );
+    });
+
+    // list_instance_configs
+    it('should list available instance configs', async () => {
+      const output = execSync(`node v2/list-instance-configs.js ${PROJECT_ID}`);
+      assert.match(
+        output,
+        new RegExp(`Available instance configs for project ${PROJECT_ID}:`)
+      );
+      assert.include(output, 'Available leader options for instance config');
+    });
+
+    // get_instance_config
+    // TODO: Enable when the feature has been released.
+    it.skip('should get a specific instance config', async () => {
+      const output = execSync(`node v2/get-instance-config.js ${PROJECT_ID}`);
+      assert.include(output, 'Available leader options for instance config');
+    });
+  });
+});

samples/v2/get-instance-config.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright 2024 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.
+ */
+
+// sample-metadata:
+//  title: Gets the instance config metadata for the configuration nam6
+//  usage: node get-instance-config.js <PROJECT_ID> <INSTANCE_CONFIG_ID>
+
+'use strict';
+
+function main(projectId) {
+  // [START spanner_get_instance_config]
+
+  /**
+   * TODO(developer): Uncomment the following line before running the sample.
+   */
+  // const projectId = 'my-project-id';
+
+  // Imports the Google Cloud client library
+  const {Spanner} = require('@google-cloud/spanner');
+
+  // Creates a client
+  const spanner = new Spanner({
+    projectId: projectId,
+  });
+
+  const instanceAdminClient = spanner.getInstanceAdminClient();
+
+  async function getInstanceConfig() {
+    // Get the instance config for the multi-region North America 6 (NAM6).
+    // See https://cloud.google.com/spanner/docs/instance-configurations#configuration for a list of all available
+    // configurations.
+    const [instanceConfig] = await instanceAdminClient.getInstanceConfig({
+      name: instanceAdminClient.instanceConfigPath(projectId, 'nam6'),
+    });
+    console.log(
+      `Available leader options for instance config ${instanceConfig.name} ('${
+        instanceConfig.displayName
+      }'): 
+           ${instanceConfig.leaderOptions.join()}`
+    );
+  }
+  getInstanceConfig();
+  // [END spanner_get_instance_config]
+}
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));