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:
docker | renkulab
- --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:
docker | renkulab
- --ssh
- Open a remote terminal through SSH.
Arguments
- <name>
Optional argument
pause
Pause an interactive session.
renku session pause [OPTIONS] <name>
Options
- -p, --provider <provider>
Session provider to use.
- Options:
renkulab
Arguments
- <name>
Optional argument
resume
Resume a paused session.
renku session resume [OPTIONS] <name>
Options
- -p, --provider <provider>
Session provider to use.
- Options:
renkulab
Arguments
- <name>
Optional argument
ssh-setup
Generate keys and configuration for SSH connections into sessions.
Note that this will not add any keys to a specific project, adding keys to a project has to be done manually or through the renku session start command by using the –ssh flag.
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:
docker | renkulab
- -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>
Number of GPU devices to add to the container (‘all’ to pass all GPUs).
- --memory <memory size>
Amount of memory required for the session.
- --volumes-from <volumes_from>
Mount volumes from the specified container(s)
- --volume <volumes>
A list of volume mounts (e.g. ‘/host/path/:/mount/path/in/container’)
- --volume-driver <volume_driver>
The name of a volume driver/plugin.
- --user <user>
Username or UID
- --tty
Allocate a pseudo-TTY.
- --stop-signal <stop_signal>
Signal to stop the container.
- --interactive
Keep STDIN open even if not attached.
- --shm-size <bytes>
Size of /dev/shm (bytes).
- --security-opt <security_opt>
Security Options.
- --runtime <runtime>
Runtime to use with this container.
- --rm <remove>
Automatically remove the container when it exits.
- --read-only
Mount the container’s root filesystem as read-only
- --publish-all
Publish all ports to the host.
- --privileged
Give extended privileges to this container.
- --platform <platform>
Set platform if server is multi-platform capable.
- --pids-limit <pids_limit>
Tune a container’s PIDs limit.
- --oom-score-adj <oom_score_adj>
Tune host’s OOM preferences (-1000 to 1000).
- --oom-kill-disable
Disable OOM Killer.
- --network <network>
Connect a container to a network.
- --name <name>
The name for this container.
- --memory-swap <memswap_limit>
Swap limit equal to memory plus swap.
- --memory-swappiness <mem_swappiness>
Tune container memory swappiness (0 to 100).
- --memory-reservation <mem_reservation>
Memory soft limit.
- --mac-address <mac_address>
MAC address to assign to the container.
- --kernel-memory <bytes>
Kernel memory limit (bytes).
- --isolation <isolation>
Isolation technology to use.
- --init
Run an init inside the container that forwards signals and reaps processes
- --hostname <hostname>
Optional hostname for the container.
- --group-add <group_add>
List of additional group names and/or IDs that the container process will run as.
- --env <environment>
Environment variables to set inside the container, in the format ‘VAR=VAL’
- --entrypoint <entrypoint>
The entrypoint for the container.
- --domainname <domainname>
Container NIS domain name.
- --dns-search <dns_search>
DNS search domains.
- --dns-opt, --dns-option <dns_opt>
Additional options to be added to the container’s
resolv.conf
file.
- --dns <dns>
Set custom DNS servers.
- --device <devices>
Expose host devices to the container.
- --device-cgroup-rule <device_cgroup_rules>
A list of cgroup rules to apply to the container.
- --cpuset-mems <cpuset_mems>
Memory nodes (MEMs) in which to allow execution (‘0-3’, ‘0,1’).
- --cpuset-cpus <cpuset_cpus>
CPUs in which to allow execution (‘0-3’, ‘0,1’).
CPU shares (relative weight).
- --cpu-rt-runtime <cpu_rt_runtime>
Limit CPU real-time runtime in microseconds.
- --cpu-rt-period <cpu_rt_period>
Limit CPU real-time period in microseconds.
- --cpu-quota <cpu_quota>
Microseconds of CPU time that the container can get in a CPU period.
- --cpu-period <cpu_period>
The length of a CPU period in microseconds.
- --cpu-percent <cpu_percent>
Usable percentage of the available CPUs.
- --cpu-count <cpu_count>
Number of usable CPUs.
- --cgroup-parent <cgroup_parent>
Override the default parent cgroup.
- --cap-drop <cap_drop>
Drop Linux capabilities.
- --cap-add <cap_add>
Add Linux capabilities.
- --blkio-weight <blkio_weight>
Block IO (relative weight), between 10 and 1000, or 0 to disable.
- --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:
docker | renkulab
- -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.
This command accepts a subset of arguments of the docker run
command. See
its help for the list of supported arguments: renku session start --help
.
Accepted values are the same as the docker run
command unless stated
otherwise.
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 <session-id> successfully started, use 'renku session open --ssh <session-id>' or 'ssh <session-id>' 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-session-id
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.
If the provider supports sessions hibernation, this command allows pausing and resuming
sessions as well.
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.
If a provider supports session hibernation (e.g. renkulab
provider) you can pause a session using
its ID
:
$ renku session pause renku-test-e4fe76cc
A paused session can be later resumed:
$ renku session resume renku-test-e4fe76cc
Note
Session ID
doesn’t need to be passed to the above commands if there is only one interactive session available.