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 gp3 with volumeBindingMode: 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 kubectl context 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 with volumeBindingMode: WaitForFirstConsumer. AKS ships StandardSSD_LRS as 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 kubectl context 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

  1. Your cloud CLI: AWS CLI or Azure CLI
  2. kubectl
  3. helm
  4. tinkey
  5. Standard utilities: curl, openssl, base64, jq

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 postgres engine.
  • Instance class. Start at db.t4g.medium. If you use the prod-large size profile, upgrade to db.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-az so 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 Disabled

Notes on the settings:

  • Engine version. PostgreSQL 16.
  • SKU. Start at GP_Standard_D2ds_v5. If you use the prod-large size profile, use MO_Standard_E8ds_v5.
  • Storage. 32 GiB is a starting point. Keep --storage-auto-grow Enabled so 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 ZoneRedundant in 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_TRGM

azure.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:

PurposeWhat it holds
ExportsExported reports and data
Quiver cacheQuery acceleration cache (durable storage)
Quiver datasource filesystemUploaded 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"}}]}'
done

All 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
done

All 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

  1. Create the namespace:

    kubectl create namespace gooddata-cn
  2. Create the metadata database secret. The chart reads the password from the postgresql-password key, so the key name must be exactly that. DB_PASSWORD is 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/stdin
  3. Create 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.json
  4. Create 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:

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.

  1. Use the IRSA trust policy in the trust-policy.json generated in 4. Generate the configuration files. The assistant asks for <OIDC_PROVIDER>, which is your cluster’s OIDC issuer URL without the https:// prefix, for example oidc.eks.eu-central-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE.

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

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

  1. Create a user-assigned managed identity:

    az identity create \
      --resource-group '<RESOURCE_GROUP>' \
      --name gooddata-cn-uami \
      --location '<AZURE_REGION>'
  2. 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)"
  3. 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 tsv

You 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:

  1. Use the pulsar-values.yaml and pulsar-values-sizing.yaml generated 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).

  2. 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.yaml points the metadata database at the gdcn-postgres secret you created in 3.3 Namespace and secrets, so only the host, port, and username appear in the values.
  • Dex is off. deployDexIdP is false, 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.yaml holds the size profile you picked, so pass both files to Helm in the next step.

7.2 Install

  1. Find the latest CN version from the release notes.

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

  1. Decide:

    • ORG_ID (example: prod)
    • ORGANIZATION_HOSTNAME (example: gooddata.example.com)
    • ADMIN_USER (default: admin). Use this same name for spec.adminUser in organization.yaml.
    • ADMIN_GROUP (default: adminGroup)
    • ADMIN_PASSWORD (strong secret). This is the secret half of the bootstrap token.
  2. Generate a salted hash of ADMIN_PASSWORD. openssl passwd -stdin reads 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 -stdin
  3. Open the organization.yaml generated in 4. Generate the configuration files. It holds one Organization document per hostname you gave the assistant. Set spec.adminUser to the same name as ADMIN_USER. Put the hash from the previous step into adminUserToken for each organization and fill in any remaining placeholders.

    To keep the hash out of the manifest, store it in a Kubernetes Secret and set adminUserTokenSecret instead:

    adminUserTokenSecret:
      kubernetesSecret:
        name: <secret-name>
        key: <key>

    The Secret value is the same salted hash. Set exactly one of adminUserToken or adminUserTokenSecret. With adminUserTokenSecret, organization.yaml contains 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 as Authorization: Bearer <token>.

  4. Apply the Organization custom resource:

    kubectl -n gooddata-cn apply -f organization.yaml
  5. Back up organization.yaml alongside your other deployment configuration. You need this file to recreate the Organization when you restore the deployment. When the file uses adminUserTokenSecret, 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.

  6. 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:

  1. Re-run the Configuration Assistant with Dex selected as the identity provider to regenerate gdcn-values.yaml with deployDexIdP: true and the dex: block, or add them by hand as shown in Set Up Dex.
  2. Point DNS for <AUTH_HOSTNAME> at your ingress.
  3. Run helm upgrade again.

For details, see Set Up Authentication Using the Default Dex Identity Provider.

With Dex enabled, create users through the public APIs:

  1. Encode the bootstrap token from the ADMIN_USER and ADMIN_PASSWORD you set in Create an organization:

    • read -rsp 'Admin password: ' ADMIN_PASSWORD && echo
    • BOOT_TOKEN="$(printf '%s' "<ADMIN_USER>:bootstrap:$ADMIN_PASSWORD" | base64 | tr -d '\n')"
  2. 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"
    }
  3. From the Dex response, capture authenticationId.

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

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