Plan DNS and TLS for the standalone gateway

Configure global.baseDomain and TLS material before or immediately after you install Red Hat Edge Manager on Red Hat Enterprise Linux, so the flightctl-gateway service can present a single trusted HTTPS endpoint on port 443.

Before you begin

  • A Red Hat Enterprise Linux host prepared for the Red Hat Edge Manager RPM installation. See Installing the Red Hat Edge Manager RPM package.
  • Administrative access (root or sudo) on the host.
  • A DNS name that resolves to the Red Hat Edge Manager host from administrator workstations, automation, and (for the agent API) enrolled edge devices.

Procedure

  1. Choose the base domain (baseDomain) for the deployment. Use a fully qualified domain name that clients will use in the browser and in flightctl login, for example edge.example.com. This name is the server_name for HTTPS on port 443; path prefixes such as /_/flightctl/ are served on the same host name, not on separate virtual hosts.
  2. Ensure that DNS records point to the Red Hat Edge Manager host:
    • Create an A or AAAA record (or equivalent) for <baseDomain> that resolves to the host IP address used for management access.
    • Confirm resolution from a client workstation: 
      dig +short <baseDomain>
  3. Plan firewall rules on the host and on perimeter firewalls:
    • Allow inbound TCP port 443 for the web console, user API, and integrated services behind the gateway.
    • Allow inbound TCP port 7443 for enrolled devices that connect to the agent API.
    • Allow inbound TCP port 4317 only if external systems send telemetry to the telemetry gateway on this host.

      For a full port list, see Network ports for Red Hat Edge Manager.

  4. Configure TLS for the gateway in /etc/flightctl/service-config.yaml.
    1. For a new installation with automatically generated certificates (typical lab or proof-of-concept), set: 
      global:
  baseDomain: <baseDomain>
  generateCertificates: builtin

      When generateCertificates is builtin, the installation creates a local CA under /etc/flightctl/pki/ and issues a gateway server certificate at /etc/flightctl/pki/flightctl-gateway/server.crt and /etc/flightctl/pki/flightctl-gateway/server.key. Distribute /etc/flightctl/pki/ca.crt to administrator workstations and browsers that must trust the deployment, or replace the generated material with certificates from your organizational CA (next step).

    2. To use your own CA and certificates, set generateCertificates to none and place PEM files before you start flightctl.target: 
      global:
  baseDomain: <baseDomain>
  generateCertificates: none

      Install at minimum:

      • CA certificate: /etc/flightctl/pki/ca.crt (and /etc/flightctl/pki/ca.key if you manage the CA on this host)
      • Gateway certificate and key: /etc/flightctl/pki/flightctl-gateway/server.crt and /etc/flightctl/pki/flightctl-gateway/server.key

        The gateway certificate must be valid for <baseDomain> (and any subject alternative names your environment requires). Agent and telemetry services use separate certificates under /etc/flightctl/pki/; the gateway certificate covers only the ports where nginx handles TLS.

  5. If you edit service-config.yaml on an existing host, stop services, update the file, and restart: 
    sudo systemctl stop flightctl.target
sudo vi /etc/flightctl/service-config.yaml
sudo systemctl enable --now flightctl.target
  6. Verify that the gateway is running and listening on port 443: 
    sudo systemctl status flightctl-gateway.service
sudo ss -tlnp | grep -E ':443|:7443'
  7. Open the web console at https://<baseDomain>/ and log in. From an administrator workstation, authenticate the CLI with one of the following:
    • flightctl login https://<baseDomain> --web: Sign in through the browser (recommended when you already use the web console).
    • flightctl login https://<baseDomain> --username <user_name> --password <password>: Non-interactive sign-in.

      If you use self-signed or private-CA certificates, trust the CA on the client or add --insecure-skip-tls-verify to the flightctl login command only for non-production testing.

    • flightctl-gateway.service is active (running).
    • curl -k -o /dev/null -w '%{http_code}\n' https://<baseDomain>/ returns 200 or a redirect to the sign-in page after you configure authentication.
    • flightctl login https://<baseDomain> --web succeeds for a valid user.
    • flightctl login https://<baseDomain> --username <user_name> --password <password> succeeds when you use non-interactive authentication.

What to do next

When you integrate an external OIDC provider, register redirect and callback URLs that use https://<baseDomain>/ on port 443, not legacy service ports. Update externalOidcAuthority and related settings in service-config.yaml to match URLs that clients can reach through the gateway. See Authenticating with OpenID Connect.