Kubernetes Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• plugin/kubernetes/main.go
• plugin/kubernetes/README.md
• plugin/kubernetes/kubernetes.go
• plugin/kubernetes/crd.yaml
• plugin/kubernetes/kubectl_exec_bridge.go
• e2e/kubernetes_test.go

The Kubernetes integration for sshpiperd allows for native management of SSH proxying through Kubernetes Custom Resource Definitions (CRDs). By utilizing the Pipe resource, administrators can define routing rules, authentication mappings, and upstream targets directly via kubectl. This integration transforms sshpiperd into a Kubernetes-native ingress-like controller for SSH traffic.

This system supports both traditional SSH proxying to remote hosts and a specialized "kubectl exec bridge" mode. The latter allows sshpiperd to pipe SSH sessions into Kubernetes pods that do not have an SSH daemon (sshd) installed, using the standard Kubernetes API for pod execution.

Sources: plugin/kubernetes/README.md:1-10, plugin/kubernetes/crd.yaml

Custom Resource Definition (CRD)

The core of the Kubernetes deployment is the Pipe custom resource, defined under the API group sshpiper.com/v1beta1. A Pipe object specifies how a downstream connection (from the user) is mapped to an upstream connection (the target).

Pipe Specification Structure

A Pipe resource consists of two primary sections: from and to.

• from: Defines the matching criteria for downstream users, including supported authentication methods like public keys or passwords.
• to: Defines the target host, port, and the authentication credentials sshpiperd should use to connect to that target.

Field	Type	Description
from.username	string	The username provided by the downstream client. Supports regex if username_regex_match is true.
from.authorized_keys_data	string	Inline base64 encoded authorized keys for public key auth.
from.authorized_keys_secret	object	Reference to a Kubernetes Secret containing authorized keys.
to.host	string	Target address. In kubectl-exec mode, follows namespace/pod/container format.
to.private_key_secret	object	Secret reference for the private key used to authenticate with the upstream.
to.ignore_hostkey	boolean	If true, sshpiperd will not verify the upstream host key.

Sources: plugin/kubernetes/crd.yaml:15-100, plugin/kubernetes/README.md:135-165

Plugin Architecture and Logic

The Kubernetes plugin operates by watching the Kubernetes API for Pipe resources and maintaining an internal state of routing rules.

The diagram above illustrates the data flow from the Kubernetes API server through the plugin's internal lister to the actual SSH session proxying logic.

Key Components

• Reflector & Lister: The plugin uses standard Kubernetes cache.NewReflector and PipeLister to maintain a local, high-performance cache of Pipe resources, reducing load on the API server.
• Client Setup: The plugin initializes using either an in-cluster configuration or a provided kubeconfig file.
• Namespace Scoping: It can be configured to watch all namespaces or be restricted to the namespace where it is deployed.

Sources: plugin/kubernetes/kubernetes.go:26-87, plugin/kubernetes/main.go:12-30

Kubectl Exec Bridge Mode

A unique feature of the Kubernetes deployment is the kubectl exec bridge. This allows users to SSH into a pod even if that pod does not have an SSH server.

Mechanism

When the annotation sshpiper.com/kubectl_exec_cmd: "true" is present on a Pipe, the plugin activates bridge mode. It dynamically generates an internal SSH server (bridge) and uses the Kubernetes pods/exec API to tunnel the SSH session into the container's shell (typically /bin/sh).

The sequence diagram shows how the plugin intercepts the request and bridges it to the Kubernetes execution API.

RBAC Requirements

For this mode to function, the sshpiperd service account must have specific permissions:

• Pods: get permissions to locate the target.
• Pods/exec: create permissions to initiate the execution session.

Sources: plugin/kubernetes/kubectl_exec_bridge.go:37-65, plugin/kubernetes/README.md:40-65

Configuration and Flags

The Kubernetes plugin is initialized via sshpiperd and accepts several command-line flags and environment variables for configuration.

Flag	Environment Variable	Description
--all-namespaces	SSHPIPERD_KUBERNETES_ALL_NAMESPACES	Watch for Pipe resources across the entire cluster.
--kubeconfig	KUBECONFIG	Path to the configuration file for the Kubernetes client.

Sources: plugin/kubernetes/main.go:13-26, plugin/kubernetes/README.md:14-20

Deployment in Kubernetes

A typical deployment involves a Deployment for the sshpiperd binary, a Service to expose port 2222 (default), and a ServiceAccount with a Role providing access to Pipes, Secrets, and Pods.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sshpiper-deployment
spec:
  template:
    spec:
      serviceAccountName: sshpiper-account
      containers:
      - name: sshpiper
        image: farmer1992/sshpiperd:latest
        env:
        - name: PLUGIN
          value: "kubernetes"

Sources: plugin/kubernetes/README.md:85-110

Summary

The Kubernetes deployment provides a powerful, declarative way to manage SSH access. By leveraging CRDs, it integrates seamlessly into the Kubernetes ecosystem, allowing DevOps teams to manage SSH routing as code. The inclusion of the kubectl exec bridge further extends its utility, enabling secure shell access to ephemeral containers without the overhead of managing SSH daemons within every pod.

Sources: plugin/kubernetes/README.md, plugin/kubernetes/kubernetes.go