Building a Custom Edge Image

Some integrations, such as MySQL, PostgreSQL and MongoDB, rely on tools provided by the vendor. These tools must be available on the edge that runs the task, as described in Integrations that need external tools. The official edge image does not include them.

A custom image bundles those tools with plakar-edge. Start from a base image that provides the tools, then copy the plakar-edge binary from the official image. The resulting image can be pushed to a container registry and run anywhere containers run, including on Kubernetes with the Helm chart.

Base image requirements

The base image must provide:

  • glibc 2.34 or later. The plakar-edge binary and the integrations it installs are built against glibc. Images based on Ubuntu 22.04 or later, Debian bookworm or later, and the official mysql image meet this requirement. Alpine images, including the -alpine variants of vendor images, do not.
  • CA certificates, so that the edge can connect to the Control Plane over HTTPS.
  • The OpenSSH client (ssh, ssh-add and ssh-agent), if the edge runs SFTP or Windows VSS tasks, or tasks of the integrations built on VSS. See SSH client.

The tools must also be compatible with the server they connect to. For example, pg_dump must be at least the same major version as the PostgreSQL server it backs up. Each integration lists the tools it needs on its resource page.

Starting from a vendor image

The simplest custom image starts from the vendor’s own image, which already contains the tools. The official mysql image includes mysql, mysqldump and CA certificates:

FROM mysql:8.4
COPY --from=ghcr.io/plakarkorp/plakar-edge:<version> /bin/plakar-edge /bin/
ENTRYPOINT ["/bin/plakar-edge"]

Setting ENTRYPOINT replaces the vendor image’s own entry point, so the container runs the edge and not the database server. The mysql image does not include the OpenSSH client.

Starting from a distribution image

An edge that serves several integrations can start from a general-purpose distribution and install each tool it needs:

FROM ubuntu:24.04
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      ca-certificates openssh-client mysql-client postgresql-client \
 && rm -rf /var/lib/apt/lists/*
COPY --from=ghcr.io/plakarkorp/plakar-edge:<version> /bin/plakar-edge /bin/
ENTRYPOINT ["/bin/plakar-edge"]

Distribution images such as ubuntu do not include CA certificates, so ca-certificates must be installed explicitly. Some vendor images, such as the official postgres image, also lack them. Check that the base image provides them before relying on it.

Choosing the edge version

Replace <version> with a released version of the edge image rather than latest, and keep it in line with your Control Plane. An edge whose protocol version differs from the Control Plane’s still enrolls, but receives no tasks until it is upgraded.

Running the image

The image accepts the same options as the standalone binary. The state directory holds the edge identity, authentication token and package cache, and must be stored on a persistent volume. Otherwise the edge enrolls as a new edge every time its container is recreated.

For example, with Docker:

$ docker run -d --name edge-mysql-1 \
  -v edge-mysql-1:/var/lib/plakar-edge \
  -e PLAKAR_EDGE_ENROLL_KEY=<enrollment-key> \
  -e PLAKAR_EDGE_ORGANIZATION=<organization-id> \
  registry.example.com/plakar-edge-mysql:1.0 \
  -control-plane https://plakman.example.com \
  -name edge-mysql-1

Setting -name keeps the edge name stable, since the container hostname changes when the container is recreated.

On Kubernetes, set image.repository and image.tag to the custom image when installing the chart.

Pages

Solutions

Resources

Newsletter