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:

  1. 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-server.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.

    Important: The renamed JSON file name must end with -server.json, for example custom-runtime-def-1-server.json.

  2. Open the JSON configuration file that you renamed in an editor.

  3. Find the line containing the "image" attribute. It has the following format "image":"<docker registry>/<image name>:<image tag>, and a value such as "image": "<private-registry>/wslocal-runtime-py39main@sha256:fce1b04fcbf5272756693e170ebe7ae870abab724c7b6e30c4c4021790b36b79".

  4. Use the registry URL that you used when you registered the custom image.

  5. Change <image name>:<image tag> to the values you used when you registered your custom image.

  6. Optional: Set user defined variables. See Setting user-defined variables.

  7. Save the file.

  8. Upload the JSON file to the Cloud Pak for Data cluster. You can use the Cloud Pak for Data API or the OpenShift CLI (oc).

    If using the Cloud Pak for Data API:

    1. Get the required platform access token. The command returns the bearer token in the accessToken field:

      curl <CloudPakforData_URL>/v1/preauth/validateAuth -u <username>:<password>

    2. Upload the JSON file:

      curl -X PUT \
'https://<CloudPakforData_URL>/zen-data/v1/volumes/files/%2F_global_%2Fconfig%2F.runtime-definitions%2Fibm' \
-H 'Authorization: Bearer <platform-access-token>' \
-H 'content-type: multipart/form-data' \
-F upFile=@/path/to/runtime/def/<custom-def-name>-server.json

      Important: The uploaded JSON file name must end with server.json and the same file name must be used across all clusters to enable exporting and importing projects across cluster boundaries.

      If the changed JSON file was uploaded successfully, you will see the following response:

      {
    "_messageCode_": "Success",
    "message": "Successfully uploaded file and created the necessary directory structure"
}

    If using the OpenShift CLI (oc):

    1. Upload the JSON file:

      oc cp <custom-def-name>-server.json $(oc get pods -l component=ibm-nginx -o jsonpath='{.items[0].metadata.name}'):/user-home/_global_/config/.runtime-definitions/ibm/<custom-def-name>-server.json

  9. Ensure that the new custom image is prepulled to each compute node. 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 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