Architecture
An overview of the architecture for Red Hat Edge Manager
Abstract
Preface
Red Hat Edge Manager provides an architecture in which autonomous agents on edge devices communicate with a central control plane to manage operating systems, workloads, and enrollment.
Chapter 1. Red Hat Edge Manager architecture
Red Hat Edge Manager uses an autonomous agent on each device to manage the operating system and workloads, ensuring reliable operation even with limited or intermittent connectivity.
Red Hat Edge Manager supports image-based operating systems. You can include the Red Hat Edge Manager agent and its settings in the image that you distribute to devices.
Image-based operating systems let the agent start a transactional update of the image and roll back to the previous version if an update fails.
Red Hat Edge Manager architecture has the following main features:
- Agent: A lightweight process on the device that polls the service for updates, applies the desired state, and manages local workloads even during network outages.
Service: The central control plane that manages the device inventory and coordinates fleet-wide settings. To support these tasks, the service includes:
- API server: Handles authenticated communication between the service, administrative tools, and enrolled devices.
-
HTTPS gateway (standalone Red Hat Enterprise Linux only): An nginx reverse proxy on port
443that handles TLS and routes traffic to internal services by URL path. The gateway forwards agent API and telemetry ports with mutual TLS (mTLS) passthrough. See HTTPS gateway for standalone Red Hat Enterprise Linux deployments. - Database: The storage layer that holds the current device registry, enrollment data, and the target state for the fleet.
- Image Builder (optional): Builds operating system images for devices from the control plane. On Red Hat OpenShift Container Platform, the Image Builder worker requires privileged access scoped to a dedicated ServiceAccount.
-
Image-based operating system: An immutable Linux distribution that uses
bootc. This enables transactional, versioned updates that can be safely rolled back if an update fails. - Device: A hardware unit or virtual machine that runs the agent. It tracks local state, applies settings, and reports health metrics back to the service.
- Device fleet: A logical grouping of devices managed as a single unit. Fleets let you roll out updates and policies to thousands of devices at once with detailed visibility.
Additional resources
1.1. Red Hat Edge Manager agent and service
The Red Hat Edge Manager agent is a process running on each managed device that periodically communicates with the Red Hat Edge Manager service.
The Red Hat Edge Manager agent is responsible for the following tasks:
- Enrolling its device into the service.
- Checking with the service at regular intervals for changes in the device specification, such as updates to the operating system, settings, and applications.
- Applying any updates independently from the service.
-
Enforcing workload user separation: applications run as root by default when
runAsis not set. When set,runAsenables rootless (non-root) execution or privileged execution with elevated capabilities. - Validating that the required user exists on the device before starting rootless workloads.
- Reporting status of the device and the applications.
The Red Hat Edge Manager service is the control plane that connects administrators and automation to the device fleet. It manages each device from enrollment through ongoing health and activity monitoring.
The service uses a database that stores the device inventory and the target device settings. The agent polls the service for changes in the settings. If the agent detects that the current settings differ from the target, it attempts to apply the changes to the device.
When the agent receives a new target configuration from the service, the agent does the following tasks:
- Stage resources: The agent pre-downloads all required assets to local storage, including the operating system image and application container images. This step guards against network failure during the update.
-
Update operating system: The agent delegates the operating system update to
bootc, ensuring a transactional image-based transition. - Apply configuration: The agent updates the local file system by overlaying configuration files provided by the service.
- Finalize environment: If the update requires it, the agent triggers a system reboot. If no reboot is needed, it signals the relevant system services and applications to reload their settings.
- Update workloads: The agent syncs and updates applications that run on Podman or MicroShift. Podman-based applications (quadlet, container) run on Podman. Helm applications are deployed to MicroShift on the device.
If the update fails or the system does not come back online after a reboot, the agent rolls back to the previous operating system image and settings.
You can store fleet definitions in a Git repository. The Red Hat Edge Manager service syncs Git-hosted definitions with the database at regular intervals so that changes you commit are applied to the fleet.
1.2. Red Hat Edge Manager API server
The API server acts as the central communication hub, exposing secure endpoints that allow both users and agents to interact with the Red Hat Edge Manager service.
The API server exposes the following endpoints:
- User-facing API endpoint
Users can connect to the user-facing API endpoint from the command-line interface (CLI) or the web console. Users must authenticate with the configured external authentication service to obtain a JSON Web Token (JWT) to make HTTPS requests.
On standalone Red Hat Enterprise Linux deployments, users reach the user-facing API through the HTTPS gateway on port
443at path prefixes/_/flightctl/and/api/v1/. The gateway also acceptsflightctl login https://<baseDomain>without a path suffix. Port3443is not required for new installations; the gateway can continue to expose it after upgrade for clients that still target that port. For routing and TLS details, see HTTPS gateway for standalone Red Hat Enterprise Linux deployments.- Agent-facing API endpoint
-
Agents connect to the agent-facing endpoint, which is mutual TLS (mTLS)-protected. On standalone Red Hat Enterprise Linux, the gateway forwards TCP port
7443to the agent listener without terminating TLS. The service authenticates devices by using X.509 client certificates.
The Red Hat Edge Manager service also communicates with various external systems to authenticate and authorize users, get mTLS certificates signed, or query configuration for managed devices.
Chapter 2. HTTPS gateway for standalone Red Hat Enterprise Linux deployments
On standalone Red Hat Enterprise Linux deployments, the HTTPS gateway is the public entry point for administrative and device traffic, consolidating TLS termination and path-based routing on port 443.
2.1. Role of the gateway
The gateway consolidates user-facing HTTPS traffic onto port 443 so that you can simplify firewall rules, certificate management, and monitoring.
The gateway:
- Terminates TLS for the web UI and for HTTP APIs that use JWT or session authentication.
-
Routes requests by URL path on
Content from <basedomain> is not included.https://<baseDomain>/, using the same path layout as Red Hat OpenShift Container Platform Routes where practical. - Re-encrypts traffic to backend containers on the local Podman network.
-
Forwards TCP port
7443(agent API) and port4317(telemetry ingestion) with TLS passthrough so that mTLS and device certificates are validated by the backend services, not by nginx.
Backend services bind to the internal flightctl.network network. Only the gateway (and the passthrough ports above) need to be reachable from administrators, automation, and edge devices.
2.2. Path-based routing on port 443
Administrators and users connect to Content from <basedomain> is not included.https://<baseDomain>/ on port 443. The gateway maps paths to services as follows:
Table 2.1. Path-based routing on port 443
| Path prefix | Backend service |
|---|---|
|
|
Web console ( |
|
|
User-facing API ( |
|
|
CLI download artifacts ( |
|
|
Alertmanager proxy ( |
|
|
Built-in PAM OpenID Connect (OIDC) issuer ( |
|
|
Operating system image build API ( |
The gateway also rewrites top-level API paths for convenience. Requests to /api/v1/… and /ws/v1/… on port 443 are routed to the user API as if they were sent under /_/flightctl/. You can run flightctl login https://<baseDomain> without specifying an API subpath.
2.3. Agent API and telemetry passthrough
The agent API and telemetry gateway use mutual TLS. The gateway does not terminate TLS for these listeners. It forwards TCP connections on the host ports that agents and collectors already use:
-
Port
7443— agent API (mTLS) -
Port
4317— telemetry gateway ingestion (when enabled)
Plan firewall rules so that enrolled devices can reach port 7443 on your management DNS name or IP address. For telemetry, open port 4317 only when sources outside the host must send data to the telemetry gateway.
2.4. Legacy ports after upgrade
Upgraded installations can keep serving the user API on port 3443 and the image build API on port 8445 through the gateway until you reconfigure clients. New installations should use port 443 only for those APIs.
When every client uses Content from <basedomain> is not included.https://<baseDomain>/ on port 443, you can disable the legacy listeners in the gateway by setting gateway.suppressOldPorts to true in /etc/flightctl/service-config.yaml and restarting flightctl.target. See Migrating to the standalone HTTPS gateway in the Additional resources section.
2.5. Configuration overview
The /etc/flightctl/service-config.yaml file controls gateway behavior:
-
global.baseDomain— DNS name for the deployment (for example,edge.example.com). -
global.generateCertificates—builtin(default) to create a local CA and service certificates, ornonewhen you supply certificates under/etc/flightctl/pki/. -
gateway.suppressOldPorts— whentrue, the gateway stops exposing legacy API and image builder ports3443and8445on the base domain.
For DNS, certificates, migration steps, and port planning, see the Additional resources section.
Chapter 3. Network ports for Red Hat Edge Manager
Plan firewall rules so that administrators, automation, and edge devices can reach Red Hat Edge Manager services. The ports are the same on Red Hat OpenShift Container Platform and Red Hat Enterprise Linux; only the exposure method differs.
The Red Hat Edge Manager API server exposes a user-facing HTTPS API and a separate agent-facing mTLS API, as described in Red Hat Edge Manager API server. On standalone Red Hat Enterprise Linux deployments, an nginx flightctl-gateway service is the primary public entry point on port 443; see HTTPS gateway for standalone Red Hat Enterprise Linux deployments.
The following tables list TCP ports that appear when Red Hat Edge Manager components accept connections. On Red Hat OpenShift Container Platform, you usually reach these ports through cluster networking, Services, and Routes. On Red Hat Enterprise Linux, administrators and devices reach the gateway and passthrough ports on the host (or on the host’s DNS name). Your organization might use different host names, TLS termination, or port mappings; confirm the values that apply to your deployment before you change firewall policy.
3.1. Red Hat OpenShift Container Platform compared with Red Hat Enterprise Linux
- On Red Hat OpenShift Container Platform: Which ports are reachable from outside the cluster depends on your Routes, Ingress configuration, and load balancers, and on whether you integrate Red Hat Edge Manager with other consoles. Optional integration ports in the second inbound table are often reachable only inside the cluster unless you expose them through a Service or Route. Red Hat OpenShift Container Platform and cluster infrastructure can require many additional ports (for example, for the Kubernetes API, ingress controllers, or monitoring). Plan those rules according to Red Hat OpenShift Container Platform documentation and your platform team. The tables below list only Red Hat Edge Manager-related ports that customers often ask about for edge and administrative access.
-
On Red Hat Enterprise Linux: Use the same port numbers when you allow traffic to the DNS name or IP address of your Red Hat Edge Manager host. Configure the host firewall (for example,
firewalld), any network firewalls in front of the host, and routing so that administrators, automation, and edge devices can reach those ports. Reserve the listed port numbers on the host so they do not conflict with your monitoring, security, backup, or other local services. Plan host-hardening and firewall guidance according to Red Hat Enterprise Linux documentation and your security team.
3.2. Inbound connections
Traffic in the following tables flows toward Red Hat Edge Manager components or the endpoints that front them. The "Required or optional" column indicates whether each port serves core functionality or optional integrations.
The first table lists ports that most deployments open for the web console, user API, and enrolled devices. The second table lists optional integration ports for monitoring, image builds, telemetry, and similar features. Include those rows in firewall and host port planning when traffic crosses a network boundary.
Table 3.1. Required inbound ports
| Port | Protocol | Service or component | Purpose | Required or optional | Counterpart |
|---|---|---|---|---|---|
| 443 | TCP | HTTPS gateway (standalone) | TLS termination and path-based routing to the web console, user API, CLI artifacts, authentication integration, image builder API, and related services on standalone Red Hat Enterprise Linux deployments | Required when administrators, users, or automation access standalone Red Hat Edge Manager through the unified gateway |
Browsers, the Red Hat Edge Manager CLI, REST clients, and CI/CD systems that use |
| 3443 | TCP | User API (legacy) |
HTTPS API for users and automation (CLI, REST) on a dedicated port, distinct from the agent API and from the standalone route on port | Optional for standalone deployments. Not required for new installations. Exposed for backward compatibility when you upgrade from a release that used this port for the user API. Open this port only if your clients are configured to use it |
Administrators, CI/CD systems, and API clients that still target port |
| 7443 | TCP | Agent API (passthrough on standalone) | mTLS API for enrolled devices. On standalone Red Hat Enterprise Linux, the gateway forwards this port without terminating TLS | Required for device management so agents can sync and report status | Edge devices running the Red Hat Edge Manager agent |
For standalone deployments, the following legacy ports are not required for new installations. Open them only when your environment still uses the endpoint after an upgrade:
-
Port
443— Use inflightctl logincommands and other user API client configuration. -
Port
3443— Open only when clients still target this endpoint for the user API. -
Port
8090— Not required; download the CLI from the web console on port443. -
Port
8444— Sign-in and certificate integration use path-based routing on port443. -
Port
8445— The operating system image build API uses path-based routing on port443.
Edge devices initiate outbound connections to port 7443 on your management endpoint. On firewalls between enrolled devices and Red Hat Edge Manager, allow destination port 7443 to the host name or IP address (or route) that agents use for management.
Table 3.2. Optional inbound ports
| Port | Protocol | Service or component | Purpose | Required or optional | Counterpart |
|---|---|---|---|---|---|
| 3000 | TCP | Monitoring dashboards (Grafana) | Web UI for bundled monitoring dashboards when Grafana is exposed on this port | Optional. Required when administrators access Grafana outside the cluster or host | Browsers opening the Grafana URL |
| 4317 | TCP | Telemetry gateway (ingestion) | Primary port for ingesting device or service telemetry when the telemetry gateway is exposed | Optional. Open inbound only if telemetry sources outside the Red Hat Edge Manager network send data to this port | Edge devices or monitoring collectors configured to report telemetry to this endpoint |
| 8090 | TCP | CLI optional downloads (legacy) |
Serves optional CLI bundles or plugins on a dedicated port when this endpoint is exposed; standalone deployments use the web console on port | Optional. Not required for new standalone installations. Exposed for backward compatibility when you upgrade from a release that used this port for CLI downloads. Open inbound only if CLI hosts outside the Red Hat Edge Manager network must reach this port |
Administrator workstations or CI/CD runners that still target port |
| 8443 | TCP | External alerting integration | Inbound endpoint for external monitoring systems that connect through this port on your Red Hat Edge Manager host or exposed endpoint | Optional. Required only if external monitoring or alerting tools connect to this port | Your Prometheus, Alertmanager, or other monitoring stack, as configured in your integration |
| 8444 | TCP | Sign-in and certificate integration (legacy) |
Internal Red Hat Edge Manager service for OpenID Connect (OIDC) and enrollment certificate flows. This traffic uses path-based routing on port | Optional. Not required for new installations. You do not need an inbound firewall rule for normal sign-in or OIDC integration. Exposed for backward compatibility when you upgrade from a release that used this port. Reserve the port on the host when it is still in use, to avoid conflicts with monitoring, security, or backup tools |
Red Hat Edge Manager control plane (internal). External identity providers or browsers only if your deployment still exposes port |
| 8445 | TCP | Operating system image build API (legacy) |
API for creating and managing operating system image builds when exposed on a dedicated port; standalone deployments use path-based routing on port | Optional. Not required for new standalone installations. Exposed for backward compatibility when you upgrade from a release that used this port. Open inbound only if build clients or automation outside the Red Hat Edge Manager network still target this port |
Administrator workstations, CI/CD systems, or the Red Hat Edge Manager CLI that still target port |
| 9093 | TCP | Alertmanager (monitoring) | Alert routing and querying for the bundled Alertmanager when this port is exposed | Optional. Required when external monitoring systems connect to Alertmanager on this port | Prometheus, Alertmanager, or other monitoring tools in your stack |
| 9464 | TCP | Telemetry gateway (export) | Secondary port for telemetry export or metrics when your deployment exposes both gateway ports | Optional. Open inbound only if external systems scrape or pull telemetry from this port | Monitoring systems or collectors configured to read from this endpoint |
Port 8444 traffic is served through path-based routing on port 443, not on a separate inbound port. Plan a firewall or host rule for port 8444 only when your deployment still exposes it after an upgrade, or when you must avoid port conflicts with other host services.
Bundled monitoring can expose more than one alerting port. Port 8443 is an integration proxy endpoint; port 9093 is the conventional Alertmanager port. Your deployment might expose one or both. Confirm which ports are in use (ss, netstat, or your platform team) before you change firewall policy.
3.3. Outbound connections
Devices, the Red Hat Edge Manager deployment, and administrators often need outbound access to external services. Requirements vary by how you configure image builds, GitOps, and identity. The table lists common examples only; plan additional outbound firewall rules for every registry, identity provider, and other service your deployment uses.
Table 3.3. Outbound ports
| Port | Protocol | Purpose | Direction | Counterpart |
|---|---|---|---|---|
| 443 | TCP | HTTPS to container registries, Git hosting, software sources, OpenID Connect and OAuth identity providers, or Red Hat Trusted Profile Analyzer for vulnerability reporting |
Outbound from the cluster or Red Hat Edge Manager host, from | Image registries, Git servers, artifact hosts, your organization’s identity provider, or the Red Hat Trusted Profile Analyzer API and OIDC issuer used for vulnerability sync |
| 22 | TCP | SSH to Git hosts when you use SSH remotes instead of HTTPS | Outbound from build systems or from systems that run Git operations against SSH remotes | Git hosting service |
| 5432 | TCP | PostgreSQL database | Outbound from the Red Hat Edge Manager control plane to a remote PostgreSQL instance when you do not run the database on the same host as the application services |
Your organization’s PostgreSQL server (the default port is |
| 6379 | TCP | Key-value store (Redis or Valkey) | Outbound from the Red Hat Edge Manager control plane to a remote key-value store when you do not run the KV service on the same host as the application services |
Your organization’s Redis- or Valkey-compatible server (the default port is |
| 7443 | TCP | Agent API | Outbound from edge devices to the agent API port on your management endpoint | Red Hat Edge Manager management endpoint (DNS name, IP address, or route that enrolled agents are configured to use) |
Embedded PostgreSQL and key-value services on the same host use ports 5432 and 6379 locally. You only need outbound rules for those ports when the control plane connects to external instances.
Some environments also require outbound access to Network Time Protocol (NTP), DNS, or internal ticket systems; those dependencies come from your operational policies, not from Red Hat Edge Manager alone.
Chapter 4. Device enrollment
You need to enroll devices to a Red Hat Edge Manager service before you can start managing them. The Red Hat Edge Manager agent that runs on a device handles the device enrollment.
When the agent starts on a device, the agent searches for the configuration in the /etc/flightctl/config.yaml file. The file defines the following configurations:
- The enrollment endpoint, which is the Red Hat Edge Manager service that the agent connects to for enrollment.
- The enrollment certificate, which is the X.509 client certificate and key that the agent only uses to securely request enrollment from the Red Hat Edge Manager service.
- Additional agent configuration options, such as system information reporting and enrollment labels.
Additional resources
4.1. The enrollment process
The agent starts enrollment by connecting to the Red Hat Edge Manager service at the enrollment endpoint defined in the configuration file.
After establishing a secure, mutual TLS (mTLS)-protected network connection with the service, the agent submits an enrollment request to the service.
The request includes a description of the device hardware and operating system, an X.509 certificate signing request, the cryptographic identity of the device, and agent-proposed labels.
An authorized user must approve the enrollment request. After approval, the Red Hat Edge Manager service trusts and manages the device.
4.2. Enrollment methods
Devices get their enrollment endpoint and certificate in one of two ways: early binding (baked into the operating system image) or late binding (set at provisioning time).
Early binding: You can build an operating system image that includes the enrollment endpoint and certificate. Devices that use an early binding image can connect to the defined Red Hat Edge Manager service to request enrollment without any additional provisioning configuration.
The devices share the same long-lived X.509 client certificate. However, this binds the devices to a specific service and owner.
Late binding: You can set the enrollment endpoint and certificate at provisioning time instead of including them in the operating system image. Devices that use a late binding image are not tied to a single owner or service and can have per-device, short-lived X.509 client certificates.
However, late binding requires tools that can request per-device enrollment endpoints and certificates from the Red Hat Edge Manager service. The tools inject them into the system by using cloud-init, Ignition, or kickstart.
The enrollment certificate secures only the network link for submitting an enrollment request. It plays no role in verifying or approving the request. After enrollment, devices use per-device management certificates instead.