Install the Alation Agent

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Important

You are viewing documentation for Classic Alation.

Installing the Alation Agent (Agent) involves the following steps:

• Step 1: Prepare for the Installation

• Step 2: Download and Run Installation Script

• Step 3: Name Your Agent

• Step 4: Generate Encryption Certificates

• Step 5: Install the Authentication Service Add-on (Optional)

These steps are described in detail below. You will be switching back and forth between Alation and the Agent’s host machine to complete the installation. You’ll use information provided in Alation to run commands on the Agent machine, and you’ll sometimes copy the output of those commands back into Alation.

You can install multiple Agents, each on its own machine, and connect them all with Alation Cloud Service. This may be needed if you have data sources in different geographical locations, network segments, or security zones.

Step 1: Prepare for the Installation

Before you can install the Agent, you must:

1. Make sure you have the Server Admin role in Alation.

2. Provision a Linux host to install the Agent on.

   • Check the System Requirements for the required hardware and software.

   • The Agent’s host can be a physical or virtual machine. A virtual machine can be set up in a shared server environment, as long as the system requirements are met.

   • The Agent machine should be located appropriately within your network so that it can access the relevant data sources.

   • Don’t run other software on the Agent machine—only the Agent should be installed.

3. Ensure that outbound port 443 is open.

4. Check that the Agent host machine can resolve the Agent connectivity endpoint for your region from the table below.

   Geography	Location	Agent Connectivity Endpoint
   Africa, Europe, & Middle East	Frankfurt	ocf.euc1.eu.alationcloud.com
   	Dublin	ocf.euw1.eu.alationcloud.com
   Americas	Montreal	ocf.cac1.ca.alationcloud.com
   	Virginia	ocf.use1.alationcloud.com
   	Oregon	ocf.usw2.alationcloud.com
   Asia Pacific	Mumbai	ocf.aps1.ap.alationcloud.com
   	Singapore	ocf.apse1.ap.alationcloud.com
   	Sydney	ocf.apse2.ap.alationcloud.com
   	Tokyo	ocf.apne1.ap.alationcloud.com

   You will need to make sure you have SSH credentials to the Agent machine and that it has outbound access to the open internet. If you do not want the Agent to have outbound access to the open internet, you may use a proxy server. In that case you will need to whitelist the Agent connectivity endpoint on your proxy server to allow the Agent machine outbound access to Alation Cloud Service.

   Note

   If your proxy server is a TLS middlebox, additional steps are required. Contact Alation Support for more information.

   Then you can use a tool such as dig or nslookup to see if you can reach your Agent connectivity endpoint. For example:

   dig <your-agent-connectivity-endpoint>
   

   If your Agent connectivity endpoint is reachable, the output of the dig command should include something like this:

   ;; ANSWER SECTION:
   <your-agent-connectivity-endpoint>. 60 IN A <alation-cloud-IP>
   

   If your Agent connectivity endpoint is not reachable, you will need to configure your network to correctly resolve it.

5. Make sure you have access to the Customer Portal so you can download the Agent and connector installation packages. If you don’t have access, contact Alation Support.

6. Optionally, contact Alation Support to request the Authentication Service add-on. The Authentication Service add-on enables the Agent to integrate directly with AWS Secrets Manager, so your data source credentials never leave your network. For information about how this integration works, see Integration with AWS Secrets Manager for Data Source Authentication Using OCF Connector.

   To use this feature, you must meet the following requirements:

   • You must be an Alation Cloud Service customer on the cloud-native architecture.

   • You must be using Alation Agent version 1.7.2.4360 or later. For help installing the Alation Agent, see Install the Alation Agent.

   • To access AWS Secrets Manager using an IAM instance profile:

     • You must be on Alation Cloud Service version 2024.1.4 or later.

     • Your Alation Agent must be installed on an Amazon EC2 instance.

     • You must install Authentication Service Add-on version 5.14.0.1882 or later on the Alation Agent.

   • To access AWS Secrets Manager using an IAM user’s credentials:

     • You must be on Alation Cloud Service version 2024.1.5 or later.

     • You must install Authentication Service Add-on version 5.14.0.1968 or later on the Alation Agent.

   • You must have a supporting OCF connector installed on the Agent. To find out if a specific connector supports this feature, see the documentation for the specific connector in the Open Connector Framework section.

     Note

     You can use the Native Data Sources API to migrate a data source from an OCF connector that’s not on an Alation Agent to an OCF connector that is on an Alation Agent.

Step 2: Download and Run Installation Script

