Deploying in Google Cloud

Introduction

ScaleOut StateServer supports deployment to the Google Cloud Platform (GCP), providing you with cost-effective, pay-as-you-go pricing. You pay only for the resources you need while having the flexibility to adjust your deployment to meet the demands of your load.

ScaleOut users can use one of two ways to deploy their store:

• The ScaleOut Management Console has been enhanced to simplify the deployment and management of Google Cloud virtual machine instances in a cloud-based cluster. Using 3-page wizard, a ScaleOut store can be configured to run in an existing Google Cloud environment.

• ScaleOut Software also provides a set of customizable Python helper scripts and a YAML configuration template to deploy a store using Google’s Deployment Manager from the command line or as part of their existing infrastructure-as-code solution.

Terminology

The following terms defined by GCP are used in this guide and are defined here for your convenience:

• Instance: An instance represents a single running copy of a Google Cloud Image, and can be accessed through the Google Cloud console in the Compute Engine section.

• Configuration file: The YAML file describing resources to be created and parameters to configure your store.

• IAM: Identity and Access Management (IAM) lets you manage granular access to specific Google Cloud resources and prevents unwanted access to other resources.

• Service account: A service account is a special kind of account typically used by an application or compute workload, such as a Compute Engine instance, rather than a person. A service account is identified by its email address, which is unique to the account.

• Project and deployment: Google Cloud projects form the basis for creating, enabling, and using all Google Cloud services including managing APIs, enabling billing, managing collaborators and permissions for Google Cloud resources.

• Machine type: When you create a VM, you select a machine type from a machine family that determines the resources available to that VM. See Machine families for more details.

• Zone: Compute Engine resources are hosted in multiple locations worldwide. These locations are composed of regions and zones.

• VPC: A Virtual Private Cloud (VPC) network is a virtual version of a physical network that is implemented inside of Google’s production network.

• Secret manager: Use Secret Manager to securely store API keys, passwords, and other sensitive information.

• Startup script: A script that will be run at startup of any new instance. In the case of ScaleOut, the startup script will install ScaleOut StateServer and configure all of its required settings.

• Metadata: Every virtual machine (VM) instance stores its metadata on a metadata server. Your VM automatically has access to the metadata server API without any additional authorization. It is also used to store values that can be queried by scripts.

• SOSS license key: The license key issued by ScaleOut Software for your store.

Note

The current support of ScaleOut StateServer deployments in Google Cloud is limited to the Debian 11 images. This means a new deployment will always use the latest Debian 11 image.

Prerequisites

To deploy ScaleOut StateServer in Google Cloud, begin by visiting https://cloud.google.com/ and signing up for a GCP account.

Service Accounts

ScaleOut’s management tools require a set of access credentials to perform actions in GCP on your behalf. The credentials that a ScaleOut deployment use in Google Cloud are linked to a Service Account. To retrieve or configure service accounts for your project, visit the IAM & Admin page in the GCP console. You will need to provide information about the service account and its associated key to run ScaleOut stores in GCP.

Note

Service accounts provide an identity for unattended applications, such as batch jobs, worker processes, or resource-monitoring agents. By using a service account, you allow these applications to run without user interaction. For production environments (or anywhere security is a concern), use the GCP Identity and Access Management (IAM) feature to create security-limited credentials. When creating a service account, the following permissions are required:

