ST4SD Runtime Service API

1. launching virtual experiment instances
2. monitoring virtual experiment instances
3. downloading outputs and measured properties of virtual experiment instances

1. you have already installed a local client.

How do I connect to the ST4SD runtime service?

Connect to the ST4SD runtime service using an oauth-token

import webbrowser
# enter the https:// ST4SD url below
url="https://${your ST4SD url}"

if url.endswith("/"):
    url = url[:-1]

url = '/'.join([url, "authorisation/token"])

Copy to clipboard

import experiment.service.db

# enter the https:// ST4SD url below
url="https://${your ST4SD url}"

# enter your auth-token below
auth_token="put your authentication/token - do not share it with anyone"

api=experiment.service.db.ExperimentRestAPI(url, cc_auth_token=auth_token)
Copy to clipboard

Connect to the ST4SD runtime service using an api-token

1. Create a new ServiceAccount on the same namespace as your ST4SD instance:

   • oc project <NAMESPACE_THAT_HOSTS_ST4SD>
     Copy to clipboard

   • oc create serviceaccount <SERVICE_ACCOUNT_NAME> (e.g. oc create serviceaccount sa-auth-st4sd)
     Copy to clipboard

2. OpenShift creates 2 Secret objects for the ServiceAccount

   • <SERVICE_ACCOUNT_NAME>-token-<random-alphanumeric>:

     This is an OpenShift token that you can use to impersonate the ServiceAccount and log on the OpenShift cluster.

   • <SERVICE_ACCOUNT_NAME>.dockercfg or <SERVICE_ACCOUNT_NAME>.dockerconfigjson:

     That contains docker registry credentials and is used for pulling images from the private container registry of your OpenShift cluster - Openshift Image Registry.

3. Bind the ServiceAccount <SERVICE_ACCOUNT_NAME> to the namespaced role st4sd-authenticate-microservice - we have configured oauth-proxy to authorize OpenShift users that can get services in the same namespace as the st4sd deployment. For that you can use the following snippet in a new role_binding.yaml file:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: st4sd-custom-authenticated
     namespace: <NAMESPACE_THAT_HOSTS_ST4SD>
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: st4sd-authenticate-microservices
   Copy to clipboard

   Create the new RoleBinding object:

   oc create -f role_binding.yaml
   Copy to clipboard

4. Extract the token of of the <SERVICE_ACCOUNT_NAME>-token-<random-alphanumeric> Secret. The secret may include the ca.crt and service-ca.crt fields that contain the CA certificate used for validating the OpenShift API server’s TLS certificate. However the token we want to extract is under the token field. The token in the Secret is base64 encoded meaning that you need to decode to its raw value after you extract it.

   • oc get secret <SERVICE_ACCOUNT_NAME>-token-<random-alphanumeric> -o jsonpath='{.data.token}' | base64 --decode | sed 's/$/\n/'
     Copy to clipboard

   • Save the raw value of the token in a bearer_key variable in your python code.

5. Use your API-key to access ST4SD:

     import experiment.service.db
   
     # enter the https:// ST4SD url below
     url="https://${your ST4SD url}"
   
     bearer_key="<THE_SERVICEACCOUNT_KEY_YOU_EXTRACTED_ABOVE>"
     api=experiment.service.db.ExperimentRestAPI(url, cc_bearer_key=bearer_key)
   Copy to clipboard

• Store the API-key in a secure way, immediately revoke it if it leaks.
  • You can revoke a API-key by deleting the Secret associated with that ServiceAccount and Openshift will auto-generate a new Secret to replace it.
• Use each API-key in just one place.
  • For example, if you build 2 microservices and wish for both of them to have access to the ST4SD microservices you should repeat the above steps twice, once for each microservice.

How do I use the python api to ?

How do I get a list of available experiments ?

{
    "full-experiment-identifier@with-hash": {
        a parameterised virtual experiment package definition
    }
}
Copy to clipboard

• How to access a virtual experiment
• What options to allow users to change
• What options have preset values
• Metadata about the package.

How do I get the status of a virtual experiment instance?

# put here the rest_uid of the virtual experiment instance
rest_uid = "toxicity-predictions-trol7a"

status = api.api_rest_uid_status(rest_uid)
Copy to clipboard

import json
print(json.dumps(status['status'], indent=2))
Copy to clipboard

{
  "experiment-state": "finished",
  "total-progress": 1.0,
  "exit-status": "Success",
  "stages": [
    "Toxicity-prediction"
  ],
  "current-stage": "Toxicity-prediction",
  "stage-state": "finished",
Copy to clipboard

1. The orchestrator observed that the virtual experiment instance terminated (experiment-state = finished)
2. The virtual experiment instance has produced all its outputs (total-progress = 1.0)
3. The virtual experiment instance completed successfully (exit-status = Success)
4. The experiment had 1 stage (stages = ["Toxicity-prediction"])
5. Toxicity-prediction was the most recently executed stage with the lowest stage index (current-stage = Toxicity-prediction).
   1. All its tasks terminated and they were all successful (stage-state = finished)
   2. It reached its max progress (stage-progress = 1.0)
6. The virtual experiment instance did not raise any errors (error-description = "")

How do I find out the key-outputs of my experiment ?

How do I find out the key-outputs of an instance of my experiment ?

{
  "name of key-output": {
    "creationtime": a floating point epoch number,
    "description": "The value of the @description field in the definition of this key-output",
    "filename": "The filename e.g. foo.bar",
    "filepath": "The path to the file relative to the instance dir e.g. stages/stage2/MyComponent/foo.bar",
    "type": "The value of the @type field in the definition of this key-output",
  }
}
Copy to clipboard

How do I download the key-outputs of my experiment ?