Docker SFTP/SSH Gateway for Kubernetes

Secure SSH/SFTP access to Kubernetes workloads, authenticated with GitHub SSH keys and repository permissions. It proxies approved sessions into running pods; it is not a standalone file server.

Quick Start · Configuration · Documentation · Development

Overview

The gateway:

• authenticates users with their GitHub public SSH keys
• checks repository access before allowing a connection
• proxies SSH sessions to selected workloads with kubectl exec
• supports SFTP when the target workload supports it
• can record gateway state through Firebase

Published images are available at usabilitydynamics/docker-sftp. Use a semantic version tag such as 0.14.1 for deployments; latest follows the most recent release. Release images support linux/amd64 and linux/arm64.

Quick Start

Prerequisites

• Docker for local image execution
• Kubernetes access appropriate for the target workload
• GitHub token with access to the repositories the gateway evaluates
• SSH key registered with the GitHub account that will connect

Run Locally

Export secrets and cluster values in your shell, then pass only their names to Docker:

docker run -d \
  --name sftp-gateway \
  -p 2222:22 \
  --env ACCESS_TOKEN \
  --env KUBERNETES_CLUSTER_ENDPOINT \
  --env KUBERNETES_CLUSTER_USER_TOKEN \
  usabilitydynamics/docker-sftp:0.14.1

Connect to a Workload

# Interactive shell
ssh -p 2222 namespace.pod-name@YOUR_GATEWAY_ADDRESS

# Upload a file
scp -P 2222 local-file namespace.pod-name@YOUR_GATEWAY_ADDRESS:/remote/path/

The authenticated GitHub user must have a permitted repository role. See the Client Guide for SSH configuration, namespaces, and advanced usage.

Configuration

The image includes safe Worker defaults. Deployments normally provide only the cluster-specific values and secrets:

Variable	Required	Purpose
ACCESS_TOKEN	Yes	GitHub token used for repository access checks.
KUBERNETES_CLUSTER_ENDPOINT	Yes	Kubernetes API endpoint.
KUBERNETES_CLUSTER_USER_TOKEN	Yes	Service-account token with workload access.
ALLOW_SSH_ACCESS_ROLES	No	Permitted GitHub roles; defaults to admin,maintain,write.

Use Docker secrets, Kubernetes Secrets, or the deployment system for sensitive values. Do not commit rendered credentials or pass them in image layers. See Runtime Configuration for the complete reference and Deployment Guide for Kubernetes manifests.

Documentation

• Deployment Guide — deploy and verify the gateway
• Runtime Configuration — service settings and secrets
• Client Guide — SSH and SFTP connections
• Troubleshooting — connection and service diagnosis
• Architecture — components and data flow
• User Management — GitHub access control
• API Reference — internal HTTP endpoints

Rabbit CI release behavior and Docker Hub configuration live in .rabbit/README.md.

Development

Local tooling requires Node.js 22.12 or newer, npm, and Docker.

npm ci
npm test
make build

For pull requests, update the relevant docs or runtime behavior, run the smallest applicable checks, and let the image workflow build and scan the change.

Contributing and Security

• Bugs and feature requests: GitHub Issues
• Security reports: security@udx.io
• Contributions: fork the repository and open a pull request