Install on AWS

Gardience runs on one EC2 instance like on any Linux server. This page covers what is specific to AWS: the instance, the security group, and launching machines that join Gardience by themselves. It follows the setup used to test Gardience on AWS: 1,020 independent machines (1,000 Linux and 20 Windows) joined through one enrollment token and were patched to a new kernel and rebooted in one governed run, 1,020 of 1,020 ok (see the sizing guide).

Pick the instance#

Any current Ubuntu or other Linux image with Docker works, on Arm (Graviton, the g types) or x86. The 1,002-agent test ran on an m7g.xlarge with Ubuntu 24.04.

Security group#

Keep 4505 and 4506 closed to the internet. Agents only connect out to Gardience, so managed machines need no inbound rule for Gardience.

Install#

1. Launch the instance with the security group above and a public or private DNS name your users can reach.

2. Install Docker. Ubuntu's own package works:

   Copy

   sudo apt-get update && sudo apt-get install -y docker.io docker-compose-v2

3. Copy the release bundle to the instance and install it as described in Install on one server. Use the console's DNS name for --hostname, the instance's private address for --master-address (what agents in your VPC connect to), and set --fleet-size to the number of machines you expect, for example:

   Copy

   sudo ./install/install.sh --hostname gardience.example.com --master-address 10.0.1.15 --fleet-size 1000

4. Run sudo /opt/gardience/gardience doctor. Every line should say PASS, including "Salt master hardening in place".

The console's certificate is self-signed until you install your own (see the installer's TLS options), so browsers warn on the first visit.

Machines that join at launch#

New EC2 machines can join Gardience from their launch script (EC2 user data), with no manual key approval, using an enrollment token:

1. In the console, open Machines > Add machines, create an enrollment (see Enrollment tokens) and download the playbook.
2. Open the playbook and copy the token that starts with enr-.
3. Use a launch script like the one below. It installs the tested Salt release with the checksum-pinned installer, points the agent at Gardience, and presents the token.

Linux (EC2 user data):

#!/bin/bash
GARDIENCE=10.0.1.15          # the Gardience instance's private address
TOKEN=enr-REPLACE-ME         # from the enrollment playbook
curl -fsSL -o /tmp/b.sh https://github.com/saltstack/salt-bootstrap/releases/download/v2026.10.08/bootstrap-salt.sh
echo "d78bff355ac2cad508201acc6a83c94ff9182292abff0e321ed8c87b4ad7fc3a  /tmp/b.sh" | sha256sum -c || exit 1
sh /tmp/b.sh -X stable 3008.3
mkdir -p /etc/salt/minion.d
IID=$(curl -s -X PUT http://169.254.169.254/latest/api/token -H 'X-aws-ec2-metadata-token-ttl-seconds: 60' \
  | xargs -I{} curl -s -H 'X-aws-ec2-metadata-token: {}' http://169.254.169.254/latest/meta-data/instance-id)
cat > /etc/salt/minion.d/gardience.conf <<EOF
master: $GARDIENCE
id: aws-${IID#i-}
autosign_grains: [gardience_enroll]
ping_interval: 5
auth_safemode: True
EOF
echo "gardience_enroll: $TOKEN" > /etc/salt/grains
systemctl enable salt-minion && systemctl restart salt-minion

The script uses systemctl restart, not start: on Ubuntu the package starts the agent before the configuration is written. ping_interval and auth_safemode let an agent restart itself if its connection to the master ever hangs (seen with Salt's own agent under heavy load).

For Windows, install the checksum-checked Salt MSI from the launch script and write the same settings to C:\ProgramData\Salt Project\Salt\conf\minion.d\gardience.conf and the token to C:\ProgramData\Salt Project\Salt\conf\grains, then restart the salt-minion service. The PowerShell installer in Enroll Windows machines shows the exact steps.

Gardience removes the token from each machine at its next scan. Close the enrollment when the launch wave is done.

Stopping and starting#

A stopped instance keeps its disks (you pay only for storage) and comes back with its data, sign-ins and agent keys. Agents reconnect on their own within a minute or two of Gardience starting again. Without an Elastic IP the public address changes at each start; give the instance an Elastic IP or a DNS record your users can rely on.

Related#

• Install on one server
• Enroll Linux machines
• Enroll Windows machines
• Requirements