Skip to content
Qubership APIHUB

Configuration reference — files, environment variables, and Helm values

This page ties together what you edit in GitOps versus what the processes actually load. Pair it with Installation guide.

Source of truth hierarchy

Section titled “Source of truth hierarchy”

  1. qubership-apihub Helm chart (deploy/helm-templates/qubership-apihub/ — values.yaml + templates) is the canonical delivery contract for Kubernetes: it defines Secrets, mounts, injected env vars, images, probes. Supported production shapes should be expressible without bypassing the chart (operators extend via values/overlays).

  2. Component source code is the authority on runtime behaviour: which knobs are read from config.yaml, which from environment, and exact variable names. This page is a map; where it disagrees with the code, the code wins.

  3. deploy/docker-compose/ stacks reproduce the same split for local rigs; they are downstream helpers, not replacements for Helm when you argue about cluster installs.

Annotated YAML schemas used by file-backed binaries live only where the loader exists today:

Component Boot-time YAML template Loader / pointers
API Registry config.template.yaml (module backend/portal-backend/) APIHUB_CONFIG_FOLDER → config.yaml; see backend service bootstrap.
Kubernetes Agent config.template.yaml Agent image (file-based like backend).
API Linter config.template.yaml LINTER_CONFIG_FOLDER → config.yaml. Spectral rulesets stay data managed through the linter API/database, separate from this boot config.
Agents-backend config.template.yaml AGENTS_BACKEND_CONFIG_FOLDER → config.yaml.
Builders / UI (none) Env only (builder env / UI nginx wrapper).

Golden path for admins: derive intent from Helm values → rendered manifests → confirm against the Go/TS loaders above when in doubt.

1. Configuration model per component

Section titled “1. Configuration model per component”
Service Primary runtime configuration Remarks
qubership-apihub-backend config.yaml on disk APIHUB_CONFIG_FOLDER; optional LOG_LEVEL, GOMEMLIMIT. File-backed: DB, security, SSO, S3, Olric, cleanup, AI, extensions. Helm: qubershipApihubBackend.env → qubership-apihub-backend-config-secret.yaml.
qubership-apihub-ui Environment variables only Internal upstream DNS (*_ADDRESS). Public URL in backend security.apihubExternalUrl. See Installation guide § UI.
qubership-apihub-build-task-consumer Environment variables only APIHUB_BACKEND_ADDRESS + APIHUB_API_KEY (aligned with backend zeroDayConfiguration.accessToken on bootstrap).
qubership-api-linter-service config.yaml on disk LINTER_CONFIG_FOLDER; optional LOG_LEVEL, GOMEMLIMIT. File-backed: DB, technicalParameters.apihub.*, linters.*, olric.*. Helm: qubershipApiLinterService.env → qubership-api-linter-service-config-secret.yaml.
qubership-apihub-agents-backend config.yaml on disk AGENTS_BACKEND_CONFIG_FOLDER; optional LOG_LEVEL, GOMEMLIMIT. File-backed: DB, technicalParameters.apihub.*, businessParameters.*, security.*, cleanup.snapshots.*. Helm: qubershipApihubAgentsBackend.env → qubership-apihub-agents-backend-config-secret.yaml.

Kubernetes agent (optional extension, not started by default Compose bundle): configured like the backend pattern — config.yaml from config.template.yaml, plus Ingress for agentUrl.

2. Helm — mapping values.yaml → runtime (integration first)

Section titled “2. Helm — mapping values.yaml → runtime (integration first)”

Chart: deploy/helm-templates/qubership-apihub/. File: values.yaml with inline semantics.