IAM Permission	Requirement
compute.autoscalers.list	Required to define autoscaling options
compute.instanceGroupManagers.Create	Required to create managed instance groups which are used for the cluster.
compute.instanceGroupManagers.get	Required to retrieve info about existing instance groups.
compute.instanceGroupManagers.list	Required to list existing instance groups.
compute.instanceGroupManagers.update	Required to make changes to existing instance groups (such as resizing).
compute.instances.create	Required to create a new instance.
compute.instances.get	Required to access instances.
compute.instances.list	Required to query instance information.
compute.instances.setMetadata	Required to set metadata for instances.
compute.instances.start	Required to start an instance.
compute.instances.stop	Required to stop an instance
compute.machineTypes.list	Required to retrieve the list of available machine types.
compute.networks.list	Required to retrieve the list of VPCs
compute.regions.list	Required to retrieve the list of available regions and zones.
deploymentmanager.deployments.create	Required to deploy new clusters using the Google Deployment Manager.
deploymentmanager.deployments.delete	Required to delete clusters deployed through the Google Deployment Manager.
deploymentmanager.deployments.get	Required to retrieve info about a cluster.
deploymentmanager.manifests.get	Required to retrieve info about the existing deployment.
deploymentmanager.operations.get	Retrieve status info about an on-going operation.
deploymentmanager.resources.list	Required to list existing resources.
resourcemanager.projects.get	Retrieve info about a given project.
runtimeconfig.configs.get	Required to retrieve configuration info.
runtimeconfig.configs.list	Required to enumerate configurations.
runtimeconfig.variables.create	Required to create config variables.
runtimeconfig.variables.get	Required to query variables defined in existing configurations.
runtimeconfig.variables.list	Required to enumerate variables defined in existing configurations.
secretmanager.versions.access	Required to access secrets such as the ScaleOut license key, stored in the Google Secret Manager service.
Service Account User (role)	Note: this is not a permission, this is a role that you will need to assign to the service account you are using.

The Service Account User role has 5 assigned permissions (iam.serviceAccounts.actAs, iam.serviceAccounts.get, iam.serviceAccounts.list, resourceManager.projects.get, resourceManager.projects.list).

Note

All permissions listed above are required for some aspect of management or creation of resources in Google Cloud. Failure to add the required permissions will result in some issues with deploying or managing your cluster. While ScaleOut management tools make every effort to notify you of missing permissions when detected, double-checking that your account has the right permissions will make the process smoother.

Once a service account is created with the proper permissions, you will also need to generate a service account file that contains the private key that will be used by the deployment scripts to authenticate with the Google Platform and use the GCP APIs to deploy your stores.

Note

The private key associated with a service account can be used to access GCP resources. It should be handled safely. For best practices related to Service accounts, please refer to https://cloud.google.com/iam/docs/best-practices-service-accounts.

Networking

Configure the following inbound rules on your VPC network:

• TCP 720-724: the default ports used by ScaleOut StateServer hosts to communicate with each other. If you use different, custom values for the ports used by the ScaleOut service, you will also need to open those ports in your VPC instead.

• TCP 4000: the web management console requires port 4000 (TCP) to be open. For security, the port should only be open to source IP addresses that are expected to use the management console.

• TCP 22: the port used for SSH connections to the GCP Compute Engine instances.

Secret manager

Google Secret Manager lets you store, manage, and secure access to your application secrets. For security reasons, the configuration scripts do not handle the ScaleOut license key directly but instead read the license key from your Google Secret Manager. In order for ScaleOut software to access that secret, the Secret Manager permission must be added to the role defined for the service account used to deploy the store.

You can create a secret to store your license key by opening the Security section in the Google Cloud console. Secrets are versioned, so if you need to update your license key at any point, you will be able to specify which version of the secret to use in your next deployment. This also allows you to have a different secret value for different environments (e.g. production or test).

Deploying using the ScaleOut Management Console

Google Cloud deployments are only available in the latest preview release of the ScaleOut Management Console. To launch the new Console, select ScaleOut Management Console (Preview) from the Windows Start Menu.

Enable the Google Cloud Management View

Enable Google Cloud Management by clicking on the main menu View->Show Google Cloud Management:

This will bring up the Google Cloud Management node in the left pane. Once you select this node, the Google Cloud Management pane will open on the right.

Establish a connection

Click on the ‘Select a connection’ box to bring up the connection manager.

If you have not previously established a connection to Google Cloud, pick the ‘Manage connections’ link.

In the pop-up window, you will need to provide two parameters:

• the zone the store will get deployed into.

• the service account file holding the credentials ScaleOut will use to create resources in GCP on your behalf.

Note

The credentials file is securely encrypted in your Windows account using Windows Data Protection (DPAPI).

You can validate the connection by clicking on the ‘Test’ button or by closing the window.

Launch a new store

Once you have selected a connection, you can start the creation of a new store by clicking on ‘Launch New Store…’. This will open a 3-page wizard which will guide you through the available parameters.

In the first page of the wizard, you will select the machine type for your instances, the VPC, and the name and version of the secret holding your ScaleOut license key.

