Important:

IBM Cloud Pak® for Data Version 4.7 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.7 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

Uploading the custom configuration

After the custom image was registered, you need to modify the JSON configuration file you downloaded and then upload it to the Cloud Pak for Data cluster under a new name.

Important: Custom runtime configurations, just like custom images, need to be maintained manually. Custom configurations and runtime images are not updated automatically.

To upload the image through a custom configuration:

Rename the JSON configuration file that you downloaded to start using the custom image. The name you use should be something like custom-def-name.json, where custom-def-name is a name that is unique within all runtime definitions of the Cloud Pak for Data instance. The unique name that you provide is listed in the Software version dropdown when creating the environment template.
Open the JSON configuration file that you renamed in an editor.
Find the line containing the "image" attribute. It has the following format "image":"<image registry>/<image name>:<image tag>, and a value such as "image": "<private-registry>/wslocal-runtime-py39main@sha256:fce1b04fcbf5272756693e170ebe7ae870abab724c7b6e30c4c4021790b36b79".
Replace name, display_name, description and author with your own data.
Use the registry URL that you used when you registered the custom image.
Change <image name>:<image tag> to the values you used when you registered your custom image.
Optional: Set user defined variables. See Setting user-defined variables.
Save the file.
Create a runtime definition with the settings in the JSON file by using the Cloud Pak for Data API.
1. Get an authorization token. For more information, see Generating an authorization token or API key.
2. Create a runtime definition with the settings in the JSON file::
```
curl -k -X POST -H "Authorization: Bearer ${MY_TOKEN}" -H "Content-Type:application/json" "${CPD_URL}/v2/runtime_definitions" -d @</path/to/runtime/def/><custom-def-name>.json
```
  If the creation of the runtime definition is successful, you receive a response including a UUID that can you can use to retrieve, update or delete the runtime definition. </path/to/runtime/def/> is the path to the runtime definition JSON file on your local computer. Note that using the @ symbol is mandatory.
Ensure that the new custom image is prepulled to each compute node. See Image download optimization.

Updating and deleting runtime definitions

To update or delete a runtime definition, you need to know its GUID. You can get a list of available runtime definitions and their GUIDs by running the following command:

curl -k -X GET -H "Authorization: Bearer ${MY_TOKEN}" "${CPD_URL}/v2/runtime_definitions" | jq -r '.resources[] | "\(.entity.name) -- \(.metadata.guid)"'

To update an existing runtime definition, call the update endpoint with the name of the existing runtime definition:

myRuntimeDefinitionID=<runtime-definition-name>; curl -kX PUT  "${CPD_URL}/v2/runtime_definitions/$myRuntimeDefinitionID"  --header "Authorization: Bearer ${MY_TOKEN}" -d @${myRuntimeDefinition}.json

To delete runtime definitions that are not in use anymore, call the delete endpoint:

curl -kX DELETE \
"${CPD_URL}/v2/runtime_definitions/${myRuntimeDefinitionID}" \
--header "Authorization: Bearer ${MY_TOKEN}"

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 via 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 will not be 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 as follows:

"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 as this might lead to breaking changes. If you decide to modify this variable, ensure that you include the current value of the variable in addition to your changes.

You can retrieve the current value by starting the runtime and running the following command:

!printenv LD_LIBRARY_PATH

Parent topic: Building custom images