This document describes how to install and configure the IBM Symphony providerfor Compute Engine. You learn how to set up Pub/Sub to monitorvirtual machine (VM) instance events, build and install the provider plugin, andconfigure the provider instance within your Symphony host factory environment.

For more information about Symphony Connectors for Google Cloud,seeIntegrate IBM Spectrum Symphony with Google Cloud.

Before you begin

To install the Symphony provider for Compute Engine, you must have thefollowing resources:

• A running IBM Spectrum Symphony cluster with the host factory serviceenabled. You have the hostname of your IBM Spectrum Symphony primary host.
• A dedicated service account with therequired roles. Formore information on how you create this service account, seeCreate aservice account.

• A firewall rule that you have configured to allow communication between Symphonyprimary host and Compute Engine. For example:

  gcloudcomputefirewall-rulescreateallow-symphony-primary-to-compute\--project=PROJECT_ID\--direction=INGRESS\--priority=1000\--network=NETWORK_NAME\--allow=all\--source-tags=NETWORK_TAGS_MASTER\--target-tags=NETWORK_TAGSgcloudcomputefirewall-rulescreateallow-symphony-compute-to-primary\--project=PROJECT_ID\--direction=INGRESS\--priority=1000\--network=NETWORK_NAME\--allow=all\--source-tags=NETWORK_TAGS\--target-tags=NETWORK_TAGS_MASTER

  Replace the following:

  • PROJECT_ID: the ID of your Google Cloudproject.
  • NETWORK_NAME: the name of the VPC networkwhere your Symphony resources are deployed.
  • NETWORK_TAGS_MASTER: the network tagapplied to your Symphony primary host VM.
  • NETWORK_TAGS: the network tag applied toyour Symphony compute node VMs.

  For more information, seeCreate VPCfirewall rules.

Required roles

To get the permissions that you need to create and manage instances that use a service account, ask your administrator to grant you the following IAM roles on the project:

• Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
• Service Account User (roles/iam.serviceAccountUser)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Prepare your Compute Engine environment

To let the Symphony host factory create and manage VMs, you need toconfigure several Google Cloud resources:

• Instance template: a blueprint that defines the configuration of theSymphony compute VMs that the host factory creates.

• Managed Instance Group (MIG): a group of identical VMs that are createdby using an instance template. The host factory scales this group up or downby adding or removing VMs based on workload demand.

• Pub/Sub topic and subscription: a messaging service thatnotifies the Symphony provider about VM lifecycle events, such as preemptionsor deletions. This service lets the provider maintain an accurate stateof the cluster.

Create an instance template

Create an instance template for the Symphony compute hosts by using thegcloudcompute instance-templatescreate command. Thistemplate defines the properties of the VMs that it creates. These VMs must haveSymphony installed. You can either use an image with Symphony pre-installed, oruse a startup script to install Symphony after you create the VMs. Forinformation about installing Symphony on a compute host VM, seeInstalling on aLinux computehostin the IBM documentation.

gcloudcomputeinstance-templatescreateINSTANCE_TEMPLATE_NAME\--machine-type=MACHINE_TYPE\--network-interface=nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=SUBNET_NAME,no-address\--instance-template-region=REGION\--service-account=SERVICE_ACCOUNT_EMAIL\--scopes=https://www.googleapis.com/auth/devstorage.read_only,https://www.googleapis.com/auth/logging.write,https://www.googleapis.com/auth/monitoring.write,https://www.googleapis.com/auth/service.management.readonly,https://www.googleapis.com/auth/servicecontrol,https://www.googleapis.com/auth/trace.append\--tags=NETWORK_TAGS\--create-disk=auto-delete=yes,boot=yes,device-name=INSTANCE_TEMPLATE_NAME,image-family=rocky-linux-9,image-project=rocky-linux-cloud,mode=rw,size=20,type=pd-balanced\--shielded-secure-boot\--shielded-vtpm\--shielded-integrity-monitoring

Replace the following:

