NVIDIA Clara Deploy SDK User Guide
1.0

17.1. Overview of clara

clara is a command line interface for managing and interacting with the Clara Deploy SDK. clara looks for a file named config.yaml in ~/.clara/. You can specify an alternate configuration by setting the --config flag and can point to a remote host using the --host flag. You can execute commands with --verbose flag to get command output with additional details.

Note: Using kubectl and/or argo cli to manage clara jobs might leave clara in an inconsistent state.

Use the following syntax to run clara commands from you terminal window:

clara [command] [type] [flags]

  • command: Specifies the operation to perform on one or more resources. clara supports several commands: create, delete, describe, download, list etc. These commands are explained in detail in the clara commands documentation.
  • type: Specifies the resource type. Resource types are case-sensitive. Currently, clara has four resource types: “pipeline”, “job”, “model” and “payload” . Many commands do not support every type. For more information on which types are supported by an individual command, run clara [command] --help.
  • flags: Specifies optional or required flags. For example, you can use the --config flag to specify the location of an alternate configuration.

If you need help, run clara --help from the terminal window.

The following table includes short descriptions and the general syntax for all clara commands. This table will expand as support is added for additional commands.

Command Syntax Description
cancel clara cancel [flags] Cancel a resource
config clara config [flags] Configures NGC credentials for CLI
create clara create [type] [flags] Create a resource.
delete clara delete [type] [flags] Delete a resources.
describe clara describe [type] [flags] Describe a resource.
download clara download JOB_ID:SRC_PATH [DEST_PATH] [flags] Download files associated with a job.
list clara list [type] [flags] List all instances of specified resource type.
logs clara logs [flags] Read clara job operator logs.
start clara start [type] [flags] Start a resource.
upload clara upload [flags] Upload a resource
version clara version Displays the clara cli and clara platform version info

For more information about a command, enter clara [command] --help in your terminal window.

The following table includes a list of all the supported resource types. This table will expand as we add support for additional resource types.

Note: Many commands do not support every type. For more information on which types are supported by an individual command, run clara [command] --help.

Resource Name API Service Description
pipeline Pipelines Service References a single pipeline in the Clara Deploy SDK.
job Jobs Service References a single instance of a pipeline execution on a payload in Clara Deploy SDK.
model Models Service References a TRITON model
payload Payloads Service References a single payload in Clara Deploy SDK.
pipelines Pipelines Service References pipelines in the Clara Deploy SDK.
jobs Jobs Service References instances of pipeline executions on a payload in Clara Deploy SDK.
model Models Service References TRITON models
payloads Payloads Service References payloads in Clara Deploy SDK.

For more information about resource types, enter clara [command] [type] --help in your terminal window.

Use the following set of examples to help you familiarize yourself with running the commonly used clara operations:

Copy
Copied!
            

# Configure NGC credentials for use by CLI. Default 'orgteam' is 'nvidia/clara' $ clara config --key NGC_API_KEY [--orgteam NGC_ORG/NGC_TEAM] [-y|--yes] # Upload model $ clara create model -p [MODEL_DIRECTORY] -t [MODEL_TYPE] [--raw] # List models $ clara list models # Create a new pipeline $ clara create pipeline -p PIPELINE_DEFINITION_FILE # See the pipeline definition being used $ clara describe pipeline -p PIPELINE_ID # Create a new job $ clara create job -n NAME -p PIPELINE_ID [-f [FILE | DIRECTORY]] [-i JOB_PRIORITY] [--start] # Start a created job $ clara start job -j JOB_ID [-a KEY=VALUE]... # Get job status and associated information $ clara describe job -j JOB_ID # Get list of jobs $ clara list jobs [--all] | [--canceled] | [--evicted] | [--faulted] | [--healthy] | [--pending] | [--running] | [--stopped] | [--terminated] | [--quiet] # Get list of all pipelines $ clara list pipeliens # Submit request to cancel job(s) $ clara cancel jobs [-j JOB_ID1,JOB_ID2...] [--all] # Upload payload $ clara upload payload -p PAYLOAD_ID -f {FILE | DIRECTORY} # Delete payloads $ clara delete payloads -p PAYLOAD_ID[,PAYLOAD_ID...]

Plugins extend clara functionality. They are described in more detail in the plugin overview document.

17.1.5.1. Examples: Creating and Using Plugins

Use the following set of examples to help you familiarize yourself with writing and using clara plugins:

Copy
Copied!
            

# Create a simple plugin in any language and name the resulting executable file # so that it begins with the prefix "clara-" $ cat ./clara-hello #!/bin/bash # This plugin prints the words "hello world" echo "hello world" # With our plugin written, let's make it executable $ sudo chmod +x ./clara-hello # and move it to a location in our PATH $ sudo mv ./clara-hello /usr/local/bin # We have now created and "installed" a Clara plugin. # We can begin using our plugin by invoking it from clara as if it were a regular command $ clara hello

