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

You install the Query Service Add-on from Alation Cloud Service after the Agent is installed and connected. If you’re setting up a new Agent that will use Zero Data, you must first prepare the Agent host with the K3s-based Zero Data runtime by passing the --zerodata flag to the Agent install script. See Prepare the Agent Host for Zero Data for that step.

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.

  • Your Agent host must run a supported operating system for Zero Data. The k3s-based Zero Data package isn’t available on Debian-based hosts or rootless installations. See the Query Service Compatibility section for the full support matrix.

  • 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.

Prepare the Agent Host for Zero Data

The --zerodata flag on the Agent install script prepares the host for Zero Data by installing the K3s-based runtime that the Query Service Add-on depends on. It does not install the Query Service itself; you still install the add-on from Alation Cloud Service after the Agent is connected (see Install the Query Service Add-on from Alation Cloud Service).

When you pass --zerodata, the installer adds the K3s-based zerodata package alongside the standard ocf-agent package, instead of the default alation-container-service package. The zerodata package provides the K3s runtime that Zero Data depends on, including the proxy pod that handles connector traffic. K3s also brings up its bundled Traefik ingress controller in the kube-system namespace as part of its standard runtime. The JWT gateway pod that authenticates incoming Zero Data requests, and the Traefik IngressRoute (a Traefik custom resource, not a pod) that tells the Traefik controller how to route browser traffic to it, are not deployed by the installer alone – they come up only after you add the [ingress] section to hydra.toml in Configure Zero Data Ingress.

To prepare a new Agent host for Zero Data:

  1. Follow Step 1: Prepare for the Installation in Install the Alation Agent to provision the host and verify network connectivity.

  2. Download and extract the installation package as described in Step 2: Download and Run Installation Script.

  3. On the Agent host, run the installation script with the --zerodata flag:

    sudo ./install.sh --zerodata

    The script installs both the ocf-agent package and the zerodata package using your platform’s package manager (yum, dnf, or apt).

    Note

    Run ./install.sh --help to see all available options. By default (without --zerodata), the script installs the Agent without the Zero Data runtime.

  4. Complete the rest of the Agent setup steps in Install the Alation Agent – name the Agent and generate the TLS certificates for the Agent-to-Alation connection.

  5. Configure Zero Data ingress in hydra.toml. See Configure Zero Data Ingress for the hostname, certificate, and key fields you need to provide. The jwtgateway pod and the Traefik IngressRoute deploy after this step.

  6. After the Agent is connected and ingress is configured, verify the Zero Data runtime is up:

    sudo k3s kubectl get pods -A

    You should see the following pods in the Running state:

    • proxy (in the Agent’s namespace) – handles connector traffic. Comes from the zerodata package.

    • jwtgateway (in the Agent’s namespace) – authenticates incoming Zero Data requests. Deployed once you add the [ingress] section to hydra.toml.

    • traefik (in the kube-system namespace) – the K3s-bundled Traefik ingress controller. K3s brings this up automatically as part of its runtime; it serves the IngressRoute that the chart deploys.

  7. Install the Query Service Add-on from Alation Cloud Service. See Install the Query Service Add-on from Alation Cloud Service below.

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.

Switch an Existing Agent to Zero Data

If you already have an Alation Agent installed without Zero Data and want to switch it to a Zero Data-based Agent, follow these steps. This procedure adds the zerodata package alongside the existing alation-container-service package on the Agent host. After the switch, when the Agent restarts it detects that K3s is available and deploys to it; K3s takes precedence even if Docker is also installed.

Note

This is a runtime change to the Agent host: the Agent stops using the container-based runtime and starts using the k3s-based runtime on the next restart. Plan a maintenance window. Connectors, data sources, and the catalog are unaffected – only the Agent host’s local runtime changes.

Prerequisites for Switching

  • Confirm that the Agent host meets the requirements in the Query Service Compatibility section. The k3s-based Zero Data package isn’t available for Debian or rootless installations; if your existing Agent runs on either, you must move the Agent to a supported host instead of switching it in place.

  • Verify that all Prerequisites for the Query Service Add-on are met (Cloud Service version, Agent version, object store, ingress hostname, TLS certificate, and network access).

  • Run a metadata extraction job and confirm it completes successfully so you have a known-good baseline.

  • Note the Agent name and any custom configuration in /etc/hydra/hydra.toml so you can reapply it after the switch.

Switch the Agent in Place

  1. Make a backup copy of the Agent configuration file:

    sudo cp /etc/hydra/hydra.toml /etc/hydra/hydra.toml.backup

  2. Stop the Agent:

    sudo systemctl stop hydra

  3. Download the latest Agent installation package from the Alation Customer Portal, choosing the RHEL package. (Debian-based hosts aren’t supported for Zero Data; see the Query Service Compatibility section.) Transfer and extract the package on the Agent host as described in Install the Alation Agent.

  4. From the extracted ocf-agent directory, run the installer with the --zerodata flag:

    cd ocf-agent