• INSTANCE_TEMPLATE_NAME: a name for your newinstance template.
• MACHINE_TYPE: the machine type for your computeinstances. For more information, seeCreate a VM with a custom machinetype.
• SUBNET_NAME: the name of the subnet for yourinstances. For more information, seeView the network configuration for aninstance.
• SERVICE_ACCOUNT_EMAIL: the email of the serviceaccount that you set up in theBefore you beginsection. Ensure this service account has the roles specified in theRequired roles section.
• REGION: the Google Cloud region where you want to create your resources.
• NETWORK_TAGS: a network tag to apply to your instances, which can be used for firewall rules—for example,symphony-compute.

Create a managed instance group

Create a managed instance group (MIG) by using the instance template from theprevious step. The host factory provider scales this group by adding or removinginstances based on workload demand.

gcloudcomputeinstance-groupsmanagedcreateINSTANCE_GROUP_NAME\--project=PROJECT_ID\--base-instance-name=INSTANCE_GROUP_NAME\--template=projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME\--size=0\--zone=ZONE--default-action-on-vm-failure=repair\--no-force-update-on-repair\--standby-policy-mode=manual\--list-managed-instances-results=pageless

Replace the following:

• INSTANCE_GROUP_NAME: your chosen name forthe managed instance group.
• PROJECT_ID: the ID of your Google Cloudproject. For more information, seeFind the project name, number, andID.
• INSTANCE_TEMPLATE_NAME: the name of theinstance template that you created in theprevious step.
• REGION: the region where your resources arelocated, such asus-east.
• ZONE: the zone within the selected region,such asa.

For more information on creating MIGs, seeCreate a MIG in a singlezone.

Set up Pub/Sub

To let the Symphony provider receive notifications about VM lifecycle events,configure a Pub/Sub topic and subscription:

1. On your Symphony primary host, set the following environment variables:

   exportGCP_PROJECT=PROJECT_IDexportPUBSUB_TOPIC=PUBSUB_TOPIC

   Replace the following:

   • PROJECT_ID: The ID of your Google Cloud project.
   • PUBSUB_TOPIC: A name for yourGoogle Cloud topic, such ashf-gce-vm-events.

2. Create a Pub/Sub topic:

   gcloudpubsubtopicscreate$PUBSUB_TOPIC

3. Use thegcloud logging sinks createcommand to create a loggingsink to export audit logs to Pub/Sub:

   gcloudloggingsinkscreate${PUBSUB_TOPIC}-sink\pubsub.googleapis.com/projects/${GCP_PROJECT}/topics/${PUBSUB_TOPIC}\--log-filter="    logName=\"projects/${GCP_PROJECT}/logs/cloudaudit.googleapis.com%2Factivity\"    resource.type=(\"gce_instance_group_manager\" OR \"gce_instance\")    protoPayload.methodName=(        \"v1.compute.instanceGroupManagers.createInstances\"        OR        \"v1.compute.instanceGroupManagers.deleteInstances\"        OR        \"v1.compute.instances.insert\"        OR        \"v1.compute.instances.delete\"    )    "\--description="Exports MIG VM create/delete audit logs to Pub/Sub"

   The output of this command includes a service account that you use in thenext step.

4. Grant thePub/Sub Publisher(roles/pubsub.publisher)role to the service account from the previous step:

   gcloudpubsubtopicsadd-iam-policy-binding$PUBSUB_TOPIC\--member="serviceAccount:LOGGING_SINK_SERVICE_ACCOUNT"\--role="roles/pubsub.publisher"

   ReplaceLOGGING_SINK_SERVICE_ACCOUNT with theservice account name from the logging sink creation output.

5. Create a subscription to receive the logs:

   gcloudpubsubsubscriptionscreate${PUBSUB_TOPIC}-sub\--topic=${PUBSUB_TOPIC}

6. Verify that your service account has the correct permissions to subscribe tothe subscription:

   gcloudpubsubsubscriptionsadd-iam-policy-binding${PUBSUB_TOPIC}-sub\--member="serviceAccount:SERVICE_ACCOUNT_EMAIL"\--role="roles/pubsub.subscriber"

   ReplaceSERVICE_ACCOUNT_EMAIL with the email of theservice account that manages your instance group. This is the same serviceaccount you set up in theBefore you begin section.

The Pub/Sub setup is complete. For more information on how toconfigurePub/Sub, seePublish and receive messages inPub/Sub by usingthe Google Cloud CLI.

