10.5. Launch a Tool

To launch a Tool you need to have EXECUTE permissions for it. For more information see 13. Permissions.

You also can launch a tool via CLI. See here.

Launch the latest version

  1. To run an instance with a selected Tool navigate to the Tools tab and click the Tool name.
  2. Click the Run button in the top-right corner of the screen and the latest version with default settings will be launched (these are defined for Cloud Pipeline globally).
    CP_LaunchTool
  3. If you want to change settings, you shall click the arrow near the Run button → Custom settings.
    CP_LaunchTool
  4. Launch tool page will be opened.
    CP_LaunchTool

  5. If the Price type is set as "On-demand" - at the Launch page, an additional checkbox Auto pause appears:
    CP_LaunchTool
    This checkbox allows to enable automatic pausing on-demand instance if it is not used. Such behavior could be controlled by Administrators using a set of parameters at System Preferences (see here).

    Please note, this checkbox will not be displayed if any cluster is configured ("Static" or "Autoscaled").

  6. If the Price type is set as "On-demand" - at the Launch page, an additional control Maintenance appears. It allows to configure schedule for automatical pause/resume a tool run:
    CP_LaunchTool
    It could be useful when the tool is launched for a long time (several days/weeks) but it shall not stand idle, just increasing costs, in weekends and holidays, for example.
    For more details, how to configure the automatically schedule for a run see 6.2. Launch a pipeline (item 5).

    Please note, the Maintenance control will not be displayed if any cluster is configured ("Static" or "Autoscaled").

    Users (who have permissions to pause/resume a run) can create/view/modify/delete schedule rules anytime launched run is active via the Run logs page - for more details see 11. Manage runs.

  7. Define the parameters in the Exec environment, Advanced and Parameters sections.

  8. Click the Launch button in the top-right corner of the screen.
    CP_LaunchTool
    Please note, that the current user can launch a tool only if he/his group has corresponding permissions on that tool (for more information see 13. Permissions), but the Launch button may be disabled also for one of the following reasons:

    • execution isn't allowed for specified docker image;
    • read operations aren't allowed for specified input or common path parameters;
    • write operations aren't allowed for specified output path parameters.

    In such cases, hover over the Launch button to view warning notification with a reason of a run forbiddance, e.g.:
    CP_LaunchTool

Note: you can also launch a tool with the same settings via the CLI command or API request.
To generate the corresponding command/request click the button CP_LaunchTool near the "Launch" button. For more details see here.

Launch particular Tool version

  1. To run a particular version click the Versions section.
  2. Select a version and click the Run button. The selected version with default settings will be launched (these are defined for Cloud Pipeline globally).
    CP_LaunchTool
  3. If you want to change settings, you shall click the arrow near the Run button → Custom settings.
    CP_LaunchTool
  4. Launch a tool page will be opened.
  5. Define the parameters.
  6. Click the "Launch" button.

Example 1

In this example, we will run the "Ubuntu" Tool with custom settings: 30 Gb hard drive, 4 CPU cores, and 16 Gb RAM.
Note: "Start idle" box is ticked to allow SSH access to the running Tool. To learn more about interactive services see 15. Interactive services.
Click the Launch button in the top-right corner of the screen when all parameters are set.
CP_LaunchTool

After the Tool is launched you will be redirected to the Runs tab:

  1. Click the Log button to see run details after instance finishes initialization.
    CP_LaunchTool
  2. Wait until the SSH button will appear at the Run logs page, click it
    CP_LaunchTool
  3. You will be redirected to the page with interactive shell session inside the Docker container. For example, we can list "/" directory content inside the container.
    CP_LaunchTool

Launch a Tool with "friendly" URL

User can specify a "friendly"-format endpoint URL for persistent services. This produces the endpoint URL for the selected interactive service in a more friendly/descriptive format instead of the default general <host>/pipeline-<RunID>-<port>.
"Friendly" format can be configured before the specific service launch in the "Advanced" section of the Launch page.
This format has the following structure - <custom-host>/<friendly_url>, where:

  • <custom-host> - valid existing domain name. If it's not specified, the default host name will be used
  • <friendly_url> - valid endpoint name. If it's not specified but the <custom-host> is specified - the final endpoint URL will be equal the <custom-host> only

Note: specified endpoint URL shall be unique among all active runs.

Example 2