sudo ./install.sh --zerodata

    The installer adds the zerodata package, which provides the K3s runtime. The ocf-agent package is upgraded in place. Existing connector configurations and the Agent’s TLS certificate are preserved. On the next restart, the Agent detects that K3s is available and deploys to it.

  5. Restore your custom configuration. Edit /etc/hydra/hydra.toml and add the [ingress] section described in Configure Zero Data Ingress:

    sudo $EDITOR /etc/hydra/hydra.toml

  6. Start the Agent:

    sudo systemctl restart hydra

  7. Validate the switch:

    1. Confirm the k3s pods are running:

      sudo k3s kubectl get pods -A

      You should see the following pods in the Running state:

      • proxy (in the Agent’s namespace) – handles connector traffic. Comes from the zerodata package.

      • jwtgateway (in the Agent’s namespace) – authenticates incoming Zero Data requests. Deployed once you add the [ingress] section to hydra.toml.

      • traefik (in the kube-system namespace) – the K3s-bundled Traefik ingress controller. K3s brings this up automatically as part of its runtime; it serves the IngressRoute that the chart deploys.

    2. In Alation, go to Admin Settings > Agents and verify the Agent shows as Connected with the Query Service status set to Connected.

    3. Run the unauthenticated ping endpoint from a user network:

      curl https://zerodata.yourcompany.com/_ping

      A successful response confirms the ingress is reachable.

    4. Run an existing connector’s metadata extraction job to confirm baseline functionality. Then run a Compose query against a data source you’ve configured for Zero Data to confirm Zero Data is working end-to-end.

If validation fails, see Troubleshoot the Query Service Add-on for diagnostic steps.

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:

  1. Register a domain name for the Agent

  2. Obtain a TLS certificate

  3. Copy the certificate and key to the Agent

  4. Update hydra.toml with the ingress configuration

  5. Verify the ingress

Each step is described below.

Register a domain name for the Agent

Choose a DNS name that you control and that the user’s browser can resolve. For example, zerodata.yourcompany.com. Create an A (or CNAME) record in your DNS provider that points the name to the Agent host’s IP address. For internal-only deployments, the name can resolve through your organization’s split-horizon DNS, as long as user browsers can resolve it.

The name doesn’t have to be public. It must, however, match the Common Name (CN) or a Subject Alternative Name (SAN) on the TLS certificate you provide in the next step, or browsers will reject the connection.

For step-by-step DNS provider examples, see your registrar’s documentation:

Obtain a TLS certificate

You need a TLS certificate and private key for the ingress hostname. The certificate must be:

  • Valid for the hostname you registered (Common Name or Subject Alternative Name).

  • Trusted by the user’s browser. Self-signed certificates work only if the signing CA is trusted by all users’ browsers; we recommend a certificate issued by a trusted public or internal CA instead.

  • In PEM format. If you receive the certificate in another format, convert it with openssl.

Acceptable sources include:

  • A public CA such as Let’s Encrypt, DigiCert, or Sectigo.

  • An internal enterprise CA, such as Microsoft AD CS or HashiCorp Vault PKI.

  • A cloud-managed certificate authority that exports a usable PEM (for example, AWS ACM with the Export option for private CAs).

The certificate must not be the same certificate the Agent uses for its outbound connection to Alation Cloud Service (the one generated by sudo kratos certs gen). The Zero Data ingress certificate is presented to user browsers and is unrelated to the Agent’s mTLS connection to Alation.

If you need to generate a CSR for an internal CA on the Agent host, you can use openssl:

openssl req -new -newkey rsa:2048 -nodes \
  -keyout /tmp/ingress-key.pem \
  -out /tmp/ingress.csr \
  -subj "/CN=zerodata.yourcompany.com"

Submit /tmp/ingress.csr to your CA. When you receive the signed certificate, save it as /tmp/ingress-cert.pem. If your CA returns a separate intermediate or chain, concatenate the issued certificate first and the chain after, in PEM order.

The openssl example above is starter guidance. Consult your chosen certificate authority for the precise requirements on generating a certificate signing request that complies with your organization’s policies (key algorithm and length, required extensions, subject and SAN formatting, and so on).

Copy the certificate and key to the Agent

Place the certificate and key in a stable location on the Agent host. We recommend /etc/hydra/certs/:

sudo mkdir -p /etc/hydra/certs
sudo cp ingress-cert.pem /etc/hydra/certs/ingress-cert.pem
sudo cp ingress-key.pem /etc/hydra/certs/ingress-key.pem

Set restrictive permissions on the private key so only root can read it:

sudo chown root:root /etc/hydra/certs/ingress-*.pem
sudo chmod 644 /etc/hydra/certs/ingress-cert.pem
sudo chmod 600 /etc/hydra/certs/ingress-key.pem

Update hydra.toml with the ingress configuration

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 so the new settings take effect:

sudo systemctl restart hydra

Verify the ingress

Confirm the ingress is working before exposing it to users:

  1. Confirm the DNS name resolves to the Agent machine from the user’s network. From a user-facing host, run:

    dig zerodata.yourcompany.com

    The answer section should show the Agent’s IP address.

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

  3. Confirm the TLS certificate is valid and trusted by the user’s browser (not self-signed, or the CA is trusted). Test with curl from a representative user network:

    curl -v https://zerodata.yourcompany.com/_ping

    A 200 OK response confirms the ingress is reachable and the certificate chain is accepted. If you see certificate errors, re-issue the certificate so it includes the full chain, or install the issuing CA in the user’s browser trust store.

If verification fails, see Troubleshoot the Query Service Add-on for diagnostic steps.

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.