.png){kind=logo}
Add capacity to an existing cluster with an additional Frontend Node to eliminate points of failure and achieve higher traffic availability.
Overview
In this scenario we will add an additional Frontend Node frontend-3 to an existing multi-node cluster. Adding additional Frontends decreases points of failure and allows higher traffic availability.
Directory Path Variables
There are two referenced directory locations in these instructions:
-
installer_dir: the location where the unzipped install files reside, including all installation scripts and supporting files. -
agilesec_install_dir: the location where AgileSec will be installed to.
Export these as bash variables to easily copy and paste guide instructions:
export installer_dir=</path/to/installer>
export agilesec_install_dir=</path/to/installation>
Prerequisites
Prior to configuring this scenario, users will need the following:
-
An existing, functional multi-node cluster with at least 2 Backend Nodes and 1 Frontend Node.
-
These instructions reference a 4 node cluster with 2 Backend Nodes and 2 Frontend Nodes, but you may also utilize an existing 3-node cluster with 2 Backend Nodes and 1 Frontend Node.
-
-
1 additional Frontend Node server/VM meeting all requirements in Multi-Node Linux Install Prerequisites.
-
If utilizing non-interactive installation,
Step 1: Add a New frontend-3 Configuration Block (backend-1)
On backend-1, add the following variables to the REQUIRED CONFIGURATION section near the top of $installer_dir/generate_envs/multi_node_config.conf:
frontend3_node_hostname="frontend-3"
frontend3_private_ip="<frontend-3 IP>"
frontend3_node_profile="ADDITIONAL_FRONTEND"
Update frontend3_private_ip with frontend-3’s IP.
Note: If updating a 3-node cluster, you may uncomment existing frontend2 variables instead of adding frontend3 ones. Ensure you amend subsequent instructions for frontend-2 instead of frontend-3.
Note: The difference between PRIMARY_FRONTEND and ADDITIONAL_FRONTEND is PRIMARY_FRONTEND runs additional quorum coordinating services: MongoDB arbiter, OpenSearch cluster-manager, and kafka-controller service.
Step 2: Generate Configuration Files for Each Node (backend-1)
On backend-1, run ./generate_envs/generate_envs.sh -t multi-node to regenerate the following files:
-
$installer_dir/generate_envs/generated_envs/env.backend-2 -
$installer_dir/generate_envs/generated_envs/env.backend-1 -
$installer_dir/generate_envs/generated_envs/env.frontend-3 -
$installer_dir/generate_envs/generated_envs/env.frontend-2 -
$installer_dir/generate_envs/generated_envs/env.frontend-1
Step 3: Copy All Frontend Configuration Files (backend-1)
Copy all frontend configuration files from backend-1 to their respective frontend machines:
scp $installer_dir/generate_envs/generated_envs/env.frontend-1 \
user@<frontend-1_IP>:$installer_dir/.env
scp $installer_dir/generate_envs/generated_envs/env.frontend-2 \
user@<frontend-2_IP>:$installer_dir/.env
scp $installer_dir/generate_envs/generated_envs/env.frontend-3 \
user@<frontend-3_IP>:$installer_dir/.env
Copy the certificates bundle kf-agilesec.internal-certs.tgz to frontend-3:
scp $installer_dir/certificates/kf-agilesec.internal-certs.tgz \
user@<frontend-3_IP>:$installer_dir/certificates
Step 4: Install frontend-3
If using DNS for FQDN resolution:
If your DNS provider does not resolve the FQDN for frontend-3, add the following entry to your /etc/hosts: <frontend-3 IP> <analytics_hostname>.<analytics_domain>.
Run the following on frontend-3 to unarchive the files, copy the .env to the $installer_dir root, and install the software:
cd $installer_dir/certificates/
tar zxvf kf-agilesec.internal-certs.tgz
cd ../
sudo ./scripts/tune.sh -u <user>
./install_analytics.sh install -u <user> -p <installation-dir>
Step 5: Patch Existing Frontends (frontend-1 and frontend-2)
On frontend-1:
cd $installer_dir
./install_analytics.sh patch --type new-frontend -p ../local/agilesec
sudo ./scripts/tune.sh -u <user>
On frontend-2:
cd $installer_dir
./install_analytics.sh patch --type new-frontend -p ../local/agilesec
sudo ./scripts/tune.sh -u <user>
Add -v to see verbose patch output.
Step 6: Update External FQDN Setup
Ensure you retain external access with at least one of the following:
-
Recommended for general access: Add a new DNS entry for
<analytics_hostname>.<analytics_domain>pointing to each Frontend Node’s IP address. -
For proof of concept, test cases, or single computer access: Add an entry in your external computer’s
/etc/hostsfor<analytics_hostname>.<analytics_domain>pointing to the additional Frontend Node’s IP address.# Example /etc/hosts entry: <frontend-1 ip> agilesec.kf-agilesec.com <frontend-2 ip> agilesec.kf-agilesec.com
Step 7: Verify Service Health
On each node, check the status of all services:
cd $agilesec_install_dir #Where AgileSec was installed to
./scripts/manage.sh status
If any service shows Not running, try restarting it. See On-Prem Managing Services for instructions on starting and restarting services.
Port 443 Information [Optional]
If using port 443, be aware of the following post-install behavior:
-
Since port 443 is a privileged port (< 1024), HAProxy requires root privileges to bind to it.
-
./manage.sh startas a regular user will start all services except HAProxy. -
Post-installation, HAProxy must be started or restarted with sudo in
agilesec_install_dir:
cd $agilesec_install_dir
sudo ./scripts/manage.sh start haproxy
-
However, stopping HAProxy does not require sudo:
cd $agilesec_install_dir
./scripts/manage.sh stop haproxy
-
The platform URL simplifies to
https://<analytics_hostname>.<analytics_domain>(no port number needed, since 443 is the default HTTPS port).
On frontend-1, backend-1, and backend-2 you should see 9 services in Running status:
$ ./manage.sh status
SERVICE DESCRIPTION STATUS UPTIME
------------------------ ---------------------------------------- ------------------------------ ---------------
mongodb MongoDB Server Running (PID: ####) 23h 8m 51s
opensearch OpenSearch Search Engine Running (PID: ####) 23h 8m 52s
kafka Kafka Server Running (PID: ####) 23m 17s
scheduler Scheduler Microservice Running (PID: ####) 23h 8m 37s
analytics-manager Analytics Manager Microservice Running (PID: ####) 23h 8m 37s
ingestion Ingestion Microservice Running (PID: ####) 23h 8m 37s
indexing Indexing Microservice Running (PID: ####) 23h 8m 37s
sm Security Manager Microservice Running (PID: ####) 23h 8m 37s
haproxy HAProxy Load Balancer Running (PID: ####)
Note: If v2_sensors is enabled in the .conf prior to install, you should also see td-agent Fluentd Data Collector service running on backend-1 and backend-2.
On additional non-Primary Frontends, you should see 5 services in Running status:
$ ./manage.sh status
SERVICE DESCRIPTION STATUS
------------------------ ---------------------------------------- --------
api Web API Microservice Running
webui Web UI Microservice Running
opensearch-dashboards OpenSearch Dashboards Running
cbom CBOM Exporter Microservice Running
haproxy HAProxy Load Balancer Running
After installation completes, allow approximately 30 seconds for all services to fully initialize before accessing the UI. Attempting to log in immediately may result in a 503 Service Unavailable error. If this occurs, wait 30 seconds and refresh the page.
Step 8: Test HA Configuration
For a true highly available cluster, ensure you can lose any single node (frontend or backend) without service interruption.
For each node:
-
Stop the node:
cd $agilesec_install_dir ./scripts/manage.sh stop -
Run a network scan from AgileSec UI (Sensors → Network Scan).
-
The scan should complete successfully, confirming the cluster remains operational with a single node failure.
-
Restart the node:
cd $agilesec_install_dir ./scripts/manage.sh start -
Repeat with each frontend and backend node.
Post-Installation Validation
See AgileSec On-Prem Validation Checklist for thorough post-installation validation checks.
Post-Installation System Administration
For information on System Administration options post-installation, see System Administration.
Troubleshooting
If you encounter issues during installation or operation, review AgileSec Linux Installation Troubleshooting Guide.