values.yaml root key Produced runtime configuration
qubershipApihubBackend.env Rendered as YAML into Secret config.yaml, mounted under /app/qubership-apihub-service/etc/ with APIHUB_CONFIG_FOLDER=/app/qubership-apihub-service/etc/. Olric namespace / replicaCount patched from Helm. Same schema as config.template.yaml.
qubershipApihubBackend.customCa Optional Kubernetes Secret mounted at /tmp/cert on the backend pod. Used with the qubership-core-base runtime image: the entrypoint loads PEM files into the system trust store before the app starts (OIDC, SAML, playground proxy, AI chat). Set enabled: true and secretName.
qubershipApihubBackend.goMemLimit Pod env GOMEMLIMIT (Go runtime soft limit; not part of config.yaml). Default 410MiB (~80% of default resource.memory.limit 512Mi).
qubershipApihubBuildTaskConsumer.env Pod env (APIHUB_API_KEY, etc.). Address often mirrors qubershipApihubUi.env.apihubBackendAddress. accessToken must match backend zeroDayConfiguration.accessToken on clean install.
qubershipApihubUi.env + apihubUrl, ingress TLS UI env + public apihubUrl (keep equal to security.apihubExternalUrl).
qubershipApiLinterService.env Rendered as YAML into Secret config.yaml, mounted under /app/qubership-api-linter-service/etc/ with LINTER_CONFIG_FOLDER (qubership-api-linter-service-config-secret.yaml). Olric namespace/replicaCount patched from Helm.
qubershipApiLinterService.customCa Optional Kubernetes Secret mounted at /tmp/cert on the linter pod. Same qubership-core-base contract for HTTPS outbound calls to APIHUB and OpenAI. Set enabled: true and secretName.
qubershipApiLinterService.goMemLimit Pod env GOMEMLIMIT. Default 800MiB (~80% of default resource.memory.limit 1000Mi).
qubershipApihubAgentsBackend.env Rendered as YAML into Secret config.yaml, mounted under /app/qubership-apihub-agents-backend/etc/ with AGENTS_BACKEND_CONFIG_FOLDER (qubership-apihub-agents-backend-config-secret.yaml).
qubershipApihubAgentsBackend.customCa Optional Kubernetes Secret mounted at /tmp/cert on the agents-backend pod. Same qubership-core-base contract for HTTPS outbound calls to APIHUB and remote agents. Set enabled: true and secretName.
qubershipApihubAgentsBackend.goMemLimit Pod env GOMEMLIMIT. Default 205MiB (~80% of default resource.memory.limit 256Mi).

