Step SSH Kubernetes Integration

This project provides a Kubernetes integration for Step SSH, allowing you to run an SSH server in your Kubernetes cluster with automatic certificate management. When the pod comes online it will register the host on your Smallstep account and when the pod shuts down it will unregister.

Note: This is a proof of concept implementation and will likely need to be adjusted to fit your specific Kubernetes deployment requirements. You may need to modify aspects such as networking, security policies, resource limits, or other configurations based on your cluster's setup and security requirements.

Prerequisites

• Docker
• Kubernetes cluster
• Smallstep account with access to the web interface
• Access to a container registry

Building the Containers

The project consists of two containers:

1. A Fedora-based container running the SSH server
2. A minimal container with just the Step SSH Kube binary

Build Commands

Replace your-registry.example.com with your container registry:

# Build the Fedora-based SSH server container
docker build -t your-registry.example.com/step-ssh-kube:fedora .

# Build the minimal binary container
docker build -f Dockerfile.binary -t your-registry.example.com/step-ssh-kube:binary .

# Push both containers to your registry
docker push your-registry.example.com/step-ssh-kube:fedora
docker push your-registry.example.com/step-ssh-kube:binary

Deployment

1. Get your Step SSH token:

   • Visit https://smallstep.com/app/myteam/ssh/hosts
   • Replace 'myteam' with your team name if different
   • Copy your token
   • Generate the base64-encoded token string:

     echo -n "your-token-here" | base64 -w0

2. Update the deployment.yaml file:

   • Replace the container image references with your registry
   • Update the SSH_PUBLIC_KEY_URL to point to your GitHub keys or other public key source
   • Adjust the STEP_SSH_TEAM and STEP_SSH_TAGS as needed
   • In the Secret section at the top of the file, replace the placeholder token:

     apiVersion: v1
     kind: Secret
     metadata:
       name: step-ssh-token
     type: Opaque
     data:
       token.txt: <base64-encoded-token>  # Replace with your base64 encoded token

3. Deploy to your Kubernetes cluster:

kubectl apply -f deployment.yaml

4. Verify the deployment:

kubectl get pods
kubectl get service step-ssh-kube

Verifying and Connecting

After deployment, you can verify that the host is registered with Step SSH and connect to it:

1. List registered hosts:

step ssh hosts

You should see your pod listed with its hostname and tags.

2. Get the service's cluster IP:

kubectl get service step-ssh-kube -o jsonpath='{.spec.clusterIP}'

3. Connect to the pod using the cluster IP:

ssh <your-username>@<cluster-ip> -p 8822

The first time you connect, you'll be prompted to verify the host's fingerprint. After accepting, you'll be logged into the pod.

4. Verify root access:

sudo su -
whoami  # Should show 'root'

Configuration

The deployment uses the following environment variables:

• SSH_PUBLIC_KEY_URL: URL to fetch authorized SSH public keys from a GitHub user. Leave unset if you don't want to have your SSH keys added to the default step user.
• STEP_SSH_TEAM: Step SSH team name (e.g., 'myteam')
• STEP_SSH_TAGS: Tags for the SSH server. Tags are space-separated key-value pairs. Examples:

  "env=prod region=us-west-1"
  "foo=bar bax=fax mop.top=cat-bat"
  

• STEP_SSH_TOKEN_FILE: Path to the Step SSH token file. This shouldn't be set unless you want to change the file path.

Architecture

The deployment consists of:

• A main container running the SSH server
• A sidecar container running the Step SSH Kube binary
• Shared volumes for SSH keys and configuration
• A NodePort service exposing port 8022

Security Notes

• The SSH server runs on port 8022
• SSH host keys are generated during pod initialization
• The Step SSH token is stored as a Kubernetes secret
• All SSH keys are mounted with appropriate permissions (0600)