Installation

StandaloneDockerKubernetes

ContainerSSH can be deployed outside of a container. On our downloads page we provide binaries for Linux, Windows, and MacOS. We also provide DEB, RPM and APK (Alpine Linux) packages.

Before running ContainerSSH you will need to create a config.yaml file that tells ContainerSSH where to find the SSH host key and the authentication server. The minimum configuration file looks like this:

ssh:
  hostkeys:
    - /path/to/your/host.key
auth:
  password:
    method: webhook
    webhook:
      url: http://your-auth-server/

Tip

You can generate a new host key using openssl genrsa. Please don't use ssh-keygen as it regenerates OpenSSH-specific keys.

Tip

Details about the authentication server are described in the Authentication section.

ContainerSSH can then be started by running ./containerssh --config /path/to/your/config.yaml

When deploying in Docker you must first prepare a configuration file that tells ContainerSSH where to find the SSH host key and the authentication server. The minimum configuration file looks like this:

ssh:
  hostkeys:
    - /var/run/secrets/host.key
auth:
  password:
    method: webhook
    webhook:
      url: http://your-auth-server/

Tip

You can generate a new host key using openssl genrsa

Tip

Details about the authentication server are described in the Authentication section.

You can then run ContainerSSH with the following command line:

docker run -d \
  -v /srv/containerssh/config.yaml:/etc/containerssh/config.yaml \
  -v /srv/containerssh/host.key:/var/run/secrets/host.key \
  -p 2222:2222 \
  containerssh/containerssh:0.4

When running ContainerSSH inside a Kubernetes cluster you must furst create a Secret that contains the host key.

openssl genrsa | kubectl create secret generic containerssh-hostkey --from-file=host.key=/dev/stdin

Next, you can create a ConfigMap to hold the ContainerSSH configuration:

( cat << EOF 
ssh:
  hostkeys:
    - /etc/containerssh/host.key
auth:
  password:
    method: webhook
    webhook:
      url: http://your-auth-server/
EOF
) | kubectl create configmap containerssh-config --from-file=config.yaml=/dev/stdin

Tip

Details about the authentication server are described in the Authentication section.

Then you can create a deployment to run ContainerSSH:

( cat << EOF 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: containerssh
  labels:
    app: containerssh
spec:
  replicas: 1
  selector:
    matchLabels:
      app: containerssh
  template:
    metadata:
      labels:
        app: containerssh
    spec:
      containers:
      - name: containerssh
        image: containerssh/containerssh:0.4
        ports:
        - containerPort: 2222
        volumeMounts:
        - name: hostkey
          mountPath: /etc/containerssh/host.key
          subPath: host.key
          readOnly: true
        - name: config
          mountPath: /etc/containerssh/config.yaml
          subPath: config.yaml
          readOnly: true
      volumes:
      - name: hostkey
        secret:
          secretName: containerssh-hostkey
      - name: config
        configMap:
          name: containerssh-config
EOF
) | kubectl apply -f -

Finally, you can create a service to expose the SSH port. You can customize this to create a loadbalancer or nodeport to make SSH publicly available. See kubectl expose --help for details.

kubectl expose deployment containerssh \
    --port=2222 --target-port=2222 \
    --name=containerssh

Note

This still does not configure ContainerSSH to use Kubernetes as a container backend. This is described in detail in the Kubernetes backend section.