Skip to content

Commit bab45b5

Browse files
committed
Configure native SSH and SCP with sandbox ssh-setup
1 parent c2d75cd commit bab45b5

13 files changed

Lines changed: 390 additions & 3 deletions

File tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* Add `databricks sandbox ssh-setup` to configure native SSH and SCP through sandbox port forwarding. ([#7590](https://github.com/databricks/cli/pull/7590))
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Cloud = false
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
2+
>>> [CLI] sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir ./releases
3+
Created SSH configuration at [TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/my-sandbox. Connect with 'ssh my-sandbox' or 'scp ./file my-sandbox:/tmp/file'.
4+
5+
>>> [CLI] sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir ./releases
6+
Created SSH configuration at [TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/my-sandbox. Connect with 'ssh my-sandbox' or 'scp ./file my-sandbox:/tmp/file'.
7+
8+
>>> cat [TEST_TMP_DIR]/.ssh/config
9+
Include "[TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/*"
10+
11+
>>> cat [TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/my-sandbox
12+
13+
Host my-sandbox
14+
User sandbox-agent
15+
ConnectTimeout 900
16+
ServerAliveInterval 30
17+
StrictHostKeyChecking yes
18+
UserKnownHostsFile "[TEST_TMP_DIR]/.databricks/ssh-tunnel-known-hosts/[SSH_IDENTITY]"
19+
HostKeyAlias [SSH_IDENTITY]
20+
IdentitiesOnly yes
21+
IdentityFile "[TEST_TMP_DIR]/.databricks/ssh-tunnel-keys/[SSH_IDENTITY]/id_ed25519"
22+
ProxyCommand [CLI] sandbox ssh sandboxes/test --proxy --profile sandbox-test --releases-dir [TEST_TMP_DIR]/releases --ssh-identity [SSH_IDENTITY] --ssh-config-file [TEST_TMP_DIR]/databrickscfg
23+
24+
>>> musterr [CLI] sandbox ssh-setup test --name ../escape
25+
Error: SSH host alias must contain only letters, numbers, dots, underscores or hyphens
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
export DATABRICKS_CONFIG_FILE="$TEST_TMP_DIR/databrickscfg"
2+
printf '[sandbox-test]\nhost = %s\ntoken = %s\n' "$DATABRICKS_HOST" "$DATABRICKS_TOKEN" > "$DATABRICKS_CONFIG_FILE"
3+
cd "$TEST_TMP_DIR"
4+
trace $CLI sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir ./releases
5+
trace $CLI sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir ./releases
6+
trace cat "$TEST_TMP_DIR/.ssh/config"
7+
trace cat "$TEST_TMP_DIR/.databricks/ssh-tunnel-configs/my-sandbox"
8+
trace musterr $CLI sandbox ssh-setup test --name ../escape
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Ignore = ["databrickscfg"]
2+
3+
[[Repls]]
4+
Old = 'sandbox-[0-9a-f]{64}'
5+
New = '[SSH_IDENTITY]'
6+
7+
[[Server]]
8+
Pattern = "GET /api/2.0/sandboxes/test"
9+
Response.Body = '''{"name":"sandboxes/test","status":{"state":"SANDBOX_STATE_STOPPED"}}'''

‎cmd/cmd.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,8 @@ func sandboxSpec() root.CommandSpec {
9696
spec := sandbox.Spec
9797
spec.Build = func(ctx context.Context, cmd *cobra.Command) {
9898
sandbox.Spec.Build(ctx, cmd)
99-
cmd.AddCommand(sandboxssh.NewServerCommand(), sandboxssh.NewSSHCommand(sandboxssh.CommandDependencies{ResolveName: sandbox.ResolveSSHName, Complete: sandbox.CompleteSandboxIDs}))
99+
deps := sandboxssh.CommandDependencies{ResolveName: sandbox.ResolveSSHName, Complete: sandbox.CompleteSandboxIDs}
100+
cmd.AddCommand(sandboxssh.NewServerCommand(), sandboxssh.NewSSHCommand(deps), sandboxssh.NewSSHSetupCommand(deps))
100101
}
101102
return spec
102103
}

‎cmd/sandbox/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# SSH through sandbox port forwarding
2+
3+
Run `databricks sandbox ssh SANDBOX_ID` for an interactive shell, or pass a
4+
remote command after `--`. This creates a reusable local SSH key automatically
5+
and connects through workspace-authenticated WebSocket port forwarding.
6+
It does not write a persistent SSH Host entry.
7+
8+
For native SSH tools, configure a local alias once:
9+
10+
```sh
11+
databricks sandbox ssh-setup SANDBOX_ID --name my-sandbox --profile my-workspace
12+
ssh my-sandbox
13+
scp ./example.txt my-sandbox:/tmp/example.txt
14+
sftp my-sandbox
15+
```
16+
17+
Keep the Databricks CLI installed at the path recorded in the generated
18+
`ProxyCommand`, with the saved Databricks profile and its credentials available.
19+
Setup requires a named profile; environment-only credentials do not create a
20+
persistent workspace selection. The proxy prepares the
21+
sandbox and connects through port forwarding for each SSH connection. Run setup
22+
again after relocating the executable or changing the selected workspace.
23+
24+
The local machine needs OpenSSH. The sandbox needs Python 3, `ssh-keygen`, and
25+
`openssh-server`, with the unprivileged `sandbox-agent` account configured to
26+
accept public-key authentication. The CLI caches a compatible Linux executable in the sandbox and invokes its server
27+
automatically; no relay needs to be included in the image.
28+
For development builds on macOS or Windows, provide `--releases-dir` containing
29+
Linux release archives built from the same checkout.
30+
31+
The private client key remains on the local machine. Public-key entries expire
32+
after 24 hours and are renewed during connection setup. The sandbox's persistent
33+
HOME stores its server key and public-key entries, allowing reuse after restart.
34+
Each proxy invocation starts and cleans up its own remote server command. The server waits up to two minutes for its first connection and exits when its
35+
SSH session ends. The CLI renews the WebSocket and command-output stream every
36+
25 minutes before their route lifetime limits. A broken forwarding connection
37+
ends the SSH session; reconnect to start another one. Setup prunes session
38+
directories older than a day while preserving directories leased by active servers.
39+
The CLI allows up to ten minutes to prepare the remote server, including sandbox
40+
startup and executable upload. The SSH handshake allows fifteen minutes overall,
41+
including workspace authentication. Neither timeout limits an established session.
42+
43+
These commands require workspace support for sandbox HTTP/WebSocket port
44+
forwarding. They do not connect to the legacy Gateway SSH endpoint or register
45+
keys with its registry.

‎experimental/ssh/internal/sshconfig/sshconfig.go‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,19 +220,24 @@ func PromptRecreateConfig(ctx context.Context, hostName string) (bool, error) {
220220
// `ssh setup --name <alias> --cluster <id>`: without it ssh would look the key up under the
221221
// alias, find no matching entry, and fail strict host key checking (DECO-27882).
222222
func GenerateHostConfig(hostName, userName, identityFile, knownHostsFile, hostKeyAlias, proxyCommand string) string {
223+
return GenerateHostConfigWithTimeout(hostName, userName, identityFile, knownHostsFile, hostKeyAlias, proxyCommand, 360)
224+
}
225+
226+
// GenerateHostConfigWithTimeout supports proxies that enforce their own startup timeout.
227+
func GenerateHostConfigWithTimeout(hostName, userName, identityFile, knownHostsFile, hostKeyAlias, proxyCommand string, connectTimeoutSeconds int) string {
223228
hostKeyAliasLine := ""
224229
if hostKeyAlias != "" {
225230
hostKeyAliasLine = fmt.Sprintf(" HostKeyAlias %s\n", hostKeyAlias)
226231
}
227232
return fmt.Sprintf(`
228233
Host %s
229234
User %s
230-
ConnectTimeout 360
235+
ConnectTimeout %d
231236
ServerAliveInterval %d
232237
StrictHostKeyChecking yes
233238
UserKnownHostsFile %q
234239
%s IdentitiesOnly yes
235240
IdentityFile %q
236241
ProxyCommand %s
237-
`, hostName, userName, ServerAliveIntervalSeconds, knownHostsFile, hostKeyAliasLine, identityFile, proxyCommand)
242+
`, hostName, userName, connectTimeoutSeconds, ServerAliveIntervalSeconds, knownHostsFile, hostKeyAliasLine, identityFile, proxyCommand)
238243
}

‎experimental/ssh/internal/sshconfig/sshconfig_test.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ func TestGenerateHostConfigSetsServerAliveInterval(t *testing.T) {
1717
// `ssh setup` and `--ide` reach ssh through this block and nothing else, so the option has to
1818
// be in it.
1919
assert.Contains(t, config, fmt.Sprintf("\n ServerAliveInterval %d\n", ServerAliveIntervalSeconds))
20+
assert.Contains(t, config, "\n ConnectTimeout 360\n")
2021

2122
// The interval has to fire well inside the ~8 minute reap window, and ServerAliveCountMax
2223
// (OpenSSH default 3) intervals have to outlast the longest legitimate pause on a healthy
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
package sandbox
2+
3+
import (
4+
"errors"
5+
"fmt"
6+
"os"
7+
"path/filepath"
8+
"strings"
9+
10+
"github.com/databricks/cli/cmd/root"
11+
"github.com/databricks/cli/libs/cmdctx"
12+
"github.com/databricks/cli/libs/cmdio"
13+
"github.com/databricks/databricks-sdk-go/config"
14+
"github.com/spf13/cobra"
15+
)
16+
17+
// NewSSHSetupCommand configures native SSH tools to use sandbox forwarding.
18+
func NewSSHSetupCommand(deps CommandDependencies) *cobra.Command {
19+
var alias, sshConfig, releasesDir string
20+
var overwrite bool
21+
cmd := &cobra.Command{
22+
Use: "ssh-setup [sandbox-id]", Short: "Configure native SSH tools for a sandbox",
23+
Long: `Create a local SSH Host entry for native ssh, scp, sftp, and tools that use SSH.
24+
25+
The CLI creates or reuses a local key. On each connection, the generated
26+
ProxyCommand prepares the sandbox and opens authenticated WebSocket port forwarding.
27+
Pass --profile with a named Databricks profile so later connections select the same workspace.
28+
Databricks CLI and that profile's credentials must remain available locally.
29+
30+
Examples:
31+
databricks sandbox ssh-setup happy-panda-1234 --name my-sandbox --profile my-workspace
32+
ssh my-sandbox
33+
scp ./example.txt my-sandbox:/tmp/example.txt
34+
35+
Interactive 'databricks sandbox ssh' works without this setup step.`,
36+
Args: cobra.MaximumNArgs(1),
37+
PreRunE: func(cmd *cobra.Command, args []string) error {
38+
cmd.SetContext(root.SkipLoadBundle(cmd.Context()))
39+
return root.MustWorkspaceClient(cmd, args)
40+
},
41+
ValidArgsFunction: deps.Complete,
42+
RunE: func(cmd *cobra.Command, args []string) error {
43+
if err := ValidateHostAlias(alias); err != nil {
44+
return err
45+
}
46+
ctx := cmd.Context()
47+
profileFlag := cmd.Flag("profile")
48+
if profileFlag == nil || !profileFlag.Changed || profileFlag.Value.String() == "" {
49+
return errors.New("ssh-setup requires a named Databricks profile; run 'databricks auth login --profile NAME' and rerun with --profile NAME")
50+
}
51+
w := cmdctx.WorkspaceClient(ctx)
52+
requested := ""
53+
if len(args) == 1 {
54+
requested = args[0]
55+
}
56+
name, err := deps.ResolveName(ctx, w, requested)
57+
if err != nil {
58+
return err
59+
}
60+
identity, err := prepareSSHIdentity(ctx, w, name)
61+
if err != nil {
62+
return err
63+
}
64+
executable, err := os.Executable()
65+
if err != nil {
66+
return err
67+
}
68+
options := sshProxyOptions{Profile: w.Config.Profile, ReleasesDir: releasesDir, IdentityScope: identity.HostKeyAlias}
69+
if releasesDir != "" {
70+
options.ReleasesDir, err = filepath.Abs(releasesDir)
71+
if err != nil {
72+
return fmt.Errorf("resolve SSH releases directory: %w", err)
73+
}
74+
options.ReleasesDir = filepath.ToSlash(options.ReleasesDir)
75+
}
76+
if w.Config.ConfigFile != "" {
77+
file, err := config.LoadFile(w.Config.ConfigFile)
78+
if err != nil {
79+
return fmt.Errorf("load SSH profile configuration: %w", err)
80+
}
81+
options.ConfigFile, err = filepath.Abs(file.Path())
82+
if err != nil {
83+
return fmt.Errorf("resolve SSH profile configuration path: %w", err)
84+
}
85+
options.ConfigFile = filepath.ToSlash(options.ConfigFile)
86+
}
87+
proxy, err := sshProxyCommand(executable, name, options)
88+
if err != nil {
89+
return err
90+
}
91+
location, err := WriteHostConfig(ctx, alias, sshConfig, proxy, identity, overwrite)
92+
if err != nil {
93+
return err
94+
}
95+
cmdio.LogString(ctx, fmt.Sprintf("Created SSH configuration at %s. Connect with 'ssh %s' or 'scp ./file %s:/tmp/file'.", strings.ReplaceAll(location, `\`, "/"), alias, alias))
96+
return nil
97+
},
98+
}
99+
cmd.Flags().StringVar(&alias, "name", "", "Local SSH host alias")
100+
cmd.MarkFlagRequired("name")
101+
cmd.Flags().StringVar(&sshConfig, "ssh-config", "", "Path to SSH config file (default ~/.ssh/config)")
102+
cmd.Flags().StringVar(&releasesDir, "releases-dir", "", "Directory containing version-matched Linux CLI archives")
103+
cmd.Flags().BoolVar(&overwrite, "overwrite", false, "Replace an existing managed SSH host entry")
104+
return cmd
105+
}

0 commit comments

Comments
 (0)