Adding a Controller

Prev Next

The Controller is the central point of administration for AppGate ZTNA. It is a stateless appliance with an internal database used to store system configuration. The first appliance in a new Collective is always the Controller. During creation, the Appliance Hostname and the Profile DNS name are set.

This section describes how to configure an additional Controller in an AppGate system.

Each Controller must be deployed in a network that allows communication with:

  • Configured identity providers

  • Configured MFA providers

  • Configured scripts


Determining the number of Controllers

You can configure between one and nine Controllers.

For high‑availability (HA) deployments:

  • A minimum of two Controllers is required.

  • A minimum of three Controllers is recommended to improve stability during database migrations, maintenance, and upgrades.

HA Controllers are not designed for active‑passive operation. Controllers should not be configured with an offline backup. If a Controller is kept offline, its database becomes outdated and is unlikely to successfully replace a failed Controller.

Ensure that all Controllers remain online and are able to communicate with each other at all times.


Before adding a Controller

Before adding a Controller, ensure the following configurations are in place:

Client-to-appliance communication

  • The Profile DNS name is created when the first Controller is configured.

  • This DNS name is shared across all Controllers and passed to Clients through the Client profile.

  • Clients use the Profile DNS name to establish TLS connections to Controllers on port 443.

For HA Controllers, it is strongly recommended to use a DNS record with multiple A records:

  • All Controllers already share the same Profile DNS name.

  • Create one A record per Controller IP address.

  • DNS resolution is the only mechanism clients use to discover available Controllers and fail over when one Controller is unreachable.

Appliance-to-appliance communication

  • Peer‑to‑peer traffic uses the System TLS Connection settings.

  • The single packet authorization (SPA) implementation used by AppGate ZTNA for appliance‑to‑appliance communication can conflict with firewalls that allow all TLS traffic.

  • Allow TCP port 443 between appliances.

Controllers communicate with each other using their Appliance Hostname. Each Controller must therefore have a resolvable hostname configured in System Settings.


Configuring additional Controllers

To add an additional Controller:

  • Add a new appliance or reconfigure an existing appliance.

  • Ensure the candidate Controller appliance is already registered with the Controller.

  • Verify that all existing Controllers and the candidate Controller have a status of Healthy.

If any Controller is Busy, wait until it returns to a Healthy state. If a Warning or Error status is displayed, resolve the issue before making changes.

NOTE

Always perform a Controller backup before making configuration changes related to HA Controllers.

WARNING

Controllers can only be added one at a time. Do not add or remove Controllers unless all Controllers have a status of Healthy.

To configure a Controller:

  1. In the Add/Edit Appliance page, select the Controller checkbox in the Functions tab.

  2. Complete the following configuration fields:

Site Settings

  • Appliance Site. Select the Site from the dropdown list.

System TLS Connection (using SPA)

These settings are used for peer‑to‑peer traffic:

  • TLS Port. The inbound TLS connection port to the appliance.

  • Allowed Sources. Select +Add to add one or more allowed sources by adding the Address, Netmask Length, and the Network Interface. The requesting IP address must match at least one allowed source.

  • SPA Mode. Allows the SPA mode to be changed for a specific appliance. Select one of the following:

    • No override

    • Check TCP SPA key before allowing connections

    • Check UDP (and TCP) SPA key before allowing connections

  • Enable proxy protocol. When enabled, the appliance accepts only packets that include a proxy protocol header. AppGate ZTNA supports proxy protocol versions 1 and 2.

NOTE

When traffic originates from a known source, add that source to Allowed Sources. Failure to do so introduces a security risk.

Admin/API TLS Connection

An Admin/API TLS connection is provided for system management on TCP port 8443. External systems use this connection to make REST API calls to the Controller. Refer to System security - best practices before configuring Admin/API-to-appliance communications.

  • Unique Admin Hostname. Enter a fully-qualified domain name or an IPv4 or IPv6 address.

  • TLS Port. The default port is 8443.

  • Allowed Sources. Select +Add to add allowed sources by adding the Address, Netmask Length, and the Network Interface. The requesting IP address must match at least one allowed source.

  • TLS Ciphers. Select +Add to select the allowed TLS ciphers. The default ciphers are recommended unless browser requirements differ.

  • HTTPS Certificate. Adding a certificate removes the untrusted browser warning associated with the default self-signed certificate. For more information, see Removing the browser security warning. Select from the following options:

    • None.

    • Use CSR format. Select to create and download a CSR file to submit to a CSA. Once the file has been validated, you can upload it here.

    • Use PKCS #12 format. Select to upload a PKCS #12 file containing a CA-signed certificate and provide a password.

After completing the configuration, continue to the Miscellaneous tab.


Removing a Controller

To remove a Controller:

  1. Clear the Controller function checkbox.

  2. Wait for the appliance to return to a Healthy state.

When a Controller is removed from an HA configuration:

  • All database data on the appliance is wiped.

  • The p12 key is deleted.

NOTE

A functioning Controller cannot be deactivated. You must first disable the Controller function and wait for the appliance to become Healthy.


Using HA Controllers

AppGate ZTNA includes built‑in support for high‑availability, multi‑master Controllers.

  • HA mechanisms use a round‑robin load‑balancing algorithm on the AppGate Client.

  • Appliances can redirect clients to another Controller during certain failure conditions.

Internal load balancing relies on the Profile DNS name created when the first Controller is configured. This name is automatically shared across all Controllers in the Collective.

For all Profile DNS names, create multiple A records, one for each Controller.

IP pools for HA Controllers

Controllers act as a DHCP‑like service for the AppGate client multi‑tunnel adapter.

  • When multiple Controllers are present, the IP Pool is distributed evenly.

  • If a Controller becomes unavailable, the IP Pool is temporarily degraded.

  • Existing IP addresses can be renewed by other Controllers, so this is usually not disruptive.

To account for degradation scenarios, follow the recommended IP Pool sizing guidelines.

HA Controller Administration

Managing HA Controllers is the same as managing a single Controller:

  • Administrators can manage the system from any Controller.

  • Configuration changes are replicated automatically.

However, use only one Controller for administration:

  • This is critical for scripts that make repeated REST API calls.

  • It prevents database conflicts when multiple admins edit the same object.

  • When conflicts occur, the last update always wins.

If a load balancer is used in front of HA Controllers, do not use the load balancer hostname for administration.