Manage the Query Service Add-on

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Important

You are viewing documentation for Alation’s Classic User Experience.

This topic describes how to install, upgrade, monitor, and remove the Query Service Add-on for the Alation Agent.

Install the Query Service Add-on

Install the Query Service Add-on from Alation Cloud Service.

Prerequisites

To use the Query Service Add-on, you must meet the following requirements:

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

  • You must have Alation Agent version 1.9.0 or later installed and connected. We recommend using the latest available version of the Agent.

  • You must have a supported object store bucket prepared:

  • You must configure the Agent with an ingress hostname, TLS certificate, and TLS private key for the Zero Data gateway. The hostname is a DNS name of your choosing (for example, zerodata.yourcompany.com) that resolves to the Agent machine. See Configure Zero Data Ingress below.

  • The user’s browser must be able to reach the Agent’s Zero Data ingress endpoint directly. This is different from the standard Agent-to-Alation Cloud Service connection, which is outbound only. See Alation’s IP Addresses for Allow Lists for details on the network requirements for Zero Data.

Install the Query Service Add-on from Alation Cloud Service

To install the Query Service Add-on from Alation Cloud Service:

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

    ../../../_images/TopNavigationBar_Gear_Neo.png ../../../_images/TopNavigationBar_Gear.png

  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.

  1. To the right of the Agent name, click the Actions button, then select Install Query Service. If the option doesn’t appear, the add-on is already installed.

  2. In the configuration wizard, select your object store provider:

    • AWS S3 – Enter the bucket name, AWS region, and IAM role ARN or managed resource ARN.

    • Azure Blob Storage – Enter the storage account name, container name, and OIDC federated credential details.

  3. Click Install. A success message appears when the installation completes.

Upgrade the Query Service Add-on

Upgrade the Query Service Add-on from Alation Cloud Service.

Upgrade the Query Service Add-on from Alation Cloud Service

Upgrading the Query Service Add-on from Alation Cloud Service always uses the latest version of the add-on.

To check which version is currently installed:

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

    ../../../_images/TopNavigationBar_Gear_Neo.png ../../../_images/TopNavigationBar_Gear.png

  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.

  1. Click the Agent name. The Agent detail view opens. Under Query Service, the version number appears. If a newer version is available, Upgrade Available appears next to the version number.

To upgrade the Query Service Add-on from Alation Cloud Service:

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

    ../../../_images/TopNavigationBar_Gear_Neo.png ../../../_images/TopNavigationBar_Gear.png

  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.

  1. To the right of the Agent name, click the Actions button, then select Upgrade Query Service. If the option is disabled, the latest version is already installed.

  2. In the confirmation dialog, click Upgrade. A success message appears when the upgrade completes.

Remove the Query Service Add-on

To remove the Query Service Add-on:

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

    ../../../_images/TopNavigationBar_Gear_Neo.png ../../../_images/TopNavigationBar_Gear.png

  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.

  1. To the right of the Agent name, click the Actions button, then select Remove Query Service. If the option doesn’t appear, the add-on isn’t installed.

  2. In the confirmation dialog, click Continue Removal. A success message appears when the removal completes.

After removal, Compose, sampling, and profiling for data sources that used the Query Service Add-on are no longer available. Export and download functionality for query results is also unavailable.

Check the Query Service Add-on Status

To check the status from Alation Cloud Service:

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

    ../../../_images/TopNavigationBar_Gear_Neo.png ../../../_images/TopNavigationBar_Gear.png

  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.

  1. Click the Agent name. The Agent detail view opens. Under Query Service, the status appears. The status can be one of the following:

    • Connected – The Query Service is running

    • Disconnected – The Query Service is installed but not running

    • Unknown – Alation can’t retrieve the Query Service status

Configure Zero Data Ingress

The Zero Data feature requires the Agent to be reachable from the user’s browser. To enable this, you must configure the Agent with an ingress hostname, TLS certificate, and TLS private key.

The ingress hostname is a DNS name of your choosing that resolves to the Agent machine. For example, zerodata.yourcompany.com. You must also provide a TLS certificate and private key for this hostname so the connection is encrypted.

To configure the ingress, edit the Agent configuration file at /etc/hydra/hydra.toml on the Agent machine and add the following section:

[ingress]
hostname = "zerodata.yourcompany.com"
certificate_path = "/etc/hydra/certs/ingress-cert.pem"
key_path = "/etc/hydra/certs/ingress-key.pem"

Replace the values with your actual hostname and certificate paths. You must provide all three fields (hostname, certificate_path, and key_path) together. If any field is missing, the system won’t enable the ingress.

After updating the configuration, restart the Agent:

sudo systemctl restart hydra

Ensure that:

  • The DNS name resolves to the Agent machine from the user’s network.

  • Inbound HTTPS traffic (port 443) is allowed through any firewalls or security groups between the user’s browser and the Agent machine.

  • The TLS certificate is valid and trusted by the user’s browser (not self-signed, or the CA is trusted).

Configure Bucket Lifecycle Policy

The object store bucket used by the Query Service Add-on stores query results with different retention needs depending on the type of operation:

  • Compose query results – Recommended retention of 7 days. Compose results are intended for short-term use. Re-execute them if needed.

  • Sampling and profiling results – Retain for a longer configurable period depending on your organization’s requirements.

Configure lifecycle rules on your bucket to automatically delete expired objects.

AWS S3 Lifecycle Policy

To configure a lifecycle policy on your S3 bucket:

  1. Open the Amazon S3 console and navigate to your bucket.

  2. Click the Management tab, then click Create lifecycle rule.

  3. Create a rule with the following settings:

    • Rule name: For example, zero-data-compose-cleanup

    • Prefix filter: query/ (the prefix the Query Service uses for Compose query results)

    • Lifecycle rule actions: Select Expire current versions of objects

    • Days after object creation: 7

  4. Create separate rules for sampling and profiling results with longer retention periods as needed:

    • Sampling results prefix: sampling/

    • Profiling results prefix: profiling/

For more information, see the Amazon S3 Lifecycle Configuration documentation.

Azure Blob Storage Lifecycle Policy

To configure a lifecycle management policy on your Azure Blob Storage container:

  1. Open the Azure portal and navigate to your storage account.

  2. Under Data management, click Lifecycle management, then click Add a rule.

  3. Create a rule with the following settings:

    • Rule name: For example, zero-data-compose-cleanup

    • Rule scope: Apply rule to all blobs, or apply filters based on your blob prefix.

    • Blob type: Block blobs

    • Delete the blob if: Last modified more than 7 days ago

  4. Create a separate rule for sampling and profiling results with a longer retention period as needed.

For more information, see the Azure Blob Storage lifecycle management documentation.

Bucket Security Requirements

AWS S3

The S3 bucket used for Zero Data must meet the following security requirements:

  • IAM policy – The IAM role or user for the Query Service must have s3:PutObject, s3:GetObject, s3:DeleteObject, and s3:ListBucket permissions on the bucket.

  • Encryption – Enable server-side encryption on the bucket (SSE-S3 or SSE-KMS).

  • Access control – Block public access. Use the S3 Block Public Access settings to prevent any public access.

Azure Blob Storage

The Azure Blob Storage container used for Zero Data must meet the following security requirements:

  • OIDC federated credential – The Query Service authenticates using an OIDC federated credential. Configure the federated credential in your Microsoft Entra ID (formerly Azure AD) application registration.

  • Encryption – Enable Azure Storage Service Encryption (SSE) on the storage account.

  • Access control – Disable public access on the storage account. Use Azure RBAC to manage access.