Load the host factory environment variables

Before you can configure or manage the host factory services, you must load theSymphony environment variables into your shell session. On your Symphony primaryhost VM, run the following command:

sourceINSTALL_FOLDER/profile.platform

ReplaceINSTALL_FOLDER with the path to your installfolder. The default Symphony installation folder path is/opt/ibm/spectrumcomputing. If you installed Symphony in a different location,then use the correct path for your environment.

This command executes theprofile.platform script, which exports essentialenvironment variables like$EGO_TOP and$HF_TOP and adds the Symphonycommand-line tools to your shell'sPATH. You must run this command for eachnew terminal session to ensure the environment is configured correctly.

Install the provider plugin

To integrate the Compute Engine provider with the Symphony host factoryservice,install the prebuilt provider plugin from theRPM package orbuild the provider from the sourcecode.

Install the prebuilt provider plugin

To install the provider plugin by using RPM packages, follow these steps on yourSymphony primary host:

1. Add theyum repository for the Google Cloud Symphony Connectors:

   sudotee/etc/yum.repos.d/google-cloud-symphony-connector.repo <<EOM[google-cloud-symphony-connector]name=GoogleCloudSymphonyConnectorbaseurl=https://packages.cloud.google.com/yum/repos/google-cloud-symphony-connector-x86-64enabled=1gpgcheck=0repo_gpgcheck=0gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpghttps://packages.cloud.google.com/yum/doc/rpm-package-key.gpgEOM

2. Install the provider package for Compute Engine:

   sudoyuminstall-yhf-gcpgce-provider.x86_64

The RPM package installs the provider executables and scripts into the correctdirectories for the Symphony host factory service. After installation, thedirectory structure appears as follows:

├── bin│   └── hf-gce└── scripts    ├── getAvailableTemplates.sh    ├── getRequestStatus.sh    ├── getReturnRequests.sh    ├── requestMachines.sh    └── requestReturnMachines.sh

Build the provider from the source code

To build and install the CLI executable in thebin directory of theprovider plugin directory, follow these steps:

1. Clone thesymphony-gcp-connector repository from GitHub:

   gitclonehttps://github.com/GoogleCloudPlatform/symphony-gcp-connector.git

2. Navigate to thehf-provider directory in your project:

   cdPROJECT_ROOT/hf-provider

   ReplacePROJECT_ROOT with the path to the top-leveldirectory that contains the hf-provider directory, such as/home/user/symphony-gcp-connector.

3. If you don't haveuv installed, then install it:

   pipinstalluv

4. Create a Python virtual environment by usinguv:

   uvvenv

5. Activate the virtual environment:

   source.venv/bin/activate

6. Install the required project dependencies:

   uvpipinstall.

7. Install PyInstaller, which bundles the Python application into a standalone executable:

   uvpipinstallpyinstaller

8. Create thehf-gce CLI for Compute Engine clusters:

   uvrunpyinstallerhf-gce.spec--clean

9. To verify the installation, run the--help command for an executable. Youmight see an error if you don't set the required environment variables.

   dist/hf-gce--help