Default extensions URLs use cluster DNS (http://qubership-api-linter-service:8080, …); Compose substitutes host.docker.internal — keep both sides coherent.

Commands: Installation guide — Helm. Template reference: templates/qubership-*-deployment.yaml in the chart.

Custom CA Kubernetes Secret (Helm)

Section titled “Custom CA Kubernetes Secret (Helm)”

When customCa.enabled: true, create the Secret before helm install / helm upgrade. Each key under data or stringData becomes a filename under /tmp/cert (use .crt, .cer, or .pem suffixes). One Secret per service is typical; PEM contents may be identical across backend, linter, and agents-backend.

Backend — save as apihub-backend-custom-ca-secret.yaml, set namespace to your APIHUB release namespace, then kubectl apply -f apihub-backend-custom-ca-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: apihub-backend-custom-ca
  namespace: qubership-apihub
type: Opaque
stringData:
  company-root-ca.pem: |
    -----BEGIN CERTIFICATE-----
    # paste PEM body from your corporate CA
    -----END CERTIFICATE-----

Linter — same shape; change metadata.name to match qubershipApiLinterService.customCa.secretName (for example apihub-linter-custom-ca).

Agents-backend — same shape; change metadata.name to match qubershipApihubAgentsBackend.customCa.secretName (for example apihub-agents-backend-custom-ca).

Enable the mount in values.yaml (defaults keep enabled: false):

qubershipApihubBackend:
  customCa:
    enabled: true
    secretName: apihub-backend-custom-ca

Alternative: kubectl create secret generic apihub-backend-custom-ca --from-file=company-root-ca.pem=./company-root-ca.pem -n qubership-apihub.

MinIO/S3 endpoint CA stays in s3Storage.crt inside the backend config Secret — not in /tmp/cert.

3. Compose — which file to edit

Section titled “3. Compose — which file to edit”

Repository path: deploy/docker-compose/apihub-generic/ (standalone) and deploy/docker-compose/with-keycloak/ (Keycloak SSO example). The stack in deploy/docker-compose/backend-debug/ runs everything except the backend, so that you can debug the backend from an IDE.

File Service Role
qubership-apihub-backend-config.yaml Backend Mounted as config.yaml. Uses ${JWT_PRIVATE_KEY}, ${APIHUB_ACCESS_TOKEN}, ${APIHUB_ADMIN_EMAIL}, ${APIHUB_ADMIN_PASSWORD} for generate_env_and_up_compose.sh. extensions[].baseUrl must be reachable from browsers and backend (see Compose readme — often host.docker.internal).
certs/ (optional) Backend, linter, agents-backend Corporate CA .crt/.cer/.pem in certs/; uncomment ./certs:/tmp/cert:ro in docker-compose.yml. qubership-core-base /tmp/cert contract. MinIO/S3 CA stays in backend s3Storage.crt.
docker-compose.yml (qubership-apihub-backend environment) Backend APIHUB_CONFIG_FOLDER, GOMEMLIMIT (Go runtime soft limit; default 800MiB for Compose memory: 1G limit).
qubership-apihub-ui.env Portal UI Internal upstream addresses (APIHUB_BACKEND_ADDRESS, API_LINTER_SERVICE_ADDRESS, …).
qubership-apihub-build-task-consumer.env Builder APIHUB_API_KEY, APIHUB_BACKEND_ADDRESS. Compose uses host.docker.internal:8090 so the worker reaches the backend through the published host port.
qubership-api-linter-service-config.yaml Linter Mounted as config.yaml: DB, technicalParameters.apihub.{url,accessToken} (${APIHUB_ACCESS_TOKEN}), linters.spectral.*, linters.ai.*. Compose sets LINTER_CONFIG_FOLDER, GOMEMLIMIT (default 1600MiB for memory: 2G).
qubership-apihub-agents-backend-config.yaml Agents backend Mounted as config.yaml: DB, technicalParameters.apihub.{url,accessToken}, businessParameters.defaultWorkspaceId, security.*, cleanup.snapshots.*. Compose sets AGENTS_BACKEND_CONFIG_FOLDER, GOMEMLIMIT (default 205MiB for memory: 256M).
scripts/init-db/init.sql PostgreSQL init Creates users/DBs: apihub_backend, api_linter, agents_backend.

Secrets helper: generate_jwt_pkey.sh (JWT private key PEM → base64 for YAML), generate_env_and_up_compose.sh (random token/admin + envsubst). Important: running generate_env_and_up_compose.sh overwrites the processed .env files and every *-config.yaml with substituted values — use version control if you care about reproducible templates.

4. Cross-cutting token and URL consistency

Section titled “4. Cross-cutting token and URL consistency”

These must stay aligned across files/env:

  1. zeroDayConfiguration.accessToken (backend YAML) = APIHUB_API_KEY (builder env) = technicalParameters.apihub.accessToken (linter and agents-backend config.yaml) on greenfield Compose/Helm.
  2. security.apihubExternalUrl (backend) = public HTTPS/HTTP origin users open = apihubUrl (Helm UI) ≈ Compose example http://host.docker.internal:8081 (only for local desktops).
  3. technicalParameters.apihub.url for linter and agents backend is the Portal base URL reachable from inside their containers (http://qubership-apihub-ui:8080 in-cluster; http://host.docker.internal:8081-style patterns on Compose with published UI port).
  4. GOMEMLIMIT on Go backends (backend, linter, agents-backend) should stay below the container memory limit — chart and Compose defaults use ~80% of the paired resource.memory.limit / Compose deploy.resources.limits.memory. When you raise memory limits, update goMemLimit (Helm) or GOMEMLIMIT (Compose) in the same change.

MinIO (S3 storage)

Section titled “MinIO (S3 storage)”

The backend can keep relatively large binary files, such as build results, in MinIO or any other S3-compatible storage. Enable it with s3Storage.enabled in the backend config.yaml, and set s3Storage.url, s3Storage.username, s3Storage.password, and s3Storage.bucketName. Set s3Storage.crt when the endpoint uses a private CA. s3Storage.storeOnlyBuildResult limits the storage to build results. The config.template.yaml describes every option.

The backend reaches MinIO through the S3 API. You can also browse the buckets in the MinIO web console. Take the console credentials from the backend’s Kubernetes secret if you have access to the cluster.

5. Where to drill deeper by topic

Section titled “5. Where to drill deeper by topic”
Topic Prefer
Auth / SAML / OIDC model Backend security-model.md, security.externalIdentityProviders in config.template.yaml
Data retention / cleanup jobs Backend cleanup section + data-maintenance
End user workflows Portal & Agents Markdown guides (Portal User Guide, Agent User Guide) + design items