Kubernetes CRD Integration Plugin

Relevant source files

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

• plugin/kubernetes/kubernetes.go
• plugin/kubernetes/crd.yaml
• plugin/kubernetes/main.go
• plugin/kubernetes/README.md
• README.md
• libplugin/plugin.proto

Introduction

The Kubernetes plugin for sshpiperd provides native integration with Kubernetes through a Custom Resource Definition (CRD). It allows administrators to manage SSH routing rules, known as "Pipes," using standard Kubernetes tools like kubectl. By defining Pipe resources, users can route downstream SSH connections to specific upstream targets within or outside the cluster.

This plugin enables advanced features such as kubectl exec bridge mode, which allows SSH access to pods that do not have an SSH daemon installed. It acts as a bridge between traditional SSH protocols and the Kubernetes API, leveraging Kubernetes secrets for private key and password management.

Sources: plugin/kubernetes/README.md:1-15, plugin/kubernetes/main.go:12-15

Architecture and Components

The plugin operates as a gRPC service that communicates with the Kubernetes API server to watch for Pipe resources. It uses a PipeLister and a Reflector to maintain an indexed local cache of these resources for high-performance lookups during the SSH authentication phase.

Plugin Component Diagram

The following diagram illustrates the relationship between sshpiperd, the Kubernetes plugin, and the Kubernetes API.

Data Structures

The core of the integration is the plugin struct, which maintains the Kubernetes client and the cache lister.

Field	Type	Description
k8sclient	corev1.CoreV1Interface	Client for interacting with standard K8s resources (Secrets, Pods).
lister	piperlister.PipeLister	Cached lister for Pipe CRD resources.
kubeCfg	*rest.Config	REST configuration for the Kubernetes client.
kubeExecTargets	map[string]kubectlExecTarget	Internal map for tracking kubectl exec bridge sessions.

Sources: plugin/kubernetes/kubernetes.go:19-32

Custom Resource Definition (CRD)

The plugin requires the application of a CRD defining the pipes.sshpiper.com resource. A Pipe consists of a from section (matching downstream criteria) and a to section (defining the upstream destination).

Pipe Resource Schema

Section	Field	Type	Description
from	username	String	Downstream username to match.
from	username_regex_match	Boolean	If true, username is treated as a regular expression.
from	authorized_keys_secret	Object	Reference to a Secret containing public keys.
to	host	String	Target address (e.g., host:port).
to	username	String	Target username to use on the upstream.
to	private_key_secret	Object	Reference to a Secret containing the upstream private key.
to	ignore_hostkey	Boolean	Whether to skip upstream host key verification.

Sources: plugin/kubernetes/crd.yaml:26-97, plugin/kubernetes/README.md:126-155

Authentication Flow

When a connection arrives, the plugin matches the downstream metadata against the cached Pipe resources.

Kubectl Exec Bridge Mode

One unique feature is the ability to bridge SSH connections to kubectl exec commands. This is enabled via annotations on the Pipe resource.

• sshpiper.com/kubectl_exec_cmd: Enables bridge mode.
• Upstream Interpretation: When enabled, spec.to.host is interpreted as pod, pod/container, or namespace/pod/container instead of a network address.
• RBAC Requirements: The service account running sshpiperd must have get permissions on pods and create permissions on pods/exec.

Sources: plugin/kubernetes/README.md:29-45

Configuration and Usage

The plugin is configured via command-line flags or environment variables.

Flag	Environment Variable	Default	Description
--all-namespaces	SSHPIPERD_KUBERNETES_ALL_NAMESPACES	false	Watch for Pipes across all namespaces.
--kubeconfig	KUBECONFIG	System default	Path to the kubeconfig file.

Configuration Snippet

libplugin.CreateAndRunPluginTemplate(&libplugin.PluginTemplate{
    Name:  "kubernetes",
    Flags: []cli.Flag{
        &cli.BoolFlag{
            Name:     "all-namespaces",
            EnvVars:  []string{"SSHPIPERD_KUBERNETES_ALL_NAMESPACES"},
        },
        &cli.StringFlag{
            Name:     "kubeconfig",
            EnvVars:  []string{"SSHPIPERD_KUBERNETES_KUBECONFIG", "KUBECONFIG"},
        },
    },
    // ... factory logic
})

Sources: plugin/kubernetes/main.go:12-30

Summary

The Kubernetes CRD Integration Plugin transforms sshpiperd into a Kubernetes-native SSH gateway. By leveraging Custom Resources and the Kubernetes API, it provides a declarative way to manage SSH routing and allows for modern operations like bridging SSH to kubectl exec sessions. It ensures security by integrating directly with Kubernetes Secrets for sensitive credential management.

Sources: plugin/kubernetes/README.md:1-10, plugin/kubernetes/kubernetes.go:40-87