You’re now ready to download the software package and run the installation script. You must have the Server Admin role in Alation to complete the remaining steps.

1. Click on the Settings icon in the top right corner.

   

2. The Admin Settings page appears. Under the Platform Settings section, click Agents.

   Under the Server Admin section, click Manage Connectors. Then click the Agents tab. The Agents Dashboard appears.

3. Click the Add New Agent button. The Add New Agent dialog will appear.

4. In the Add New Agent dialog, click the download the package link to open the Alation Customer Portal.

   

5. In the Alation Customer Portal, select the latest available version for the desired operating system:

   • RHEL for Red Hat-based systems

   • DEBIAN for Debian-based systems

   

   The Agent will download to your computer as a tar.gz file named ocf-agent-<agent-version>-<operating-system>.tar.gz.

6. If needed, transfer the downloaded file to the Agent’s host machine. For example, if you downloaded the Agent file to a Unix-based machine, you could transfer the file using the scp command in Terminal:

   scp /local/path/to/ocf-agent-<agent-version>-<operating-system>.tar.gz <ssh-user>@<server-address>:/remote/path/to/ocf-agent
   

7. On the Agent’s host machine, extract the .tar.gz file. Example:

   tar -xf ocf-agent-<agent-version>-<operating-system>.tar.gz
   

   The Agent installation files are extracted into an ocf-agent directory.

8. Change into the ocf-agent directory.

   cd ocf-agent
   

9. In Alation, copy the relevant installation command from the Install Agent screen.

   

10. In the terminal on the Agent’s host machine, make sure you are in the ocf-agent directory, then paste and run the installation command. This will install and configure the Agent.

11. (Optional) If your network routes outgoing traffic through an HTTP CONNECT proxy, see the Advanced Configuration section below.

12. In Alation, click the Next button.

You have now installed and configured the Agent on a machine inside your network. Next you’ll need to name the Agent in Alation.

Advanced Configuration

If your network routes outgoing traffic through an HTTP CONNECT proxy, you need to:

• Add the Alation Cloud Service connectivity endpoint to your proxy server’s allow list.

• Add the proxy’s address to the Agent configuration file.

Proxy Allow List

You will need to add the Alation Cloud Service connectivity endpoint to your proxy server’s allow list so the Agent can reach your Alation Cloud Service instance.

The Alation Cloud Service endpoint is shown on the address line of the Agent installation command. This is the same address that should be in your Agent configuration file at /etc/hydra/hydra.toml.

Add Proxy Address to Agent Config

This is done on the Agent’s host machine. The steps depend on whether your proxy requires authentication.

• No Authentication

  For proxies that don’t require authentication, edit /etc/hydra/hydra.toml to add the following line:

  web_proxy = "<proxy-address>:<proxy-port>"
  

• Basic Authentication

  Starting with Agent version 1.2.1.1168, you can route the Agent through proxies that require basic authentication. Edit /etc/hydra/hydra.toml to add the following line:

  web_proxy = "<username>:<password>@<proxy-address>:<proxy-port>"
  

  Replace the parts in angle brackets with the appropriate information for your proxy. Don’t include the angle brackets. Do include the quotes. The proxy address can be a domain name or an IP address. If no port is provided, the Agent defaults to port 80.

  Here’s an example with basic authentication:

  web_proxy = "jane:[email protected]:3128"
  

Step 3: Name Your Agent

1. In Alation, enter a name for the Agent. This name can’t be changed, so choose carefully.

   

   Note

   The Agent’s name is used to identify connectors that you install on this Agent. When you install a new connector or add a new data source and link it to your Agent, you’ll see the Agent name added to the end of the connector name.

2. (Optional) Enter a description of the Agent. This appears on the Agent’s detail page. The description can’t be changed later.

3. Click the Next button, then confirm the name you chose.

Now that you’ve named the Agent, it’s time to establish the secure connection between your Alation Cloud Service instance and the Agent.

Note

After starting the Add Agent workflow you can always close the Add New Agent dialog. You can pick it back up again at a later time by returning to the Agent Dashboard and clicking on the Complete Setup link.

Step 4: Generate Encryption Certificates

Alation uses signed certificates to encrypt the communication between Alation and the Agent.

1. On the Generate Certificate Signing Request (CSR) screen, copy the provided command and run it on the Agent’s host machine.

   sudo kratos certs gen
   

   The command will generate a certificate signing request. Example output:

   -----BEGIN CERTIFICATE REQUEST-----
   <your certificate signing request>
   -----END CERTIFICATE REQUEST-----
   

2. Copy the certificate signing request from the Agent machine, including the dashes.

