Architecture
An overview of the architecture for Red Hat Edge Manager
Abstract
Preface
Overview of the Red Hat Edge Manager architecture, major components, and how devices enroll and communicate with the control plane.
Chapter 1. Red Hat Edge Manager architecture
Red Hat Edge Manager is designed for scalability and resilience, leveraging an autonomous Red Hat Edge Manager agent to manage the operating system and workloads on each device. By offloading management logic to the edge, this architecture ensures reliable deployment and monitoring across extensive fleets. The agent maintains operational integrity locally and reports status to the Red Hat Edge Manager service as connectivity allows, enabling consistent management even in limited or intermittent network environments.
Red Hat Edge Manager supports image-based operating systems. You can include the Red Hat Edge Manager agent and the agent configuration in the image that is distributed to the devices.
Image-based operating systems allow the agent to initiate a transactional update of the image and to roll back to the previous version in case of an update error.
Red Hat Edge Manager architecture has the following main features:
- Agent: A lightweight process on the device that autonomously polls the service for updates, implements the desired state, and manages local workloads even during network outages.
Service: The central control plane responsible for managing device inventory and coordinating fleet-wide configurations. To support these operations, 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 that terminates TLS on port
443, routes traffic to internal services by URL path, and forwards the agent API and telemetry ports with mTLS passthrough. See HTTPS gateway for standalone Red Hat Enterprise Linux deployments. - Database: The persistent storage layer that holds the current device registry, enrollment information, and the target state definitions for the fleet.
-
Image-based operating system: An immutable Linux distribution using
bootc. This enables transactional, versioned updates that can be safely rolled back, ensuring maximum reliability for edge deployments. - Device: An individual hardware unit or virtual machine running the agent. It maintains local state awareness, independently applying configurations and reporting its unique health metrics back to the service.
- Device fleet: A logical grouping of devices managed as a single entity. Fleets allow you to roll out updates and policies to thousands of devices simultaneously with granular visibility.
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.
- Periodically checking with the service for changes in the device specification, such as changes to the operating system, configuration, and applications.
- Applying any updates independently from the service.
-
Enforcing workload user separation: applications run as root by default when
runAsis not specified; when specified,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 acts as the central hub for your edge operations, functioning as a reliable bridge between your core systems and your distributed devices. It manages the entire life of a device from the moment it’s securely connected to the network to the ongoing tracking of its health and activity across the fleet.
The service communicates with a database that stores the device inventory and the target device configuration. When communicating with the service, the agent polls the service for changes in the configuration. If the agent detects that the current configuration deviates from the target configuration, the agent 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: To ensure resilience against network failure during the update, the agent pre-downloads all required assets—including the operating system image and application container images—directly to local storage.
-
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 required by the update, the agent triggers a system reboot. If no reboot is necessary, it signals the relevant system services and applications to reload their configurations.
- Update Workloads: The agent synchronizes and updates applications running 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 return online after rebooting, the agent automatically rolls back to the previous operating system image and configuration.
You can maintain fleet definitions in Git. Red Hat Edge Manager periodically syncs with the fleet definitions in the database.
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 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, the user-facing API is reachable through the HTTPS gateway on port
443at path prefixes/_/flightctl/and/api/v1/. The gateway also acceptsflightctl login Content from <basedomain> is not included.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 mTLS-protected. On standalone Red Hat Enterprise Linux, the gateway forwards TCP port
7443to the agent listener without terminating TLS. The service authenticates devices using the 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.
1.3. HTTPS gateway for standalone Red Hat Enterprise Linux deployments
On standalone Red Hat Enterprise Linux deployments, an nginx-based flightctl-gateway service is the public HTTPS entry point for the web console and most administrative APIs. The gateway terminates TLS on port 443, routes traffic to backend services on the Podman network, and passes agent and telemetry connections through without terminating mTLS.
1.3.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.
1.3.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:
| Path prefix | Backend service |
|---|---|
|
|
Web console ( |
|
|
User-facing API ( |
|
|
CLI download artifacts ( |
|
|
Alertmanager proxy ( |
|
|
Built-in PAM OIDC issuer ( |
|
|
OS 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 Content from <basedomain> is not included.https://<baseDomain> without specifying an API subpath.
1.3.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.
1.3.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 in release 1.2 and later 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.
1.3.5. Configuration overview
Gateway behavior is driven by /etc/flightctl/service-config.yaml:
-
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.
1.4. Network ports for Red Hat Edge Manager
Plan firewall rules and network paths so that administrators, automation, and edge devices can reach Red Hat Edge Manager. The TCP ports in the following tables are the same whether you run Red Hat Edge Manager on Red Hat OpenShift Container Platform or on Red Hat Enterprise Linux; what differs is how you expose and protect them (for example, Red Hat OpenShift Container Platform routes and load balancers versus a Red Hat Enterprise Linux host firewall and perimeter rules).
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 in release 1.2 and later, 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.
1.4.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.
1.4.2. Inbound connections
Traffic in the following tables is toward the Red Hat Edge Manager components or the endpoints that front them. "Required or optional" indicates whether each port is required for core Red Hat Edge Manager functionality or for optional integrations; your security approval process might still require every listed port.
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.
Knowledge of how Red Hat Edge Manager runs internal services can help when you troubleshoot or configure a deployment, but it is not required to use the product or to plan firewall rules from the tables in this topic.
| 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, use port 443 in flightctl login commands and other user API client configuration. Use port 3443 only when your environment still relies on that endpoint after an upgrade. Standalone deployments do not require port 8090 for CLI downloads; download the CLI from the web console on port 443. Open port 8090 only when your environment still uses that endpoint after an upgrade. Sign-in and certificate integration use path-based routing on port 443; you do not need a separate inbound rule for port 8444 unless your environment still exposes it after an upgrade. Standalone deployments in release 1.2 and later do not require port 8445 for the OS image build API; that API uses path-based routing on port 443. Open port 8445 only when your environment still exposes it after an upgrade.
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.
| 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 in release 1.2 and later use the web console on port | Optional. Not required for standalone deployments in release 1.2 and later. 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 OIDC and enrollment certificate flows. In release 1.2 and later, this traffic uses path-based routing on port | Optional. Not required for new installations in release 1.2 and later. You do not need an inbound firewall rule for normal sign-in or OIDC integration on those releases. 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 | OS image build API (legacy) |
API for creating and managing OS image builds when exposed on a dedicated port; standalone deployments in release 1.2 and later use path-based routing on port | Optional. Not required for standalone deployments in release 1.2 and later. 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 supports internal identity and certificate integration inside Red Hat Edge Manager. You do not need to understand those internal flows to operate the product. In release 1.2 and later, that 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 (for example, after an upgrade) or when you must avoid port conflicts with other services on the host.
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.
1.4.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.
| 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 database or KV instances.
Some environments also require outbound access to NTP, DNS, or internal ticket systems; those dependencies come from your operational policies, not from Red Hat Edge Manager alone.
Chapter 2. 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. For more information, see Reporting system information from the agent and Device alias and enrollment labels.
2.1. The enrollment process
The agent starts the enrollment process by searching for the enrollment endpoint, the Red Hat Edge Manager service, that is defined in the configuration file.
After establishing a secure, mTLS-protected network connection with the service, the agent submits an enrollment request to the service.
The request includes a description of hardware and operating system of the device, a X.509 certificate signing request, the cryptographic identity of the device, and labels proposed by the agent (including a default device alias when configured).
The enrollment request must be approved by an authorized user. After the request is approved, the device becomes trusted and managed by the Red Hat Edge Manager service.
2.2. Enrollment methods
You can provision the enrollment endpoint and certificate to the device in the following ways. The simplified image building workflow lets you choose Early or Late binding in the UI; see the Building images with the simplified workflow.
Early binding: You can build an operating system image that includes the enrollment endpoint and certificate. Devices using an early binding image can automatically connect to the defined Red Hat Edge Manager service to request enrollment, without depending on any provisioning infrastructure.
The devices share the same long-lived X.509 client certificate. However, in this case, the devices are bound to a specific service and owner.
Late binding: You can define the enrollment endpoint and certificate at provisioning time instead of including them in the operating system image. Devices using a late binding image are not bound to a single owner or service and can have device-specific, short-lived X.509 client certificates.
However, late binding requires virtualization or bare metal provisioning infrastructure that can request device-specific enrollment endpoints and certificates from the Red Hat Edge Manager service and inject them into the provisioned system by using mechanisms such as Content from cloud-init.io is not included.cloud-init, Content from coreos.github.io is not included.Ignition, or Content from anaconda-installer.readthedocs.io is not included.kickstart.
The enrollment certificate is only used to secure the network connection for submitting an enrollment request. The enrollment certificate is not involved in the actual verification or approval of the enrollment request. The enrollment certificate is no longer used with enrolled devices, as the devices rely on device-specific management certificates instead.