Uploading the custom configuration

After you register your custom image, you must modify the JSON configuration file that you downloaded and then upload it to the IBM® Software Hub cluster under a new name.

Important: Custom runtime definitions, just like custom images, require manual maintenance. They are not updated automatically.

Prerequisites: Get an authorization token and export it as the MY_TOKEN environment variable. See Generating an API authorization token.

To upload the custom configuration:
  1. Open the JSON configuration file that you downloaded in an editor.
  2. Find the line that contains the "image" attribute. It has the following format "image":"<image registry>/<image name>:<image tag>, and contains a value such as "image": "<private-registry>/wslocal-runtime-241-py@sha256:f21b54dee335c9a39de5980a41ac2a422a2bda8820b91da005dba53ba5857434"
  3. Replace name, display_name, description, and author with your own data. If name consists of several words, separate each word with a hyphen (for example, custom-def-name). The name must be unique among all runtime definitions of IBM Software Hub. The unique name that you provide appears in the Software version dropdown when an environment template is created.
  4. Use the registry URL that you used when you registered the custom image.
  5. Change <image name>:<image tag> to the values that you used when you registered your custom image.
  6. Optional: Set user-defined variables. See Setting user-defined variables.
  7. Save the file.
  8. Create a runtime definition with the settings that are defined in the JSON file by using the API:
    curl -k -X POST -H "Authorization: ZenApiKey ${MY_TOKEN}" -H "Content-Type:application/json" "${CPD_URL}/v2/runtime_definitions" -d @</path/to/runtime/def/><custom-def-file-name>.json
    Note:
    • </path/to/runtime/def/> is the path to the runtime definition JSON file on your local computer.
    • In case of Python requests, you can pass the payload inline. For example requests.post(..., data=<content of custom-def-file-name.json file>)
    • You cannot skip the @ symbol. This symbol is mandatory.

    If the creation of the runtime definition is successful, you receive a response that contains a GUID that can you can use to retrieve, update or delete the runtime definition.

  9. Make sure that each compute node prepulls the new custom image. See Image download optimization.

Setting user-defined variables

You can add arbitrary environment variables to the runtime, for example if you want users to be able to access the Web through a proxy.

The variables that you add must be prefixed with _userdefined_. If you want to set the http_proxy variable, the variable must to be named _userdefined_http_proxy. If this prefix is missing, the variable is filtered out and is not available in the runtime.

To set environment variables to the runtime configuration file, add an env section to the top level of the JSON configuration file. See an example: 
"env": [
    {
        "name": "_userdefined_http_proxy",
        "value": "http://proxy:3129"
    },
    {
        "name": "_userdefined_https_proxy",
        "value": "http://proxy:3129"
    }
],
Important: Be careful when replacing variables such as LD_LIBRARY_PATH because this might lead to breaking changes. If you decide to modify this variable, make sure that you include the current value of the variable in addition to your changes.

Get the current value by starting the runtime and running the following command: !printenv LD_LIBRARY_PATH