Note

The secret must be created prior to the execution of this wizard, as ScaleOut will attempt to read the license key from the Secret manager while deploying the store.

In the second page of the wizard, you can customize the ScaleOut store parameters such as version, ports, or optional REST services.

In the final page of the wizard, pick a name for your store and the number of instances to deploy. A summary view will help you validate your parameters.

Once you are satisfied with the parameters, click on ‘Launch’ to initiate the deployment of your store.

Configure the remote client

Once the new store is deployed, a pop-up dialog will offer you to configure the remote client parameters to connect to this new store. If you accept, the client configuration will get automatically updated, allowing the Console to manage the ScaleOut hosts in your new deployment.

If you want to change that selection or did not elect to configure the client after the creation of the store, you can do so by opening the ‘Client configuration’ view in the left pane.

There you can select the Cloud in the location drop-down box. This will reveal the Cloud provider options. Pick ‘Google Cloud Platform’ in the Cloud Provider drop-down, and the active Google Cloud connection you have created your store in.

If you have multiple stores in that zone, you will be given a chance to pick which one your client will be configured to use in the Store drop-down. You can then press ‘Apply’ to add this store to the remote client configuration. Click ‘Select as Active’ if you want to make this store the active remote client configuration.

You will see the update in the left pane as the store is now appearing:

Managing the store

In the Google Cloud Management view, you can see details about the existing stores for a given connection. You can see details of each instance, or reboot them.

You can also perform the following management operations: - resize the store by updating the size to its new value and clicking ‘Resize Store’. The Google Cloud Platform will automatically pick instances to add or remove to match the new size. - delete the entire store.

Deploying using a configuration template

ScaleOut publishes configuration templates and scripts to be used with Google Deployment Manager. The scripts are packed into a zip file available for download here.

When deploying a ScaleOut store with a configuration template, you can customize a configuration file to meet your needs. The configuration file contains parameters with default values that you may override in order to customize your store. You can for instance select the machine type, the number of instances, the zone that your store will be deployed in, or the service account to use for credentials. A number of ScaleOut-specific parameters will also allow you to configure ports, software version, or the store name.

Here is what the config.yml configuration file looks like:

imports:
- path: instance.py
- path: startup-script.sh
  name: startup-script.sh

resources:
- name: soss-cluster
  type: instance.py
  properties:
    metadata-from-file:
      startup-script: startup-script.sh

    # Google Cloud
    ConfigId: soss-config
    ServiceAccount: soss-service-account@my-deployments-394100.iam.gserviceaccount.com
    MachineType: e2-standard-2
    Zone: us-central1-a
    VpcName: default

    # ScaleOut cluster configuration
    StoreName: GEOSTORE1
    ServerPort: 721
    ManagementPort: 720
    InterconnectPort: 722
    SecureManagementPort: 723
    SecureServerPort: 724
    ServiceNetworkBinding: external
    EnableClientRestService: no
    EnableManagementRestService: yes
    SossVersion: 5.12.2-377
    InstanceCount: 3
    SossLicenseKeySecretName: SecretLicenseKey
    SossLicenseKeySecretVersion: 1

Feel free to edit any of the parameters in the Google Cloud or ScaleOut cluster configuration sections. Details about the Google-specific parameters are provided below:

• ConfigId: the name of your deployment. It should be unique if you intend on having multiple deployments in the same Google project.

• ServiceAccount: the ID of the service account you configured in the Google project with all the required permissions.

• SossLicenseKeySecretName: the name of the secret containing the ScaleOut license key (stored in the Secret Manager).

• SossLicenseKeySecretVersion: the version of the secret containing the ScaleOut license you want to use for this deployment.

• MachineType: the type of Compute Engine instance to use for each ScaleOut StateServer instance.

• Zone: the zone in which the ScaleOut StateServer cluster will be deployed (e.g. ‘us-central1-a’)

• VpcName: the name of the VPC network where the cluster will be deployed. Make sure you define the proper inbound rules described earlier.

Once you have edited the config.yml file, you can run a CLI command to deploy a ScaleOut cluster in your default project:

gcloud deployment-manager deployments create soss-deployment --config config.yml