Skip to main content

Before installing: what each team grants

A Qry installation waits on other teams more than on anything in Qry: an app registration, a role on a resource, a grant on a catalog, an outbound rule. This page is the whole list, one section per team, so each request can go out on day one instead of being discovered one at a time.

Each team can check its part itself, before Qry exists, with the qry CLI:

qry doctor --plane prerequisites [flags for the parts you own]

It calls each service as the identity in question rather than reading role names, changes nothing, and says what is missing and how to fix it. Every flag is optional; checks for a part you did not name are left out.

The scripts below print every command and change nothing unless run with --apply. Read them first; they are short.

Identity team​

Microsoft Entra ID​

One app registration for sign-in. Download azure-entra-app.sh and run it with your own az login:

./azure-entra-app.sh --qry-url https://qry.example.com [--groups] [--databricks-obo]          # review
./azure-entra-app.sh --qry-url https://qry.example.com [--groups] [--databricks-obo] --apply # do it
WhatWhyWhen
Web redirect URI https://<qry>/auth/azure/callbackEntra sends the sign-in back there; any other address fails with AADSTS50011Always
Microsoft Graph › openid, profile, email, User.Read (delegated)The person's name and e-mail at sign-inAlways
Admin consentMost tenants forbid people from consenting themselves, so without it the first sign-in stops at "Need admin approval"Always
A client secret or certificateQry's credential for the sign-in exchange. Renew it before it expires: when it does, nobody can sign inAlways
Groups claim (security groups, ID token)Map Entra groups to Qry groupsOnly with group mapping
AzureDatabricks › user_impersonation (delegated) + admin consentRun each person's Databricks queries as that person (queries as the user)Only with queries as each person

The script writes the secret to qry-entra-secret.txt (readable only by you), never to the terminal, and prints its end date. Paste both in Admin › Authentication: Qry notifies administrators before the secret expires.

qry doctor --plane prerequisites --entra-app-id <appId> --qry-url https://qry.example.com

Google​

An OAuth client of type Web application in the Google Cloud console (APIs & Services › Credentials), with https://<qry>/auth/google/callback as an authorised redirect URI. Google does not offer this through gcloud, so there is no script.

Cloud platform team​

Azure​

  • Models (Azure AI Foundry): a resource of kind AIServices with a custom subdomain, the deployments Qry will use, and on it, for the identity Qry runs as: Cognitive Services User, Cognitive Services OpenAI User and Azure AI Developer. The OpenAI and Anthropic endpoints authorise separately; being subscription Owner grants neither.
  • Cluster (AKS): running, with OIDC issuer and workload identity enabled (so Qry needs no key), the Blob CSI driver if files live in Azure Blob, and more than one 4 vCPU / 16 GB node.
qry doctor --plane prerequisites --azure-resource-group <rg> \
--azure-resource <foundry-resource> --aks-cluster <cluster>

Google Cloud​

A service account with only the roles Qry uses, reached from the cluster through workload identity. Download gcp-service-account.sh:

./gcp-service-account.sh --project <project> [--vertex] [--bigquery-datasets proj:ds1,proj:ds2]          # review
./gcp-service-account.sh --project <project> [--vertex] [--bigquery-datasets proj:ds1,proj:ds2] --apply # do it
WhatWhyWhen
Vertex AI API + roles/aiplatform.userGemini and the other Vertex modelsModels from Vertex
Organization policy vertexai.allowedPartnerModelFeatures allowing publishers/anthropic:web_searchThe chat's web search with Claude, which Google denies by default (how)Claude on Vertex, with web search
roles/bigquery.jobUser on the project, roles/bigquery.dataViewer on each datasetRun queries; read only the datasets named, never the whole projectBigQuery datasources
roles/iam.workloadIdentityUser for <namespace>/qry-backend-saQry's pods act as the account without a keyGKE with workload identity

Not Owner or Editor: they reach every service in the project, and the check flags them.

qry doctor --plane prerequisites --gcp-project <project> --gcp-service-account <sa> \
--gke-cluster <cluster> --gke-location <region>

Data platform team​

Databricks (Azure)​

Qry's own identity for its work (catalog, profiling, anything not done as a person) is an Entra service principal with OAuth client credentials. Not a personal access token: a token carries all of its owner's rights, usually an administrator's, makes every query look like one person in Unity Catalog's audit, and stops when that person leaves.

Download azure-databricks.sh:

./azure-databricks.sh --host <workspace-host> --warehouse <id> --catalog <catalog> \
--schemas sales,finance [--write-schemas staging] # review; add --apply to do it