Copy
Copied!
            

hello world

Copy
Copied!
            

# We can "uninstall" a plugin by simply removing it from our PATH $ sudo rm /usr/local/bin/clara-hello

We can think of plugins as a means to build more complex functaionlity on top of the existing kubectl commands.

17.1.5.2. Examples: Using the clara-platform plugin

clara-platform plugin is a command-line interface for managing clara deploy platform. More information about clara-platform can be found here.

Copy
Copied!
            

# Start the Clara Deploy SDK (clara platform must be pulled for this command to work. See `clara-pull` plugin below) $ clara platform start # Stop the Clara Deploy SDK $ clara platform stop [-y | --yes] # Restart the Clara Deploy SDK $ clara platform restart [-y | --yes]


17.1.5.3. Examples: Using the clara-dicom plugin

clara-dicom manages a DICOM Adapter that facilitates the input and output of DICOM files to and from the Clara Deploy SDK. More information about clara-dicom can be found here.

Copy
Copied!
            

# Start the DICOM Adapter with default configuration $ clara dicom start # Start the DICOM Adapter with custom configuration $ clara dicom start -f CONFIG-FILE # Restart the DICOM Adapter $ clara dicom restart [-y | --yes] # Stop the DICOM Adapter $ clara dicom [-y | --yes] # Add (SCP) AE Title-Pipeline mapping $ clara dicom create aetitle [-n NAME] -a AE_TITLE [-o] [-i UID1,UID2,UID3] [-p Job.Processor.Assembly.NameSpace.Class] key1=value1 key2=value2 key3=value3 # Delete (SCP) AE Title-Pipeline mapping $ clara dicom delete aetitle -n NAME # List all (SCP) AE Title-Pipeline mappings $ clara dicom list aetitle # Describe a (SCP) AE Title-Pipeline mappings $ clara dicom describe aetitle -a AE_TITLE # Add DICOM Source for SCP $ clara dicom create source -a AE_TITLE -i HOSTNAME_IP # Delete DICOM Source of SCP $ clara dicom delete source -n NAME # List all DICOM Sources of SCP $ clara dicom list source # Add DICOM Destination for Clara SCU $ clara dicom create destination -a AE_TITLE -i HOSTNAME_IP -N NAME -p PORT # Delete DICOM Destination of SCU $ clara dicom delete destination -n NAME # List all DICOM Destinations of SCU $ clara dicom list destination # Get DICOM Adapter health and status $ clara dicom status


17.1.5.4. Examples: Using the clara-render plugin

clara-render manages a cinematic render service that facilitates visualizing medical images that are output from the Clara Deploy SDK. More information about clara-render can be found here.

Copy
Copied!
            

# Start the render service $ clara render start # Restart the render service $ clara render restart [-y | --yes] # Stop the render service $ clara render stop [-y | --yes]


17.1.5.5. Examples: Using the clara-pull plugin

clara-pull facilitates installation of different Clara Components and Reference Pipelines. More information about clara-pull can be found here. If a version is not specified, the latest version of the resource is downloaded.

Copy
Copied!
            

# Pull clara platform helm charts and configure CLI $ clara pull platform [ -v VERSION_NUMBER ][ -y | --yes ] # Pull clara dicom-adapter helm charts and configure CLI $ clara pull dicomadapter [ -v VERSION_NUMBER ][ -y | --yes ] $ clara pull dicom-adapter [ -v VERSION_NUMBER ][ -y | --yes ] $ clara pull dicom [ -v VERSION_NUMBER ][ -y | --yes ] # Install clara-renderer helm charts $ clara pull clararenderer [ -v VERSION_NUMBER ][ -y | --yes ] $ clara pull clara-renderer [ -v VERSION_NUMBER ][ -y | --yes ] $ clara pull render [ -v VERSION_NUMBER ][ -y | --yes ] $ clara pull renderer [ -v VERSION_NUMBER ][ -y | --yes ] # Install clara management console helm charts $ clara pull claraconsole [ -v VERSION_NUMBER ] [ -y | --yes ] $ clara pull clara-console [ -v VERSION_NUMBER ] [ -y | --yes ] $ clara pull console [ -v VERSION_NUMBER ] [ -y | --yes ] # Pull clara pipeline $ clara pull pipeline [-v VERSION_NUMBER] [-d DESTINATION_DIR]

17.1.5.5.1. Examples: Using the clara-console plugin

clara-console manages the Clara Management Console instance. More information about clara-console can be found here.

Copy
Copied!
            

# Start the Clara Management Console (the Clara Management Console chart must be pulled for this command to work) $ clara console start # Restart the Clara Management Console $ clara console restart [-y | --yes] # Stop the Clara Management Console $ clara console stop [-y | --yes]

© Copyright 2018-2020, NVIDIA Corporation. All rights reserved. Last updated on Jun 28, 2023.