Compute is in preview, and the
v1alpha API can change.general-purpose Instances only. A general-purpose Instance runs in its own virtual machine, so a shell session reaches a real container through that isolation boundary. unikernel Instances don’t have a shell, so the Shell tab and datumctl compute exec aren’t available for them. For more about the two classes, see Choose a runtime class.
How a session works
Opening a shell creates a session: a request to run one command, with or without a terminal, in one container of one Instance. The session has a time limit, and it ends when the command exits, when you close it, when it reaches its time limit, or when the platform can’t keep it open. A session is single-use. Reconnecting after it ends, or running another command, starts a new session. Two ways to open a session:Cloud Portal
Open an interactive shell from the Instance’s Shell tab.
datumctl
Run
datumctl compute exec for an interactive shell or a single command.Cloud Portal
Open an interactive shell in a runninggeneral-purpose Instance from the Datum Cloud portal.
Before you begin
- Deploy a
general-purposeworkload with at least oneAvailableInstance. For more information, see Run a container image. - Your account needs the Compute Admin role to open a shell. For more information, see Permissions.
Open a shell
- Open your project in the Datum Cloud portal.
- Go to Compute, then Workloads.
- Select the workload, then select the Instance you want a shell in.
- Select the Shell tab.
- Choose a Container. If the Instance runs only one container, it’s already selected.
- Enter a Command, or select one of the quick picks,
/bin/shor/bin/bash. The field defaults to/bin/sh. - Select Connect.
Open the shell in its own window
Select Open in new window to continue the session in a console-only window, separate from the rest of the portal. The option is hidden on phones and other small screens, where the shell stays in the page instead. Opening a shell from a shared link only fills in the Container and Command fields. Nothing runs until you select Connect yourself.End a session
Select Close shell to end the session and stop the command. Leaving the page or closing the tab also ends the session.datumctl
datumctl compute exec runs a command, interactively or once, in a container of a running general-purpose Instance.
Before you begin
-
Select a project, install the
computeplugin, and get access to Compute. For more information, see Set up your project. -
execneeds a version of thecomputeplugin that includes it. Ifdatumctl compute exec --helpdoesn’t show the command, upgrade the plugin:For more on installing and upgrading plugins, see Using plugins. -
Deploy a
general-purposeworkload with at least oneAvailableInstance. For more information, see Run a container image.
Open an interactive shell
Run the following command, replacingINSTANCE_NAME with the name of the Instance:
-i keeps standard input open, and -t allocates a terminal. Together, they give you an interactive shell. The following example opens one in an Instance named api-dfw-0:
Run a single command
Omit-it to run a command once and print its output, without an interactive shell:
Choose a container
If the Instance runs more than one container, name the one to run the command in with-c:
-c, the command runs in the Instance’s only container. general-purpose Instances run exactly one container today, so you only need -c once an Instance runs more than one.
Exit codes
datumctl compute exec passes through the result of the command or the session:
For the full list of reasons the platform can end a session, see Why a session ended.
For the full flag reference, run
datumctl compute exec --help.
Security
- End-to-end encryption. The connection between your browser or
datumctland the Instance’s container is encrypted all the way to the cell that runs the Instance. - A one-time key that stays local. Each session generates its own key pair. The private key never leaves your browser or your machine, and it isn’t sent to Datum.
- Every session is recorded. Opening, connecting, and ending a session each appear in the project’s Activity, with the end reason and exit code.
- Containers in the same Instance share a trust domain. Two shell sessions into the same Instance can see each other’s processes and environment variables, because they run in the same container. Treat every shell into an Instance as having the same level of access as any other shell into it.
- Ending a session stops what it started, with one exception. A process that detaches itself from the session, for example with
setsid, can keep running after the session ends. A background job that was killed can also stay behind as a defunct process in a container whose main process doesn’t reap its children. This is a known limitation.
Permissions
Creating a shell session requires the Compute Admin role, which includescompute.datumapis.com/instanceconsolesessions.create. The Compute Viewer role can list and inspect sessions, including who opened one and how it ended, but can’t open or close one. For more on assigning roles, see Assign roles.
Limits
Why a session ended
The Shell tab anddatumctl compute exec both report why a session ended. The following table lists every reason:
If your project’s shell session limit is
0, the Shell tab and datumctl compute exec both report that shell sessions aren’t enabled for the project. Request an increase from support@datum.net.