Custom Runtime add-ons with Cloudera AI

Custom ML Runtimes enable you to create runtimes with your own choice of libraries and applications, but also to further customize existing ML Runtimes with additional configuration files or binaries such as connection drivers, without the effort of creating a new custom ML Runtime.

Custom Runtime add-on format requirements

The name of the add-on must contain only lowercase letters, numbers, underscores and hyphens. Also, it must be no longer than 35 characters. When added to Cloudera AI, the add-on will be prefixed with the term custom-addon-.
Aat least one path must be mentioned in the uploaded json file.
Paths in the metadata file must not end with a forward slash ( / ) character.
Requested paths will be symlinked in the workloads filesystem by the cdsw user, therefore these locations must not exist in the workload file system and the cdsw user must have write access to these locations.

Limitations of using Runtime add-ons

The following limitations are valid for using custom Runtime add-ons:

Injecting Python or R libraries into workloads using custom Runtime add-ons is not supported. To accomplish this, create a custom Runtime instead. For more information, see Creating customized ML Runtimes.
Misconfigured custom Runtime add-ons can break user workloads, for example, if metadata refers to paths that do not exist in the uploaded tarball archive.
You cannot add custom Runtime add-ons using the UI.
You can only disable but not update or remove custom Runtime add-ons.
Custom Runtime add-ons are mounted to workloads in read-only mode.

Working with custom Runtime add-ons

Package your dependencies into a tarball file, following the specified format.
As an Administrator, register the custom runtime add-on by uploading the tarball file using an API call on the command line.
After a custom runtime add-on is registered, as an Administrator enable or disable add-ons in the UI.
When an add-on is enabled, it is mounted to all newly started runtime-based workloads, in read-only mode.

Creating the custom Runtime add-on

Create a structure of files and folders with the following pattern and package it as a tar.gz archive file.

For example, to mount a folder called custom_folder to the /usr/bin/custom_folder directory, and the custom_file folder to the /usr/custom_file directory, the tarball file has the following internal structure:
note
Ensure that the Runtime Addon file is a valid tar.gz archive. You can verify its validity by using the file addon.tar.gz command.
```
text
        root@ecs1 customRuntime# file addon.tar.gz  
        addon.tar.gz: gzip compressed data, from Unix, original size modulo 2^32 271134720
```
The output must display gzip compressed data.
Create a json file that describes the custom runtime add-on to register in Cloudera AI. The json file has the following structure:
```
{
      "name" : "name-of-the-addon",
      "spec" : {"paths" : ["/usr/custom_file", "/usr/bin/custom_folder"]}
      }   
```
Upload the json and tar.gz files as an Administrator by using the following curl command:
```
curl -v -L '[***ML CLUSTER***]/api/v2/runtimeaddons/custom'  -F metadata=@metadata.json 
-F tarball=@addon.tar.gz  -H 'Authorization: Bearer [***APIv2 KEY***]'
```
Substitute the following elements:
- metadata.json: the name of the json file
- addon.tar.gz: the name of the tar.gz file
Once the runtime add-on has been uploaded, it will be enabled and mounted to all newly-initiated Runtime-based workloads.