It creates the principal and its secret (whose end date it prints, for the datasource's Client secret expires on), adds it to the workspace and gives it Can use on the warehouse. The Unity Catalog grants go to qry-databricks-grants.sql for the catalog owner to run:

  • USE CATALOG on the catalog; USE SCHEMA and SELECT on each schema Qry answers from.
  • CREATE TABLE and MODIFY only on the schemas Qry pipelines write to, never on the whole catalog.

With queries as each person, people read with their own grants; Qry's principal needs nothing more for that. Check that groups such as account users do not hold MODIFY on the whole catalog: the check flags it, because it lets Qry's identity, and with queries as each person every person, write anywhere in it.

qry doctor --plane prerequisites --databricks-host <host> --databricks-sp <appId> \
--databricks-warehouse <id> --databricks-catalog <catalog>

The check sees Can use on the warehouse when it is granted to the principal or to users; through another group it reads as missing, so confirm it on the warehouse's permissions page.

Network and security team​

Inbound: HTTPS to Qry's address, with a certificate for it.

Outbound from the cluster's nodes:

DestinationFor
registry.qry.dev, europe-southwest1-docker.pkg.devQry's images: the registry checks the license, the image layers come from the second
get.qry.devOnline license: whether it was withdrawn (every 6 h, 7 days' grace). Not needed with an offline license
*.googleapis.comOnly installations still on the older service-account license key
login.microsoftonline.comEntra sign-in and tokens (Azure)
<resource>.services.ai.azure.com, <resource>.openai.azure.comModels on Azure AI Foundry
<region>-aiplatform.googleapis.com, oauth2.googleapis.comModels on Vertex AI, Google tokens
<workspace>.azuredatabricks.netDatabricks
Each datasource's host and portOracle, SQL Server, PostgreSQL…

A cluster with no route to the internet takes an offline license. The images can be copied into your own registry instead of pulled from ours.

What keeps people's code away from Qry's data​

People's Python and notebooks run code of their choosing on the cluster's network. A new installation keeps that code away from what Qry stores, with nothing to configure:

  • Network policies are on. Only Qry's own pods can reach its PostgreSQL and its Redis, and only Qry's backend and workers can reach the pods that run people's code. The code can still reach Qry's backend (the qry module in notebooks), the internet (for pip) and your data sources. They need a cluster that enforces network policies (GKE Dataplane V2, AKS with Azure or Cilium network policy, Calico); on one that does not, they are present but have no effect.
  • PostgreSQL and Redis have their own passwords, random ones generated at installation. Nobody chooses or sees them, and notebooks never get them. A managed PostgreSQL or Redis keeps the password you give it.
  • No pod that runs people's code gets a Kubernetes token, so that code cannot call the Kubernetes API.
  • Several Qry installations can share a cluster, even the namespace where code runs: each one's policies cover only its own pods.

Each installation includes a check: helm test <release> -n <namespace> runs a pod with no special access and fails if it can talk to Redis without the password.

Installing with helm template (Argo CD, Flux, a marketplace's installer): the chart cannot read the cluster there, so give the passwords as values (postgresql.auth.password, redis.auth.password). Without one, PostgreSQL refuses to render, and Redis runs without a password.

Upgrading an installation from before November 2026 turns the network policies on, unless your values set networkPolicies.enabled: false. After that, anything outside Qry's namespace that connects straight to its PostgreSQL or Redis stops reaching them, for example a backup job in another namespace. Run it in Qry's namespace with the label qry.ixen.ai/trusted: "true", or tell us.

The upgrade does not change the passwords. PostgreSQL keeps the one it was created with, which on older installations may be the old default qry2024lab. Redis stays without a password. To set them:

# Redis: a value is enough; the upgrade restarts Redis and Qry with it.
helm upgrade qry <chart> -n <namespace> --reset-then-reuse-values --set redis.auth.password="$(openssl rand -hex 16)"

# PostgreSQL: change it in the database first, then give the same value to the chart.
NEW="$(openssl rand -hex 16)"
kubectl exec -n <namespace> postgres-0 -- psql -U postgres -c "ALTER USER postgres PASSWORD '$NEW'"
helm upgrade qry <chart> -n <namespace> --reset-then-reuse-values --set postgresql.auth.password="$NEW"

Keep both where you keep the installation's other secrets: a later helm template needs them.

After installing: the first administrator​

A new installation has no users and no default password. Open Qry: it asks for a setup code and the first administrator's email and password (12 characters or more). The code is in the backend's log:

kubectl logs deploy/qry-backend -n <namespace> | grep "setup code"

It works once. Every backend replica prints the same code, and it stays the same across restarts until the administrator exists. Ten wrong tries pause attempts for everyone for 15 minutes — anyone who reaches the page can cause that pause, so keep a new installation off public addresses until it has its administrator, or give the code at installation. To hand the code over another way, set bootstrap.setupCode (12 characters or more): the chart mounts it into the backend from a Kubernetes Secret as a file. Whoever has the code can become the administrator, so keep it as you would a password.

The page comes back only if no active administrator is left (the last one deactivated); the code is then in the log of the backend's next start.

The same screen proposes the address people will use to reach Qry (the one in the browser), and saves it for links in emails and shares. Then the administrator lands in a guided setup: see after installing.

What the checks do not cover​

  • Outbound rules: from a laptop, a rule that does not exist looks the same as one that does. Test from inside the cluster.
  • Roles inherited from a Google folder or organisation, and warehouse permissions granted through a group other than users.
  • Whether each person exists in Databricks for queries as each person; that shows at their first query, with a reason.