10. Copy the executable to the provider pluginbin directory:

    mkdir-p${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/bincpdist/hf-gce${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/bin/

11. Copy the scripts to the provider pluginscripts directory:

    cp-R./resources/gce_cli/1.2/providerplugins/gcpgce/scripts${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/

    The OS must support the version of Python used to build the executables.The executables were tested with Python 3.9.6.

After installation, the directory structure for the provider plugin is similar tothis example:

├── bin│   └── hf-gce└── scripts    ├── getAvailableTemplates.sh    ├── getRequestStatus.sh    ├── getReturnRequests.sh    ├── requestMachines.sh    └── requestReturnMachines.sh

Enable the provider plugin

To enable the Compute Engine provider plugin, register it in the host factoryconfiguration:

1. Open the$HF_TOP/conf/providerplugins/hostProviderPlugins.json file.

   The$HF_TOP environment variable is defined in your environment when youuse thesource command. The value is the path to thetop-level installation directory for the IBM Spectrum Symphony host factoryservice.

2. Add agcpgce provider plugin section:

   {"name":"gcpgce","enabled":1,"scriptPath":"${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/scripts/"}

   If you are using version 1.2 ofthe provider plugin with the default value for$HF_TOP, the resultingscriptPath value is:INSTALL_FOLDER/hostfactory/1.2/providerplugins/gcpgce/scripts/.

Set up a provider instance

To configure the Compute Engine provider for your environment, create a providerinstance.

1. Set up the directory for the provider instance:

   • If youbuilt the provider from source code,then you must create the directory and configuration files manually:

     mkdir-p$HF_TOP/conf/providers/gcpgceinst/

   • If youinstalled with RPM, then this directoryalready exists and contains example configuration files. Copy theexample files to create your configuration:

     cp$HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_config.json.dist$HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_config.jsoncp$HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_templates.json.dist$HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_templates.json

2. In the$HF_TOP/conf/providers/gcpgceinst/ directory, create or edit agcpgceinstprov_config.json file. This file contains the main configurationfor the provider. The provider supports the following configuration variables.You must specify variables that have no default value in this configuration.

   Variable Name	Description	Default Value
   HF_DBDIR	The location where this provider stores its state database.	Defined in the HostFactory environment as$HF_DBDIR.
   HF_TEMPLATES_FILENAME	The name of the templates file.	gcpgceinstprov_templates.json
   GCP_CREDENTIALS_FILE	The location of the Google Cloud service account credentials file.	The application uses the default credentials if you don't specify this value.
   GCP_PROJECT_ID	The ID of the Google Cloud project.	None
   GCP_INSTANCE_PREFIX	A string to prepend to all hosts created by this provider.	sym-
   LOGFILE	The location of the log file that the provider sends logs to.	A file with a generated name, located in the directory defined by theHostFactory environment variableHF_PROVIDER_LOGDIR.
   LOG_LEVEL	The Python log level	WARNING
   PUBSUB_TIMEOUT	If the most recent Pub/Sub event is older than this duration, inseconds, the Pub/Sub listener disconnects. This timeout only applies whenthe Pub/Sub event listener is automatically launched. Otherwise, the listenerruns indefinitely, and the administrator must control the lifecycle.	600
   PUBSUB_TOPIC	The name of the Pub/Sub topic. This variable is for backwardcompatibility only.	hf-gce-vm-events
   PUBSUB_SUBSCRIPTION	The name of the Pub/Sub subscription to monitor for VM events.	hf-gce-vm-events-sub
   PUBSUB_LOCKFILE	The name of the file that indicates whether the Pub/Sub event listener is active.	/tmp/sym_hf_gcp_pubsub.lock
   PUBSUB_AUTOLAUNCH	If set totrue, the provider attempts to automaticallylaunch the Pub/Sub event listener. Iffalse, you mustlaunch the Pub/Sub event listener by using the method of yourchoice, with the commandhf-gce monitorEvents.	true

   The following example shows a basic configuration:

   {"GCP_PROJECT_ID":"PROJECT_ID","LOG_LEVEL":"INFO","PUBSUB_SUBSCRIPTION":"PUBSUB_SUBSCRIPTION","PUBSUB_TIMEOUT":100}

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.
   • PUBSUB_SUBSCRIPTION: the name of thePub/Sub subscription that you created to monitor VM events.For more information, seeSet up Pub/Sub.

3. In the same directory, create or edit agcpgceinstprov_templates.jsonfile. This file defines the templates for the VMs that the provider cancreate. The attributes in the template must align with the configuration ofthe supporting instance group.

   • If youinstalled with RPM, then use thegcpgceinstprov_templates.json file that you created in the previoussteps as a starting point.

   • If youbuilt from source, then use thefollowing example template:

     {"templates":[{"templateId":"template-gcp-01","maxNumber":10,"attributes":{"type":["String","X86_64"],"ncpus":["Numeric","1"],"nram":["Numeric","1024"]},"gcp_zone":"GCP_ZONE","gcp_instance_group":"INSTANCE_GROUP_NAME"}]}

     Replace the following:

     • GCP_ZONE: the Google Cloud zone where your instancegroup is located, such asus-central1-a.
     • INSTANCE_GROUP_NAME: the name of the instance group thatthe provider manages, such assymphony-compute-ig.

4. After you create these files, verify that your provider instance directory issimilar to this example:

   ├── gcpgceinstprov_config.json└── gcpgceinstprov_templates.json

Enable the provider instance

To activate the provider instance, enable it in the host factory configuration file:

1. Open the$HF_TOP/conf/providers/hostProviders.json file.

2. Add agcpgceinst provider instance section:

   {"name":"gcpgceinst","enabled":1,"plugin":"gcpgce","confPath":"${HF_CONFDIR}/providers/gcpgceinst/","workPath":"${HF_WORKDIR}/providers/gcpgceinst/","logPath":"${HF_LOGDIR}/"}

   Important: Don't replace the${HF_CONFDIR},${HF_WORKDIR}, and${HF_LOGDIR}variables in this configuration. The IBM Spectrum Symphony host factoryautomatically defines these environment variables.

   When you configure your shell session by using thesourcecommand, this script sets these variables to pointto the correct subdirectories within your Symphony installation. The hostfactory service then uses these variables to construct the full paths atruntime.

Enable the requestor instance

To let a specific Symphony component use the Compute Engine provider toprovision resources, enable it for that requestor.

1. Open the$HF_TOP/conf/requestors/hostRequestors.json file.

2. In the appropriate requestor instance, addgcpgceinst to theprovidersparameter:

   "providers":["gcpgceinst"],

   The provider value must match the provider name you use inEnable theprovider instance.

Start the host factory service

To apply your configuration changes, start the host factory service. On yourSymphony primary host VM, sign in as the cluster administrator and start theservice:

sed-i-e"s|MANUAL|AUTOMATIC|g"$EGO_ESRVDIR/esc/conf/services/hostfactory.xmlegoshuserlogon-u"SYMPHONY_USERNAME -x "SYMPHONY_PASSWORDegoshservicestartHostFactory

Replace the following:

• SYMPHONY_USERNAME: the Symphony username for authentication.
• SYMPHONY_PASSWORD: the password for the Symphony user.

Test connectors

Create a resource request to test the providerfor Compute Engine.

To do so, use one of the following methods:

• Symphony GUI: For instructions on how to create a resource requestby using the Symphony GUI, seeManually scheduling cloud host requests andreturnsin the IBM documentation.

• REST API: To create a resource request using the REST API, follow thesesteps:

  1. Find the host and port of the host factory REST API:

     egoshclientviewREST_HOST_FACTORY_URL

     The output is similar to this example:

     CLIENT NAME: REST_HOST_FACTORY_URLDESCRIPTION: http://sym2.us-central1-c.c.symphonygcp.internal:9080/platform/rest/hostfactory/TTL        : 0LOCATION   : 40531@10.0.0.33USER       : AdminCHANNEL INFORMATION:CHANNEL             STATE9                   CONNECTED

  2. To create a resource request using the REST API, use thefollowing command:

     HOST=PRIMARY_HOSTPORT=PORTTEMPLATE_NAME=INSTANCE_TEMPLATE_NAMEPROVIDER_NAME=gcpgceinstcurl-XPOST-u"SYMPHONY_USER:SYMPHONY_PASSWORD"-H"Content-Type: application/json"-d"{ \"demand_hosts\": [ { \"prov_name\": \"$PROVIDER_NAME\", \"template_name\": \"$TEMPLATE_NAME\", \"ninstances\": 1 } ] }"\http://$HOST:$PORT/platform/rest/hostfactory/requestor/admin/request

     Replace the following:

     • PRIMARY_HOST: the hostname of your primaryhost from the output of the previous command.
     • PORT: the port number of your primary hostfrom the output of the previous command, such as9080.
     • SYMPHONY_TEMPLATE_ID: ThetemplateIddefined in thegcpgceinstprov_templates.json file, such astemplate-gcp-01.
     • SYMPHONY_USER: the Symphony user forauthentication.
     • SYMPHONY_PASSWORD: the password for theSymphony user.

     If successful, then the output is similar to this example:

     {"scheduled_request_id":["SD-641ef442-1f9e-40ae-ae16-90e152ed60d2"]}

What's next

• Install the GKEprovider
• Troubleshoot IBM SpectrumSymphony connectors