From 805c98b00d63b81404067e5b3a87c87ec44ce0bc Mon Sep 17 00:00:00 2001 From: Rafael Riki Ogawa Osiro Date: Thu, 21 May 2026 18:30:16 -0300 Subject: [PATCH 1/2] docs(deployments): document Postgres fork support, schema config, and Snowflake CSID - Self-hosted deployment: add "Database Configuration (Optional)" section covering PostgreSQL fork compatibility (EPAS, Yugabyte, Aurora, Greenplum) and the POSTGRES_SCHEMA environment variable for custom schema layouts. - Snowflake datastore: add "Identifying Qualytics in Snowflake" section describing the application=Qualytics JDBC parameter that surfaces under Snowflake's Client Application monitoring views. - Polish: remove em-dashes, align placeholders (your-company.qualytics.io), and replace internal jargon with clearer wording. --- docs/deployments/self-hosted-deployment.md | 54 +++++++++++-------- .../add-datastores/snowflake.md | 8 ++- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/docs/deployments/self-hosted-deployment.md b/docs/deployments/self-hosted-deployment.md index a14cd82ce9..7fc2834384 100644 --- a/docs/deployments/self-hosted-deployment.md +++ b/docs/deployments/self-hosted-deployment.md @@ -3,7 +3,7 @@ This guide walks you through deploying the Qualytics platform on your own infrastructure using a Self-Hosted Kubernetes cluster. !!! info "Deployment Model" - This guide covers the **Self-Hosted Deployment** model — where Qualytics runs on your own Kubernetes infrastructure (including on-premises). If you are a Managed customer, your deployment is fully operated by Qualytics and you do not need this guide. + This guide covers the **Self-Hosted Deployment** model, where Qualytics runs on your own Kubernetes infrastructure (including on-premises). If you are a Managed customer, your deployment is fully operated by Qualytics and you do not need this guide. ## Deployment Overview @@ -106,11 +106,11 @@ global: dnsRecord: "your-company.qualytics.io" # or your custom domain ``` -**Authentication** — choose one of the following: +**Authentication** (choose one of the following): === "OIDC (Recommended)" - Only 4 values needed — scopes, claim mappings, and endpoints all use sensible defaults. See the [OIDC Configuration Guide](oidc-configuration.md) for advanced options. + Only 4 values are needed. Scopes, claim mappings, and endpoints all use sensible defaults. See the [OIDC Configuration Guide](oidc-configuration.md) for advanced options. ```yaml global: @@ -161,10 +161,22 @@ secrets: - Enable `nginx` if you need an ingress controller - Enable `certmanager` for automatic SSL certificates -- Configure SMTP for email notifications, invitations, and password resets — see the [SMTP Configuration Guide](smtp-configuration.md) +- Configure SMTP for email notifications, invitations, and password resets. See the [SMTP Configuration Guide](smtp-configuration.md) for details. For the full list of available options, refer to `charts/qualytics/values.yaml` in the Helm chart. +### Database Configuration (Optional) + +Two control-plane database options are available for self-hosted deployments: + +**PostgreSQL fork compatibility** + +The control plane supports stock PostgreSQL and common forks, including **EDB Postgres Advanced Server (EPAS)**, **Yugabyte**, **Aurora**, and **Greenplum**, without extra configuration. Compatibility shims (such as quoting the `partition` keyword required by EPAS) are applied to both runtime queries and Alembic migrations. + +**Custom PostgreSQL schema** + +The control plane reads the `POSTGRES_SCHEMA` environment variable (default `public`) to decide where its tables live. Alembic migrations automatically run `CREATE SCHEMA IF NOT EXISTS` and set the session `search_path`, so no manual schema creation is required. Set this variable through your Helm values when sharing one PostgreSQL instance across multiple Qualytics environments or when matching internal naming conventions. + ### Deploy ```bash @@ -189,11 +201,11 @@ Qualytics supports two authentication modes for self-hosted deployments: | Mode | Recommended For | Details | |------|----------------|---------| -| **OIDC** (Recommended) | Air-gapped or standard self-hosted deployments | Integrates directly with your enterprise IdP — no external dependencies | -| **Auth0** | Deployments with internet access | Managed by Qualytics — simpler setup but requires egress to `auth.qualytics.io` | +| **OIDC** (Recommended) | Air-gapped or standard self-hosted deployments | Integrates directly with your enterprise IdP, with no external dependencies | +| **Auth0** | Deployments with internet access | Managed by Qualytics. Simpler setup but requires egress to `auth.qualytics.io` | -- **[OIDC Configuration Guide](oidc-configuration.md)** — Step-by-step instructions for configuring OIDC with your Identity Provider -- **[Auth0 Setup Guide](auth0-setup.md)** — How to request and configure Auth0 for your self-hosted deployment +- **[OIDC Configuration Guide](oidc-configuration.md)**: step-by-step instructions for configuring OIDC with your Identity Provider. +- **[Auth0 Setup Guide](auth0-setup.md)**: how to request and configure Auth0 for your self-hosted deployment. ## Step 5: Configure DNS & SSL @@ -225,23 +237,23 @@ If using your own domain: ## Step 6: Verify Deployment -1. **Access the UI** — Navigate to your configured domain (e.g., `https://acme.qualytics.io`) in a browser -2. **Test authentication** — Log in using your configured authentication method (OIDC or Auth0) -3. **Check pod health** — Verify all pods are running: +1. **Access the UI.** Navigate to your configured domain (e.g., `https://acme.qualytics.io`) in a browser. +2. **Test authentication.** Log in using your configured authentication method (OIDC or Auth0). +3. **Check pod health.** Verify all pods are running: ```bash kubectl get pods -n qualytics ``` -4. **Check API health** — Verify the API is responding: +4. **Check API health.** Verify the API is responding: ```bash - curl -s https://your-domain.qualytics.io/api/health + curl -s https://your-company.qualytics.io/api/health ``` ## Step 7: Activate Your License -Self-hosted deployments require a valid license. A **31-day grace period** starts automatically when you create your first datastore connection — during this time, the platform is fully functional without a license. A warning banner on the **Settings > Status** page counts down the remaining days. +Self-hosted deployments require a valid license. A **31-day grace period** starts automatically when you create your first datastore connection. During this time, the platform is fully functional without a license. A warning banner on the **Settings > Status** page counts down the remaining days. !!! warning "Activate before the grace period ends" If the grace period expires without a valid license, **dataplane operations** (scanning, profiling, enrichment) are blocked. The UI remains accessible so admins can apply a license. @@ -249,25 +261,25 @@ Self-hosted deployments require a valid license. A **31-day grace period** start ### Requesting a License 1. Navigate to **Settings > Status** (requires **Admin** or **Manager** role) -2. Click **Generate License Request** — this creates an encoded fingerprint of your deployment -3. Copy the request string and send it to your [Qualytics account manager](mailto:hello@qualytics.ai) via a secure channel (e.g., [Bitwarden Send](https://bitwarden.com/products/send/) — never plain email) +2. Click **Generate License Request**. This creates a signed request that uniquely identifies your deployment +3. Copy the request string and send it to your [Qualytics account manager](mailto:hello@qualytics.ai) via a secure channel (e.g., [Bitwarden Send](https://bitwarden.com/products/send/); never plain email) 4. Qualytics signs the request and returns a license key ### Applying a License 1. In **Settings > Status**, click **Update License** 2. Paste the signed license key and submit -3. The license is now active — the expiration date displays on the Status page +3. The license is now active. The expiration date displays on the Status page. ### Renewal -The renewal process is identical to initial activation — generate a new request, send it to Qualytics, and apply the signed key. +The renewal process is identical to initial activation. Generate a new request, send it to Qualytics, and apply the signed key. - A warning appears when the license expires **within 30 days** (the date turns red with a warning icon) -- **Renew before expiration** to avoid service interruption — if a license expires, dataplane operations stop until a new license is applied +- **Renew before expiration** to avoid service interruption. If a license expires, dataplane operations stop until a new license is applied !!! note - No Helm configuration is needed for licensing — it is handled entirely through the UI. + No Helm configuration is needed for licensing. It is handled entirely through the UI. ## Air-Gapped Deployments @@ -275,7 +287,7 @@ Qualytics fully supports air-gapped deployments with no internet egress required 1. **Import container images** into your private registry using the credentials from your account manager 2. **Update image URLs** in `values.yaml` to point to your private registry -3. **Use OIDC authentication** — configure direct integration with your enterprise IdP (see the [OIDC Configuration Guide](oidc-configuration.md)) +3. **Use OIDC authentication.** Configure direct integration with your enterprise IdP (see the [OIDC Configuration Guide](oidc-configuration.md)). !!! info The only egress requirement for a standard self-hosted deployment is to `https://auth.qualytics.io` for Auth0 authentication. By using OIDC instead, you eliminate this requirement entirely. diff --git a/docs/source-datastore/add-datastores/snowflake.md b/docs/source-datastore/add-datastores/snowflake.md index 6e6f510446..a647155ba2 100644 --- a/docs/source-datastore/add-datastores/snowflake.md +++ b/docs/source-datastore/add-datastores/snowflake.md @@ -161,6 +161,10 @@ Common causes: !!! tip Start by confirming credentials are valid (authentication errors), then verify role privileges (permission errors), and finally check warehouse availability (connection errors). +## Identifying Qualytics in Snowflake + +Qualytics tags every Snowflake JDBC connection with `application=Qualytics`. The tag appears in Snowflake's `QUERY_HISTORY`, `LOGIN_HISTORY`, and Snowsight monitoring under the **Client Application** column, making it easy to filter and analyze Qualytics activity in your account. No configuration is required on your side. + ## Add a Source Datastore A source datastore is a storage location used to connect to and access data from external sources. Snowflake is an example of a source datastore, specifically a type of JDBC datastore that supports connectivity through the JDBC API. Configuring the JDBC datastore enables the Qualytics platform to access and perform operations on the data, thereby generating valuable insights. @@ -416,7 +420,7 @@ This section provides sample payloads for creating a Snowflake datastore. Replac "schema": "snowflake_schema", "enrich_only": false, "trigger_catalog": true, - "connection_id": connection-id + "connection_id": 123 } ``` === "Create a Source Datastore using the CLI" @@ -472,7 +476,7 @@ This section provides sample payloads for creating an enrichment datastore. Repl "database": "snowflake_database", "schema": "snowflake_schema", "enrich_only": true, - "connection_id": connection-id + "connection_id": 123 } ``` === "Create an Enrichment Datastore using the CLI" From 99ebc2ba5660ad311e2a373d5a71cfa1d43ab773 Mon Sep 17 00:00:00 2001 From: Rafael Riki Ogawa Osiro Date: Wed, 3 Jun 2026 15:15:21 -0300 Subject: [PATCH 2/2] docs(self-hosted): apply Greptile review fixes - Normalize 'control-plane' to 'controlplane' - Soften POSTGRES_SCHEMA guidance: chart does not expose the key via values.yaml - Add missing periods to license request and renewal items --- docs/deployments/self-hosted-deployment.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/deployments/self-hosted-deployment.md b/docs/deployments/self-hosted-deployment.md index 7fc2834384..01334cb77a 100644 --- a/docs/deployments/self-hosted-deployment.md +++ b/docs/deployments/self-hosted-deployment.md @@ -167,7 +167,7 @@ For the full list of available options, refer to `charts/qualytics/values.yaml` ### Database Configuration (Optional) -Two control-plane database options are available for self-hosted deployments: +Two controlplane database options are available for self-hosted deployments: **PostgreSQL fork compatibility** @@ -175,7 +175,7 @@ The control plane supports stock PostgreSQL and common forks, including **EDB Po **Custom PostgreSQL schema** -The control plane reads the `POSTGRES_SCHEMA` environment variable (default `public`) to decide where its tables live. Alembic migrations automatically run `CREATE SCHEMA IF NOT EXISTS` and set the session `search_path`, so no manual schema creation is required. Set this variable through your Helm values when sharing one PostgreSQL instance across multiple Qualytics environments or when matching internal naming conventions. +The control plane reads the `POSTGRES_SCHEMA` environment variable (default `public`) to decide where its tables live. Alembic migrations automatically run `CREATE SCHEMA IF NOT EXISTS` and set the session `search_path`, so no manual schema creation is required. Set this environment variable on the controlplane deployment when sharing one PostgreSQL instance across multiple Qualytics environments or when matching internal naming conventions. ### Deploy @@ -261,7 +261,7 @@ Self-hosted deployments require a valid license. A **31-day grace period** start ### Requesting a License 1. Navigate to **Settings > Status** (requires **Admin** or **Manager** role) -2. Click **Generate License Request**. This creates a signed request that uniquely identifies your deployment +2. Click **Generate License Request**. This creates a signed request that uniquely identifies your deployment. 3. Copy the request string and send it to your [Qualytics account manager](mailto:hello@qualytics.ai) via a secure channel (e.g., [Bitwarden Send](https://bitwarden.com/products/send/); never plain email) 4. Qualytics signs the request and returns a license key @@ -276,7 +276,7 @@ Self-hosted deployments require a valid license. A **31-day grace period** start The renewal process is identical to initial activation. Generate a new request, send it to Qualytics, and apply the signed key. - A warning appears when the license expires **within 30 days** (the date turns red with a warning icon) -- **Renew before expiration** to avoid service interruption. If a license expires, dataplane operations stop until a new license is applied +- **Renew before expiration** to avoid service interruption. If a license expires, dataplane operations stop until a new license is applied. !!! note No Helm configuration is needed for licensing. It is handled entirely through the UI.