In this example we will configure a pretty URL for RStudio Tool.
Note: for do that, user account shall be registered within CP users catalog and granted READ & EXECUTE permissions for the rstudio Tool.

  1. Navigate to the Tools tab.
  2. Select/find RStudio Tool in the list:
    CP_LaunchTool
  3. At the opened page hover the "Run" button and click the appeared "Custom settings" point:
    CP_LaunchTool
  4. Click the "Advanced" control (a), input desired "Friendly URL" (b) (name shall be unique) and then click the "Launch" button (c), e.g.:
    CP_LaunchTool
  5. Open the Run logs page of RStudio Tool, wait until the tool successfully starts.
  6. Click the hyperlink opposite "Endpoint" label:
    CP_LaunchTool
  7. In a new tab RStudio will be opened. Check that the URL is in the "pretty" format you specified at step 4:
    CP_LaunchTool

Launch a tool with "hosted" applications

"Long-running" Cloud Pipeline applications may occasionally failed.
And one of the main task caused this situation - saving the internal access to the services (e.g. if a database was hosted) as the IP and name (which match the pod) are being changed during the default run restarts.

For that, there is a special option to assign an internal DNS name to the run.

Name of the service and a list of ports can be supplied by the user in the GUI, at the Launch form before the run:
CP_LaunchTool

Pop-up for DNS configuration for the upcoming run will appear:
CP_LaunchTool

To configure the internal DNS:

  • specify the valid service name, e.g.:
    CP_LaunchTool
  • specify the origin port of the application that should be hosted, e.g.:
    CP_LaunchTool
    Please note, value of the Target port is being specified firstly the same as the origin Port value (automatically)
  • change the value of the Target port if needs, e.g.:
    CP_LaunchTool
  • if the configuration of an additional origin port is required, click the button "+ Add ports configuration":
    CP_LaunchTool
    Specify values for the additional port and its target port. If the configuration of an additional origin port is required, click the button "+ Add ports configuration" again.
  • to delete "extra" added port in the list, click the delete icon for it, e.g.:
    CP_LaunchTool
  • after the service is configured, click the Save button to confirm:
    CP_LaunchTool

Configured DNS service is shown in the Advanced section of the Launch form:
CP_LaunchTool

Example of "hosted" application running

In the example below, we will run and "host" RStudio tool.

  1. Open the Tools page and find RStudio tool:
    CP_LaunchTool
  2. At the tool's page, click the Settings tab:
    CP_LaunchTool
    Save endpoints' port values.
  3. Select Run → Custom settings:
    CP_LaunchTool
  4. At the Launch page, expand the Advanced section and click the Configure button near the "Internal DNS name" label:
    CP_LaunchTool
  5. In the appeared pop-up, specify the service name, e.g.:
    CP_LaunchTool
  6. Specify ports saved at step 2. To add the second port use "+ Add ports configuration" button:
    CP_LaunchTool
    Click the Save button.
  7. Check that configured service is displayed at the Launch page:
    CP_LaunchTool
  8. Click the Launch button and launch the run.
  9. Open the Run logs page of the just-launched run.
  10. FQDN of both configured services are shown in the GUI - at the Run logs page:
    CP_LaunchTool
    Currently, the format of the service FQDN is <service_name>.default.svc.cluster.local:<origin_port>
  11. Wait until SSH hyperlink appears.
  12. Click the SSH hyperlink to open the Web-terminal.
  13. In the opened terminal, perform the command: curl -I rstudio-example-service.default.svc.cluster.local:8788 to view info about RStudio hosted service:
    CP_LaunchTool
  14. Perform the command: curl -I rstudio-example-service.default.svc.cluster.local:3838 to view info about Shiny hosted service:
    CP_LaunchTool

Instance management

Instance management allows to set restrictions on instance types and price types for tool runs.

User shall have ROLE_ADMIN or to be an OWNER of the Tool to launch Instance management panel. For more information see 13. Permissions.

To open Instance management panel:

  1. Click CP_LaunchTool button in the left upper corner of the main tool page.
  2. Click "Instance management":
    CP_LaunchTool
  3. Such panel will be shown:
    CP_LaunchTool

On this panel you can specify some restrictions on allowed instance types and price types for launching tool.

Here you can specify:

Field Description Example
Allowed tool instance types mask This mask restrict for a tool allowed instance types. If you want for that tool only some of "large m5..." instances types will be able, mask would be m5*.large*
CP_LaunchTool
In that case, before launching tool, dropdown list of available node types will be look like this:
CP_LaunchTool
Allowed price types In this field you may restrict, what price types will be allowed for a user. If you want "On-demand" runs only for that tool will be able, select it in the dropdown list:
CP_LaunchTool
In that case, before launching tool, dropdown list of price types will be look like this:
CP_LaunchTool

To apply set restrictions for a tool click CP_LaunchTool button.

Setting restrictions on allowed instance types/price types is a convenient way to minimize a number of invalid configurations runs.
Such restrictions could be set not only for a tool, but on another levels too.
In CP platform next hierarchy is set for applying of inputted allowed instance types (sorted by priority):