Cloudera Docs

Uploading ML Runtime add-on repository files using the APIv2 endpoint

Cloudera AI provides an APIv2 endpoint that allows Administrators to upload and register ML Runtime add-on repository files by submitting the JSON file as a multipart upload.

The API accepts a JSON ML Runtime add-on repository file, validates its contents, and then triggers add-on loading asynchronously. Administrators can upload add-ons using Swagger UI or via command-line tools such as cURL.

The Cloudera-provided ML Runtime add-on repository file does not include a registry prefix in the image_identifier field. When add-ons are loaded, Cloudera AI automatically prepends the pinned Registry of the workbench if no registry is specified.

The Endpoint details are as follows:

  • Method: POST

  • Path: /api/v2/runtimeaddons

  • Authentication: Administrator only (APIv2 key)

Uploading ML Runtime add-on repository file using APIv2 with Swagger UI

  1. In the Cloudera console, click the Cloudera AI tile.

    The Cloudera AI Workbenches page displays.

  2. On the left sidebar, click User Settings and navigate to API Keys > Swagger UI.
  3. Click the Authorize button in the top right part of the window.
    Figure 1. Authorize button

    The Available authorizations window displays.

    Figure 2. Authorization
  4. Provide the Bearer API Key in the Value field and click Authorize.
  5. Close the Available authorizations window.

    The icon for the Authorize button has changed.

    Figure 3. Authorize icon
  6. Find POST /api/v2/runtimeaddons among the services and open it.
  7. Use the file upload control for the file (formData) field to upload your repo-assembly.json file.
Figure 4. ML Runtime add-on repository file load with Swagger UI

Uploading ML Runtime add-on repository file using APIv2 with cURL

Make sure the following requirements are fulfilled when using cURL for uploading add-ons:

  • The Content-Type must be multipart/form-data.

  • The Form field name must be file.

  • The uploaded file must be a json Runtime Add-on Repository file, repo-assembly.json, format

  • The field name for the json content must be file.

  • The json file must include:

    • assembly_metadata_version - the value must be 1

    • runtime_addons - must be a non-empty array

  • Maximum 10 add-ons per request

  • Add-on requirements:

    • unique_name

    • component - must be one of: Spark, HadoopCLI, Ozone

    • displayName

    • image_identifier

    • specialization - must be present

    • runtime_addon_metadata_version - the value must be 1

cURL example command:
curl -X POST \
  -H "Authorization: Bearer $API_V2_KEY" \
  -F "file=@/tmp/repo-assembly.json;type=application/json" \
  "$WORKBENCH_BASE_URL/api/v2/runtimeaddons"

Verifying load status

To verify the load status and to review any errors that occurred during processing follow the instructions:

  1. In the Cloudera console, click the Cloudera AI tile.

    The Cloudera AI Home page displays.

  2. Click on the name of the workbench.

    The Cloudera AI Workbenches Home page displays.

  3. Select Site Administration > Runtimes > Runtime Add-ons.

Alternatively, you can use the existing API: GET /api/v2/runtimeaddons.