renku session

Manage interactive sessions.

Description

Manage sessions through the command line interface by starting and stopping them. It’s possible to list the current sessions and to connect to them.

Currently, two providers are supported: docker and renkulab. More on this later.

Commands and options

renku session

Session commands.

renku session [OPTIONS] COMMAND [ARGS]...

ls

List interactive sessions.

renku session ls [OPTIONS]

Options

-p, --provider <provider>

Backend to use for listing interactive sessions.

Options: renkulab | docker

-c, --config <config file>: YAML file containing configuration for the provider.

--columns <columns>: Comma-separated list of column to display: id, status, url, ssh, start_time, commit, branch, provider.

--format <format>

Choose an output format.

Options: tabular | log

open

Open an interactive session.

renku session open [OPTIONS] <name>

Options

-p, --provider <provider>

Session provider to use.

Options: renkulab | docker

--ssh: Open a remote terminal through SSH.

Arguments

<name>: Required argument

ssh-setup

Setup keys for SSH connections into sessions.

renku session ssh-setup [OPTIONS]

Options

-k, --existing-key <private key file>: Existing private key to use.

--force: Overwrite existing keys/config.

start

Start an interactive session.

renku session start [OPTIONS]

Options

-p, --provider <provider>

Backend to use for creating an interactive session.

Default: docker
Options: renkulab | docker

-c, --config <config file>: YAML file containing configuration for the provider.

--image <image_name>: Docker image to use for the session.

--cpu <cpu quota>: CPUs quota for the session.

--disk <disk size>: Amount of disk space required for the session.

--gpu <GPU quota>: GPU quota for the session.

--memory <memory size>: Amount of memory required for the session.

--force-build: Always build image and don’t check if it exists.

--port <port>: Local port to use (random if not specified).

--ssh: Enable ssh connections to the session.

stop

Stop an interactive session.

renku session stop [OPTIONS] <name>

Options

-p, --provider <provider>

Session provider to use.

Options: renkulab | docker

-a, --all: Stops all the running containers.

Arguments

<name>: Optional argument

Docker provider

The docker provider will take the current state of the repository, build a docker image (if one does not already exist) and then launch a session with this image. In addition to this, the docker provider will mount the local repository inside the docker container so that changes made in the session are immediately reflected on the host where the session was originally started from.

Please note that in order to use this provider Docker is expected to be installed and available on your computer. In addition, using this command from within a Renku interactive session started from the Renku website is not possible. This command is envisioned as a means for users to quickly test and check their sessions locally without going to a Renku deployment and launching a session there, or in the case where they simply have no access to a Renku deployment.

$ renku session start -p docker

The command first looks for a local image to use. If a local image isn’t found, it searches the remote Renku deployment (if any) and pulls the image if it exists. Finally, it prompts the user to build the image locally if no image is found. You can force the image to always be built by using the --force-build flag.

Renkulab provider

The renkulab provider will launch a regular interactive session in the Renku deployment that hosts the current project. If the project has not been uploaded/created in a Renku deployment then this provider will not be able to launch a session. This provider is identical to going through the Renku website and launching a session “manually” by selecting the project, commit, branch, etc.

Please note that there are a few limitations with the renkulab provider:

If the user is not logged in (using the renku login command) then sessions can only be launched if the specific Renku deployment supports anonymous sessions.
When launching anonymous sessions local changes cannot be reflected in them and changes made inside the session cannot be saved nor downloaded locally. This feature should be used only for adhoc exploration or work that can be discarded when the session is closed. The CLI will print a warning every time an anonymous session is launched.
Changes made inside the interactive session are not immediately reflected locally, users should git pull any changes made inside an interactive session to get the same changes locally.
Local changes can only be reflected in the interactive session if they are committed and pushed to the git repository. When launching a session and uncommitted or unpushed changes are present, the user will be prompted to confirm whether Renku should commit and push the changes before a session is launched. The session will launch only if the changes are committed and pushed.

$ renku session start -p renkulab

SSH connections to remote sessions

You can connect via SSH to remote (Renkulab) sessions, if your project supports it.

To see if your project supports SSH, you can run renku project show and check the SSH Supported flag. If your project doesn’t support SSH, update the project template or contact the template maintainer to enable SSH support on the template.

You can start a session with SSH support using:

$ renku session start -p renkulab --ssh
Your system is not set up for SSH connections to Renkulab. Would you like to set it up? [y/N]: y
[...]
Session sessionid successfully started, use 'renku session open --ssh sessionid' or 'ssh sessionid' to connect to it

This will create SSH keys for you and setup SSH configuration for connecting to the renku deployment. You can then use the SSH connection name (ssh renkulab.io-myproject-sessionid in the example) to connect to the session or in tools such as VSCode.

Note

If you need to recreate the generated SSH keys or you want to use existing keys instead, you can use the renku session ssh-setup command to perform this step manually. See the help of the command for more details.

Alternatively, you can use renku session open --ssh <session_id> to directly open an SSH connection to the session.

You can see the SSH connection name using renku session ls.

SSH config for specific sessions is removed when the session is stopped.

Managing active sessions

The session command can be used to also list, stop and open active sessions. In order to see active sessions (from any provider) run the following command:

$ renku session ls -p renkulab
ID                   STATUS    URL
-------------------  --------  -------------------------------------------------
renku-test-e4fe76cc  running   https://dev.renku.ch/sessions/renku-test-e4fe76cc

An active session can be opened by using its ID from the list above. For example, the open command below will open the single active session in the browser.

$ renku session open renku-test-e4fe76cc

An active session can be stopped by using the stop command and the ID from the list of active sessions.

$ renku session stop renku-test-e4fe76cc

The command renku session stop --all will stop all active sessions regardless of the provider.