Route creation service: register and unregister an instance

This example shows how to use the Route Creation Service (RCS) API to register an external service instance with the HPS reverse proxy and then unregister it when the session ends. Registering an instance makes the external service accessible through the HPS gateway under a path prefix, removing the need for clients to reach it directly.

Background

HPS includes a Route Creation Service that manages the reverse-proxy routing table at runtime. When a solver or external tool registers itself, HPS adds a route so that HTTP traffic sent to a well-known path on the HPS gateway is forwarded to that instance’s URL. Unregistering removes the route.

The RCS API is exposed through ansys.hps.client.rcs.RcsApi and uses the same Client authentication as the rest of the pyhps library.

The registration workflow involves three objects:

Class	Purpose
RcsApi	Client for the RCS REST API. Constructed from an authenticated Client.
RegisterInstance	Request body for registering a new instance. Supply the instance URL, a service name, and the routing strategy ("path_prefix" is the standard choice).
UnRegisterInstance	Request body for removing a previously registered instance. Requires the resource_name returned by the register call.

How the example works

1. Connect to the HPS server using Client with the server URL, username, and password.

2. Create an RcsApi from the authenticated client.

3. Health-check the RCS API with RcsApi.health_check() to confirm the service is reachable before attempting registration.

4. Register the instance by calling RcsApi.register_instance() with a RegisterInstance payload that specifies:

   • url: the base URL of the instance to expose (for example https://localhost:8000).

   • service_name: an identifier for the type of service (for example "solver").

   • routing: the routing strategy; "path_prefix" routes all requests whose path begins with the allocated prefix to this instance.

5. Unregister the instance by calling RcsApi.unregister_instance() with the resource_name from the registration response. This removes the route from the gateway immediately.

Command-line options

Option	Description
-U / --url	Base URL of the HPS server (default: https://localhost:8443/hps).
-i / --instance_url	URL of the external instance to register (default: https://localhost:8000).
-u / --username	HPS username (default: repuser).
-p / --password	HPS password (default: repuser).

Expected output

A successful run produces output like this:

Connect to HPC Platform Services
HPS URL: https://localhost:8443/hps
RCS API health check: {'status': 'ok'}
RCS API info: {'version': '1.0.0', ...}
Register instance with URL: https://localhost:8000
Register instance response: resource_name='solver-a1b2c3' url='https://localhost:8000' ...
Unregister instance
Unregister instance response: resource_name='solver-a1b2c3' status='removed'

Here is the rcs_example.py script for this example:

rcs_example.py

"""Simple script to use RCS for registering and unregistering an instance."""

import argparse
import logging

from ansys.hps.client import Client, HPSError
from ansys.hps.client.rcs import RcsApi, RegisterInstance, UnRegisterInstance

log = logging.getLogger(__name__)

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("-U", "--url", default="https://localhost:8443/hps")
    parser.add_argument("-i", "--instance_url", default="https://localhost:8000")
    parser.add_argument("-u", "--username", default="repuser")
    parser.add_argument("-p", "--password", default="repuser")
    args = parser.parse_args()

    logger = logging.getLogger()
    logging.basicConfig(format="%(message)s", level=logging.DEBUG)

    try:
        log.info("Connect to HPC Platform Services")
        client = Client(url=args.url, username=args.username, password=args.password)
        log.info(f"HPS URL: {client.url}")
    except HPSError as e:
        log.error(str(e))

    rcs_api = RcsApi(client)
    request_data = RegisterInstance(
        url=f"{args.instance_url}", service_name="solver", routing="path_prefix"
    )
    resp = rcs_api.health_check()
    log.info(f"RCS API health check: {resp}")
    resp = rcs_api.get_api_info()
    log.info(f"RCS API info: {resp}")
    log.info(f"Register instance with URL: {args.instance_url}")
    register_instance = rcs_api.register_instance(request_data)
    log.info(f"Register instance response: {register_instance}")
    log.info("Unregister instance")
    unregister = UnRegisterInstance(resource_name=register_instance.resource_name)
    unregister_instance = rcs_api.unregister_instance(unregister)
    log.info(f"Unregister instance response: {unregister_instance}")