Controller Security

A controller runs in the customer’s environment and manages the deployments of one deployment target. This page explains why you can run it there without opening the environment up, and which of its settings you control.

The Docker controller and the Kubernetes controller are open source under the Apache 2.0 license. Their code is in the Distr repository on GitHub, in cmd/controller/docker and cmd/controller/kubernetes. The autoheal service, in docker-autoheal, is an MIT-licensed adaptation of willfarrell/docker-autoheal. You can read all of it before you install a controller.

Public GitHub Actions workflows build the images from that code. Every released image comes with an SBOM and build provenance and is signed with cosign, so you can check that the image you pull was built by that workflow. The commands are on the Images page.

Please report a vulnerability privately through GitHub’s vulnerability reporting rather than in a public issue. Fixed vulnerabilities are announced as security advisories in the same repository, which you can watch to be notified.

The controller connects to Distr. Distr never connects to the controller. Every few seconds the controller fetches its deployments over HTTPS and reports back over the same connection. The environment needs outbound access to Distr and the registries but no firewall rule for incoming traffic.

The controller opens no port that is reachable from outside. Distr cannot open a connection into the environment or run a command there. It can only change what the controller fetches next. Network & Authentication lists every connection and the local health check.

Distr Secrets are encrypted at rest, but the controller still receives their values from Distr. A password, an API key or a certificate that should never leave the customer environment can be created there instead, as a Kubernetes Secret or a file on the Docker host. The deployment then refers to it by name, and Distr only ever sees that name. External Secrets shows how for each deployment type.

Log collection, metrics, automatic controller and application updates, image cleanup, autoheal and the scope of a Kubernetes controller are settings you control, most of them per deployment target. The Configuration Reference lists each of them with its default.

• Docker Controller covers the mounts, the Docker commands and the credentials on a Docker host.
• Kubernetes Controller covers the RBAC of both scopes and the resources, operations and credentials in a cluster.
• Network & Authentication lists the connections a controller opens and explains how it logs in to Distr.
• Data Sent to Distr lists the logs, status and metrics a controller reports.
• External Secrets shows how to reference secrets that are created in the customer environment.
• Images describes what the controller images contain and how to verify their signatures.
• Configuration Reference lists the settings of a controller with their defaults.