Production Deployment
GoodData.CN installs into your own Kubernetes cluster with a Helm chart. We recommend you deploy and monitor GoodData.CN the same way your company deploys and monitors its other applications, on the same clusters and through the same delivery pipeline, secret management, and observability stack. Nothing below asks you to run a separate platform.
This guide is written using plain YAML and Helm commands. If you use a CI/CD system, you can translate it to your system of choice. Every helm upgrade --install command maps directly to an Argo CD Application, a Flux HelmRelease, or an equivalent resource that points at the same chart and values.
The page covers the GoodData.CN parts of the install: what to create in your cloud account, what to deploy into the cluster, and how to configure organizations and users in GoodData.
When you’re done, you should have:
- GoodData.CN + dependency charts deployed
- A GoodData Organization created
- An initial user created
1. Before you start
If you are deploying in a restricted environment such as AWS GovCloud, contact your GoodData representative for guidance before you follow these steps. Those environments have requirements that this guide does not cover.
Your infrastructure should already provide:
- Managed Kubernetes cluster (EKS)
- Multi-AZ.
- Baseline node size
m8a.xlarge. As a rule of thumb, GoodData services use CPU and memory in a ratio of about 1 vCPU : 4 GiB RAM. - A default StorageClass with dynamic provisioning for persistent volumes. Use
gp3withvolumeBindingMode: WaitForFirstConsumer. - An IAM OIDC provider associated with the cluster, so that you can use IAM roles for service accounts (IRSA).
- Ingress and DNS. Any ingress controller is fine. DNS routes each
<ORGANIZATION_HOSTNAME>to your ingress. - Cluster access. A
kubectlcontext that points at the cluster, with permission to create namespaces, secrets, and custom resources. - (Recommended) KEDA operator for autoscaling. GoodData.CN services scale horizontally through KEDA. We strongly recommend installing the KEDA operator, version 2.x, as part of your cluster setup and enabling autoscaling when you generate the configuration. Deploy KEDA the same way you deploy your other cluster add-ons; GoodData.CN only requires that the operator is running in the cluster before you install with autoscaling enabled. See Configure Autoscaling in GoodData.CN for which services scale and how to tune them.
Have these handy:
- AWS account ID and region (used for S3 URLs), e.g.
eu-central-1 - Organization hostnames, e.g.
gooddata.example.com,sandbox.example.com - Organization IDs (DNS labels), e.g.
prod,sandbox - Your GoodData.CN license key
Your infrastructure should already provide:
- Managed Kubernetes cluster (AKS)
- Multi-AZ.
- Baseline node size
Standard_D4as_v6. As a rule of thumb, GoodData services use CPU and memory in a ratio of about 1 vCPU : 4 GiB RAM. - A default StorageClass with dynamic provisioning for persistent volumes. Use a Premium SSD (
Premium_LRS) class withvolumeBindingMode: WaitForFirstConsumer. AKS shipsStandardSSD_LRSas the default, so create a premium class and make it the default before you install any chart. - The OIDC issuer and workload identity enabled, so that pods can use Microsoft Entra Workload ID.
- Ingress and DNS. Any ingress controller is fine. DNS routes each
<ORGANIZATION_HOSTNAME>to your ingress public IP. - Cluster access. A
kubectlcontext that points at the cluster, with permission to create namespaces, secrets, and custom resources. - (Recommended) KEDA operator for autoscaling. GoodData.CN services scale horizontally through KEDA. We strongly recommend installing the KEDA operator, version 2.x, as part of your cluster setup and enabling autoscaling when you generate the configuration. Deploy KEDA the same way you deploy your other cluster add-ons; GoodData.CN only requires that the operator is running in the cluster before you install with autoscaling enabled. See Configure Autoscaling in GoodData.CN for which services scale and how to tune them.
Have these handy:
- Azure subscription, resource group, and region, e.g.
East US - Organization hostnames, e.g.
gooddata.example.com,sandbox.example.com - Organization IDs (DNS labels), e.g.
prod,sandbox - Your GoodData.CN license key
2. Tools you’ll need
Several steps below need a password or a license key. Each one reads the value into a shell variable with read -s first and then references the variable, so the literal secret is never typed into a command and never lands in your shell history.
3. Create cloud resources
GoodData.CN needs three things from your cloud account: a PostgreSQL database for metadata, object storage for exports and the Quiver cache, and a workload identity that lets the GoodData.CN pods reach that storage without static credentials. This step creates the database and the storage, then the gooddata-cn namespace and the secrets the chart reads. The workload identity comes later, in 5. Workload identity for storage access, because it consumes policy files that you generate in step 4.
The commands below use the CLI. You can create the same resources in the console, in your own Terraform or Bicep modules, or through whatever provisioning workflow your company already uses.
3.1 Metadata database
Create an Amazon RDS for PostgreSQL instance in the private subnets of your cluster VPC:
read -rsp 'Database master password: ' DB_PASSWORD && echo
aws rds create-db-instance \
--db-instance-identifier gooddata-cn \
--engine postgres \
--db-instance-class db.t4g.medium \
--allocated-storage 20 \
--max-allocated-storage 100 \
--storage-encrypted \
--no-publicly-accessible \
--master-username postgres \
--master-user-password "$DB_PASSWORD" \
--db-subnet-group-name '<PRIVATE_DB_SUBNET_GROUP>' \
--vpc-security-group-ids '<RDS_SECURITY_GROUP_ID>'Notes on the settings:
- Engine version. Take the current AWS default for the
postgresengine. - Instance class. Start at
db.t4g.medium. If you use theprod-largesize profile, upgrade todb.r6g.xlarge. - Storage. 20 GB encrypted storage is a starting point. Pass
--max-allocated-storage(for example,100) so that storage autoscaling is on. - Availability. The command above is a starter configuration and creates a single-AZ instance. For production, add
--multi-azso that RDS maintains a standby in a second availability zone and fails over automatically.
pg_trgm is required for user and user-group search. On RDS it is a trusted extension and the GoodData.CN database migration creates it automatically, so there is nothing to configure.
Allow the cluster nodes to reach the database on port 5432:
aws ec2 authorize-security-group-ingress \
--group-id '<RDS_SECURITY_GROUP_ID>' \
--protocol tcp --port 5432 \
--source-group '<EKS_CLUSTER_PRIMARY_SECURITY_GROUP_ID>'Record the instance endpoint and the master username, and keep DB_PASSWORD in the same shell session. You need all three in 7. Install GoodData.CN. If you open a new shell later, read the password in again with read -rsp 'Database password: ' DB_PASSWORD && echo.
Create an Azure Database for PostgreSQL Flexible Server, integrated into your VNet:
read -rsp 'Database administrator password: ' DB_PASSWORD && echo
az postgres flexible-server create \
--resource-group '<RESOURCE_GROUP>' \
--name '<DB_SERVER_NAME>' \
--location '<AZURE_REGION>' \
--version 16 \
--tier GeneralPurpose \
--sku-name GP_Standard_D2ds_v5 \
--storage-size 32 \
--storage-auto-grow Enabled \
--backup-retention 7 \
--admin-user '<DB_USERNAME>' \
--admin-password "$DB_PASSWORD" \
--vnet '<VNET_NAME>' \
--subnet '<DB_SUBNET_NAME>' \
--private-dns-zone '<DB_SERVER_NAME>.postgres.database.azure.com' \
--public-access DisabledNotes on the settings:
- Engine version. PostgreSQL 16.
- SKU. Start at
GP_Standard_D2ds_v5. If you use theprod-largesize profile, useMO_Standard_E8ds_v5. - Storage. 32 GiB is a starting point. Keep
--storage-auto-grow Enabledso that storage autoscaling is on. - Networking. The server is delegated into a dedicated subnet and resolved through a private DNS zone linked to the cluster VNet. Public network access stays disabled.
- Availability. The command above is a starter configuration and creates a server without zone redundancy. For production, add
--high-availability ZoneRedundantin a region that supports availability zones, so that Flexible Server keeps a standby in a second zone and fails over automatically.
PG_TRGM is required for user and user-group search, and Flexible Server creates only allowlisted extensions, so allowlist it before you install:
az postgres flexible-server parameter set \
--resource-group '<RESOURCE_GROUP>' \
--server-name '<DB_SERVER_NAME>' \
--name azure.extensions \
--value PG_TRGMazure.extensions is a single comma-separated allowlist. If you already allowlist other extensions on this server, add PG_TRGM to the existing list instead of replacing it.
Record the server FQDN and the administrator login, and keep DB_PASSWORD in the same shell session. You need all three in 7. Install GoodData.CN. If you open a new shell later, read the password in again with read -rsp 'Database password: ' DB_PASSWORD && echo.
3.2 Object storage
GoodData.CN uses three separate buckets or containers:
| Purpose | What it holds |
|---|---|
| Exports | Exported reports and data |
| Quiver cache | Query acceleration cache (durable storage) |
| Quiver datasource filesystem | Uploaded data source files, for example CSVs |
Create three S3 buckets, for example company-gooddata-exports, company-gooddata-quiver-cache, and company-gooddata-quiver-datasource-fs. Block all public access and enable default encryption on each:
AWS_REGION='<AWS_REGION>'
for BUCKET in '<EXPORTS_BUCKET_NAME>' '<QUIVER_CACHE_BUCKET_NAME>' '<DATASOURCE_FS_BUCKET_NAME>'; do
# us-east-1 rejects a LocationConstraint; every other region requires one.
if [ "$AWS_REGION" = "us-east-1" ]; then
aws s3api create-bucket \
--bucket "$BUCKET" \
--region "$AWS_REGION"
else
aws s3api create-bucket \
--bucket "$BUCKET" \
--region "$AWS_REGION" \
--create-bucket-configuration LocationConstraint="$AWS_REGION"
fi
aws s3api put-public-access-block \
--bucket "$BUCKET" \
--public-access-block-configuration \
"BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"
aws s3api put-bucket-encryption \
--bucket "$BUCKET" \
--server-side-encryption-configuration \
'{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'
doneAll three buckets hold regenerable data, so leave versioning off. Keep the buckets in the same region as the cluster.
Create one storage account and three private containers in it:
az storage account create \
--resource-group '<RESOURCE_GROUP>' \
--name '<AZURE_STORAGE_ACCOUNT_NAME>' \
--location '<AZURE_REGION>' \
--kind StorageV2 \
--sku Standard_LRS \
--min-tls-version TLS1_2 \
--allow-blob-public-access false
for CONTAINER in exports quiver-cache quiver-datasource-fs; do
az storage container create \
--account-name '<AZURE_STORAGE_ACCOUNT_NAME>' \
--name "$CONTAINER" \
--public-access off \
--auth-mode login
doneAll three containers hold regenerable data, so leave blob versioning off. Keep the storage account in the same region as the cluster.
3.3 Namespace and secrets
Create the namespace:
kubectl create namespace gooddata-cnCreate the metadata database secret. The chart reads the password from the
postgresql-passwordkey, so the key name must be exactly that.DB_PASSWORDis the password you set in 3.1 Metadata database; if you are in a new shell, read it in again first:read -rsp 'Database password: ' DB_PASSWORD && echo printf '%s' "$DB_PASSWORD" | kubectl -n gooddata-cn create secret generic gdcn-postgres \ --from-file=postgresql-password=/dev/stdinCreate the encryption keyset secret:
tinkey create-keyset --key-template AES256_GCM --out gdcn-keyset.json kubectl -n gooddata-cn create secret generic gdcn-encryption --from-file=keySet=gdcn-keyset.jsonCreate the license secret:
read -rsp 'GoodData.CN license key: ' GDCN_LICENSE_KEY && echo printf '%s' "$GDCN_LICENSE_KEY" | kubectl -n gooddata-cn create secret generic gdcn-license \ --from-file=license=/dev/stdin
4. Generate the configuration files
With the database and the storage in place, generate every configuration file that the rest of this guide uses. The Configuration Assistant is how you create them. It asks for your hostnames, buckets, and identities once, then writes the whole set for you:
trust-policy.jsonands3-policy.jsonfor the workload identity in 5. Workload identity for storage accesspulsar-values.yamlandpulsar-values-sizing.yamlfor 6. Install Pulsargdcn-values.yamlandgdcn-values-sizing.yamlfor 7. Install GoodData.CNorganization.yamlfor 8. Create an organization
The sizing files come from the prod-small and prod-large size profiles, so you get production-grade resource requests without tuning them yourself. Every step from here on assumes these files exist and refers to them by name, so run the assistant before you continue.
Open the Configuration Assistant
5. Workload identity for storage access
GoodData.CN runs under the gooddata-cn service account in the gooddata-cn namespace. Bind that service account to a cloud identity so the pods reach object storage without static credentials.
Use the IRSA trust policy in the
trust-policy.jsongenerated in 4. Generate the configuration files. The assistant asks for<OIDC_PROVIDER>, which is your cluster’s OIDC issuer URL without thehttps://prefix, for exampleoidc.eks.eu-central-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE.Use the S3 permission policy in the generated
s3-policy.json. It grants the three buckets you created in 3.2 Object storage the bucket listing and object read, write, and multipart permissions that GoodData.CN needs.Create the role and attach the policy:
aws iam create-role \ --role-name gooddata-cn-irsa \ --assume-role-policy-document file://trust-policy.json aws iam create-policy \ --policy-name GoodDataCNS3Access \ --policy-document file://s3-policy.json aws iam attach-role-policy \ --role-name gooddata-cn-irsa \ --policy-arn 'arn:aws:iam::<AWS_ACCOUNT_ID>:policy/GoodDataCNS3Access'
Record the role ARN. You annotate the service account with it in 7. Install GoodData.CN.
Create a user-assigned managed identity:
az identity create \ --resource-group '<RESOURCE_GROUP>' \ --name gooddata-cn-uami \ --location '<AZURE_REGION>'Grant it data-plane access to the storage account:
az role assignment create \ --assignee-object-id "$(az identity show -g '<RESOURCE_GROUP>' -n gooddata-cn-uami --query principalId -o tsv)" \ --assignee-principal-type ServicePrincipal \ --role 'Storage Blob Data Contributor' \ --scope "$(az storage account show -g '<RESOURCE_GROUP>' -n '<AZURE_STORAGE_ACCOUNT_NAME>' --query id -o tsv)"Federate the identity with the cluster service account:
az identity federated-credential create \ --name gdcn-workload \ --identity-name gooddata-cn-uami \ --resource-group '<RESOURCE_GROUP>' \ --issuer "$(az aks show -g '<RESOURCE_GROUP>' -n '<AKS_CLUSTER_NAME>' --query oidcIssuerProfile.issuerUrl -o tsv)" \ --subject 'system:serviceaccount:gooddata-cn:gooddata-cn' \ --audience api://AzureADTokenExchange
Record the identity’s client ID:
az identity show -g '<RESOURCE_GROUP>' -n gooddata-cn-uami --query clientId -o tsvYou put it into the Helm values in 7. Install GoodData.CN. The values there also set the azure.workload.identity/use: "true" pod label on every workload that talks to storage. Without that label, the webhook does not inject the projected token and storage access fails.
6. Install Pulsar
GoodData.CN uses Pulsar for messaging. If you don’t already run Pulsar, install it like this:
Use the
pulsar-values.yamlandpulsar-values-sizing.yamlgenerated in 4. Generate the configuration files. These values are the same on AWS and Azure. The only cloud difference is the StorageClass the Pulsar volumes land on, which comes from your cluster default (see 1. Before you start).Install:
helm repo add pulsar https://pulsar.apache.org/charts helm repo update helm upgrade --install pulsar pulsar/pulsar \ --namespace pulsar --create-namespace \ --version "3.9.0" \ --values pulsar-values.yaml \ --values pulsar-values-sizing.yaml \ --wait --timeout 30m
7. Install GoodData.CN
7.1 Values files
Use the gdcn-values.yaml and gdcn-values-sizing.yaml generated in 4. Generate the configuration files. Open both files, read through them, and fill in anything the assistant left as a placeholder with the values you recorded in 3. Create cloud resources and 5. Workload identity for storage access.
A few defaults are worth knowing before you install:
- The database password stays out of the file.
gdcn-values.yamlpoints the metadata database at thegdcn-postgressecret you created in 3.3 Namespace and secrets, so only the host, port, and username appear in the values. - Dex is off.
deployDexIdPisfalse, because the built-in Dex identity provider is meant for testing environments only. To turn it on, follow Set Up Authentication Using the Default Dex Identity Provider and the Dex steps in 9. Auth and users. - Any ingress controller works. The values set the ingress class you gave the assistant. You still need DNS to route each
<ORGANIZATION_HOSTNAME>to your ingress. - Sizing is a separate file.
gdcn-values-sizing.yamlholds the size profile you picked, so pass both files to Helm in the next step.
7.2 Install
Find the latest CN version from the release notes.
Install (using both values files):
helm repo add gooddata https://charts.gooddata.com/ helm repo update helm upgrade --install gooddata-cn gooddata/gooddata-cn \ --namespace gooddata-cn \ --version "[GOODDATA_CN_VERSION x.xx.x]" \ --values gdcn-values.yaml \ --values gdcn-values-sizing.yaml \ --wait --timeout 30m
8. Create an organization
GoodData.CN creates one administrator for the organization. The default user name is admin. Set another name with ADMIN_USER below, and set spec.adminUser in organization.yaml to that same name. The bootstrap token authenticates as that user. This is the only user that can start the initial provisioning of the organization. The user has one API token, with the id bootstrap. That token is the bootstrap token.
This user has no authentication ID, so it cannot sign in through the UI until you map it to your identity provider. See Set Up Authentication.
The Helm chart does not create the bootstrap token. You provide it on the Organization custom resource, in adminUserToken or adminUserTokenSecret.
Decide:
ORG_ID(example:prod)ORGANIZATION_HOSTNAME(example:gooddata.example.com)ADMIN_USER(default:admin). Use this same name forspec.adminUserinorganization.yaml.ADMIN_GROUP(default:adminGroup)ADMIN_PASSWORD(strong secret). This is the secret half of the bootstrap token.
Generate a salted hash of
ADMIN_PASSWORD.openssl passwd -stdinreads the password from standard input, so it never appears as a command argument:read -rsp 'Admin password: ' ADMIN_PASSWORD && echo printf '%s' "$ADMIN_PASSWORD" | openssl passwd -6 -stdinOpen the
organization.yamlgenerated in 4. Generate the configuration files. It holds one Organization document per hostname you gave the assistant. Setspec.adminUserto the same name asADMIN_USER. Put the hash from the previous step intoadminUserTokenfor each organization and fill in any remaining placeholders.To keep the hash out of the manifest, store it in a Kubernetes Secret and set
adminUserTokenSecretinstead:adminUserTokenSecret: kubernetesSecret: name: <secret-name> key: <key>The Secret value is the same salted hash. Set exactly one of
adminUserTokenoradminUserTokenSecret. WithadminUserTokenSecret,organization.yamlcontains only the Secret name and key. Securely back up that Secret, or recreate it with the same salted hash, before you restore the manifest.API calls use the bootstrap token, which is the Base64 encoding of
<ADMIN_USER>:bootstrap:<ADMIN_PASSWORD>. Send it asAuthorization: Bearer <token>.Apply the Organization custom resource:
kubectl -n gooddata-cn apply -f organization.yamlBack up
organization.yamlalongside your other deployment configuration. You need this file to recreate the Organization when you restore the deployment. When the file usesadminUserTokenSecret, it holds only a reference to the Kubernetes Secret. Securely back up that Secret, or recreate it with the same salted hash, before you restore the manifest. See Backup and Restore.Limit where the bootstrap token can be used. Create an IP allowlist policy for the configured
ADMIN_USER, the administrator used for the initial setup, and include only the networks that run that setup. The bootstrap token has full administrative access.
9. Auth and users
Connect GoodData.CN to your own identity provider. The built-in Dex identity provider is available as a testing-only alternative.
External OIDC (default)
Bring your own IdP (Okta, Entra ID, Auth0, and similar) and configure GoodData to trust it. Follow the Set Up Authentication guide.
Built-in Dex (testing environments only)
Dex is for testing only. To enable it:
- Re-run the Configuration Assistant with Dex selected as the identity provider to regenerate
gdcn-values.yamlwithdeployDexIdP: trueand thedex:block, or add them by hand as shown in Set Up Dex. - Point DNS for
<AUTH_HOSTNAME>at your ingress. - Run
helm upgradeagain.
For details, see Set Up Authentication Using the Default Dex Identity Provider.
With Dex enabled, create users through the public APIs:
Encode the bootstrap token from the
ADMIN_USERandADMIN_PASSWORDyou set in Create an organization:read -rsp 'Admin password: ' ADMIN_PASSWORD && echoBOOT_TOKEN="$(printf '%s' "<ADMIN_USER>:bootstrap:$ADMIN_PASSWORD" | base64 | tr -d '\n')"
Create the user in Dex:
POST https://<ORGANIZATION_HOSTNAME>/api/v1/auth/users- Header:
Authorization: Bearer <BOOT_TOKEN> - Body:
{ "email": "user@example.com", "password": "user_password_here", "displayName": "First Last" }From the Dex response, capture
authenticationId.Create the user record in GoodData:
POST https://<ORGANIZATION_HOSTNAME>/api/v1/entities/users- Header:
Authorization: Bearer <BOOT_TOKEN> - Header:
Content-Type: application/vnd.gooddata.api+json - Body:
{ "data": { "id": "user.at.example.com", "type": "user", "attributes": { "email": "user@example.com", "firstname": "First", "lastname": "Last", "authenticationId": "<DEX_AUTHENTICATION_ID>" } } }
10. Log in
- Open GoodData.CN:
https://<ORGANIZATION_HOSTNAME>
Support
If you have any trouble following these steps, reach out to us via support.
Other Platforms
GoodData.CN runs on any conformant Kubernetes cluster. If you are considering another platform, contact GoodData for guidance.