Declarative Tunnels
Manage tunnels from desired state instead of imperative commands.
Declarative tunnels allow tunnel configuration to be described as desired state. Instead of running rstream forward for each tunnel, a single long-running agent reconciles the desired configuration and keeps tunnels in sync with it.
Declarative tunnels are available in three forms: rstream run --apply for explicit YAML files, rstream run --docker for Docker label discovery, and the Kubernetes operator for clusters that should expose Services through custom resources.
This mode is the right fit when tunnels are part of an application deployment rather than an operator's interactive shell. It keeps tunnel configuration close to the application, supports reconnect and reconciliation, and marks managed tunnels with labels so they can be distinguished from manually created tunnels.
Apply mode, Docker mode, and Kubernetes
In apply mode, rstream run --apply <path> reads a YAML configuration file, validates it strictly, and reconciles tunnels to match it. This is useful for servers, CI deployments, and environments where tunnel definitions are stored next to application configuration.
In Docker mode, rstream run --docker listens to Docker events and reads labels on running containers to derive tunnels. This is useful when containers already declare their own exposure model and a single rstream agent should publish them.
In Kubernetes mode, rstream-operator watches RstreamConnection and RstreamTunnel custom resources. It resolves the project engine, creates a per-tunnel agent Deployment, and writes readiness, hostname, and forwarding address back to Kubernetes status.
All modes support reconciliation. Changes to a YAML file, Docker labels, or Kubernetes resources trigger updates without replacing the whole operational model.
Related pages
YAML documents the configuration file format. Docker Labels documents the label schema and provides compose examples. Kubernetes Operator covers the custom resource model, and Expose a k3s Service with the rstream Kubernetes Operator walks through a complete first cluster setup. CLI Workflow covers the context and environment resolution model used by rstream run.