Install Secure Agent on Virtual Machine (K3s)

Updated April 11, 2025 05:58

💪 Did you know? Secure Agent installation can be done by a non-root user. Root access is only needed for setting up system prerequisites before installation.

This page provides instructions for installing the Secure Agent on a virtual machine (VM) by deploying K3s in a rootless execution mode.

System requirements

Before installing the Secure Agent, ensure that the virtual machine (VM) meets the following requirements:

At least 80GB of available disk space.
A Linux-based OS running on an amd64 (x86_64) architecture with systemd enabled.
The Secure Agent requires the following ports for internal services. Ensure these ports are open and accessible:
- Kubernetes API: 6443
- Internal K3s proxy: 10443, 10080
- MinIO storage: 9000, 32075
- MinIO console: 9001, 30614
- Traefik ingress: 31037, 32547

Prerequisites

Before installing the Secure Agent, complete the following setup steps to prepare your Atlan tenant and virtual machine.

Configure Atlan tenant

In Atlan, complete the following steps to configure the tenant:

Sign in to your tenant as an Atlan admin.
From the left menu of any screen, click Admin.
Under Workspace click Labs.
Navigate to Workflow Center.
Enable the Crawl assets using Secure Agent toggle.

Configure virtual machine

On the virtual machine, complete the following steps to configure it:

Log in as a root user.
Create the required directory to configure cgroup delegation with:
```
sudo mkdir -p /etc/systemd/system/user@.service.d
```

Use the below cat command to create the delegation file with required configuration:

cat <<EOF | sudo tee /etc/systemd/system/user@.service.d/delegate.conf
[Service]
Delegate=cpu cpuset io memory pids
EOF

Use the below command to reload systemd:

sudo systemctl daemon-reload && sudo reboot

To keep the Secure Agent running after logout, the root user must enable service persistence for the user installing it by running the following command:
```
sudo loginctl enable-linger <user_installing_secure_agent>
```
- Replace <user_installing_secure_agent> with the actual username of the user installing the Secure Agent.
Run the following commands to enable IP forwarding so Secure Agent can communicate with other Secure Agent instances and make network requests to the Atlan tenant.
- IPv4 forwarding:
```
sudo sysctl -w net.ipv4.ip_forward=1
```
- IPv6 forwarding:
```
sudo sysctl -w net.ipv6.conf.all.forwarding=1
```
To manage containerized workloads, install fuse-overlayfs with:
```
sudo yum install fuse-overlayfs
```
The VM must have access to the source system’s secret manager to retrieve secrets. For more information, see how to provide access for some popular secret managers listed below:
- AWS: Configure access for AWS Secrets Manager.
- Azure: Configure access for Azure Key Vault.
- GCP: Configure access for GCP Secret Manager.

Permissions required

Before installing the Secure Agent, the user must have the following permissions:

Create and modify directories in the user’s home directory: ~/.config/systemd/user, ~/bin, ~/.local/bin, and ~/.rancher.
Create and write log files.
Execute standard Linux commands: mkdir, chmod, tar, and sed.

Download Agent packages

Follow these steps to download the necessary packages for setting up the Secure Agent.

💪 Did you know? The steps require Internet access to download files. In case the VM has no Internet connectivity, one can download them separately and copy the files to the VM.

Create a folder for deployment and navigate to it:

mkdir -p atlan-secure-agent && cd atlan-secure-agent

Run the following commands to download the required packages:

Download the Kubernetes install package, which contains files to run K3s on an air-gapped VM:

curl -O https://atlan-public.s3.amazonaws.com/workflow-offline-agent/container/k3s_offline_package_main.tar

Download the Container images package if an image registry isn't available:

curl -O https://atlan-public.s3.amazonaws.com/workflow-offline-agent/container/atlan_images_main.tar

Download the Secure Agent install package, which contains files for running the Secure Agent:

curl -O https://atlan-public.s3.amazonaws.com/workflow-offline-agent/container/atlan_install_config_main.tar.gz

Verify that all the files are downloaded.