Cloudera Docs

Custom Runtime addons 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 addon format requirements

  1. The name of the addon must contain only lowercase letters, numbers, underscores and hyphens. Also, it must be no longer than 35 characters. When added to Cloudera AI, the addon will be prefixed with the term custom-addon-.
  2. Aat least one path must be mentioned in the uploaded json file.
  3. Paths in the metadata file must not end with a forward slash ( / ) character.
  4. 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 addons

The following limitations are valid for using custom Runtime addons:

  • Injecting Python or R libraries into workloads using custom Runtime addons is not supported. To accomplish this, create a custom Runtime instead. For more information, see Creating customized ML Runtimes.
  • Misconfigured custom Runtime addons 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 addons using the UI.
  • You can only disable but not update or remove custom Runtime addons.
  • Custom Runtime addons are mounted to workloads in read-only mode.

Working with custom Runtime addons

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

Creating the custom Runtime addon

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

  2. Create a json file that describes the custom runtime addon 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"]}
      }
  3. 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 addon has been uploaded, it will be enabled and mounted to all newly-initiated Runtime-based workloads.