3. In Alation, paste the certificate signing request into the provided box under Certificate Signing Request Output. Then click the Next button.

   

4. Alation will generate two signed certificates—one for the Agent and one root certificate. Copy the provided certificate installation command.

   

5. On the Agent’s host machine, paste the copied certificate command and run it. This installs the certificate.

   Warning

   The certificates will automatically expire after one year.

6. Restart the Agent by copying the provided command and running it on the Agent’s host machine.

   sudo systemctl restart hydra
   

7. When the Agent has finished restarting, click the Finish button in Alation. Check that your Agent has a status of Connected in the Agent Dashboard. If it doesn’t, check the Troubleshooting page.

If the installation was successful, you can now install connectors on your Agent.

Step 5: Install the Authentication Service Add-on (Optional)

If you would like to enable the Alation Agent to integrate directly with AWS Secrets Manager when authenticating requests to your data source, you can install the Authentication Service add-on.

To use this feature, you must meet the following requirements:

• You must be an Alation Cloud Service customer on the cloud-native architecture.

• You must be using Alation Agent version 1.7.2.4360 or later. For help installing the Alation Agent, see Install the Alation Agent.

• To access AWS Secrets Manager using an IAM instance profile:

  • You must be on Alation Cloud Service version 2024.1.4 or later.

  • Your Alation Agent must be installed on an Amazon EC2 instance.

  • You must install Authentication Service Add-on version 5.14.0.1882 or later on the Alation Agent.

• To access AWS Secrets Manager using an IAM user’s credentials:

  • You must be on Alation Cloud Service version 2024.1.5 or later.

  • You must install Authentication Service Add-on version 5.14.0.1968 or later on the Alation Agent.

• You must have a supporting OCF connector installed on the Agent. To find out if a specific connector supports this feature, see the documentation for the specific connector in the Open Connector Framework section.

  Note

  You can use the Native Data Sources API to migrate a data source from an OCF connector that’s not on an Alation Agent to an OCF connector that is on an Alation Agent.

To install or update the Authentication Service add-on on an Alation Agent:

1. If you don’t have the latest plugin yet, contact Alation Support to request it. The plugin is a Docker image named auth-service-docker-image-<plugin-version>tar.gz.

2. If needed, transfer the downloaded file to the Agent’s host machine. For example, if you downloaded the plugin file to a Unix-based machine, you could transfer the file using the scp command in Terminal:

   scp /local/path/to/auth-service-docker-image-<plugin-version>.tar.gz <ssh-user>@<server-address>:/remote/path/to/agent
   

3. On the Agent’s host machine, unzip the .tar.gz file. Example:

   gzip -d auth-service-docker-image-<plugin-version>.tar.gz
   

4. Install or update the plugin. To install the plugin from scratch, use this command:

   sudo kratos addons install auth ./auth-service-docker-image-<plugin-version>.tar
   

   To update the plugin, use this command:

   sudo kratos addons update auth ./auth-service-docker-image-<plugin-version>.tar
   

5. Restart the Agent:

   sudo systemctl restart hydra
   

6. Check that the plugin is running. It may take about two minutes for the plugin to start up.

   sudo docker ps
   

   In the output of this command, you should see auth listed under IMAGE, and under STATUS it should indicate that the plugin is Up. For example:

   CONTAINER ID   IMAGE                 COMMAND                  CREATED          STATUS                             PORTS                                           NAMES
   00d929b2582b   auth                  "java -Dlog4j.config…"   11 seconds ago   Up 10 seconds                      0.0.0.0:11001->11001/tcp, :::11001->11001/tcp   auth
   f80e23b27e2a   application_gateway   "/opt/cag"               11 seconds ago   Up 10 seconds (health: starting)                                                   cag
   c8c16128644e   proxy                 "/opt/reverseProxy"      12 seconds ago   Up 11 seconds (health: starting)                                                   proxy
   8c3d5cfeb3fd   connector_21          "/opt/entrypoint.sh …"   12 seconds ago   Up 12 seconds (health: starting)   127.0.0.1:10021->10021/tcp                      connector21
   c8814bcadc3c   agent                 "/opt/agent"             13 seconds ago   Up 12 seconds (health: starting)   127.0.0.1:8080->8080/tcp                        agent
   

The Authentication Service add-on has now been installed. To troubleshoot the Agent or Authentication Service add-on, see Troubleshoot the Agent.

See Integration with AWS Secrets Manager for Data Source Authentication Using OCF Connector for information on different ways to integrate with AWS Secrets Manager, along with detailed instructions.