Configure Your Deployment#
Use values files to express your deployment choices. The complete reference is the selected chart’s values.yaml and values.schema.json; this page explains how the important groups fit together. Set BASYX_CHART_VERSION using version selection first.
Inspect the version you actually install#
helm show chart basyx/basyx --version "${BASYX_CHART_VERSION:?Select a chart version first}"
helm show values basyx/basyx --version "${BASYX_CHART_VERSION:?Select a chart version first}" > values.defaults.yaml
In the chart repository, select tag basyx-<your chart version> and use its README, charts/basyx source, and values examples together. The repository’s main branch may already document features that are not in your installed chart. For example, download an observability overlay matched to your selection:
curl --fail --location \
"https://raw.githubusercontent.com/eclipse-basyx/charts/basyx-${BASYX_CHART_VERSION:?Select a chart version first}/values/values.observability.example.yaml" \
--output values.observability.yaml
If the file is unavailable for an older release, inspect that release’s available profiles instead of substituting an example from main.
Choose a deployment shape#
Need |
Starting profile in the chart repository |
Important distinction |
|---|---|---|
One combined API runtime and the Web UI |
|
Enables |
Separate core Go services |
|
Unsecured evaluation profile. Individual services share the configured database. |
Keycloak and ABAC |
|
Replace demo credentials and verify the actual access policy. |
BaSyx Studio as the user interface |
|
Review that release’s Studio storage, identity, and app-origin requirements. |
Catena-X marker-based access example |
|
A specific DTR/Submodel Repository scenario, not a declaration of production compliance. |
Existing PostgreSQL |
|
Configure database connection and migration ownership explicitly. |
Database sizing/scheduling |
|
Tune to your storage, nodes, workload, and connection budget. |
Gateway API |
|
Requires Gateway API CRDs and a functioning controller/Gateway. |
Logs/traces or autoscaling |
|
Overlays, not complete deployment profiles. |
The sample files are stored in the Git repository; helm show values shows chart defaults, not all repository examples.
How overrides work#
Helm combines the chart defaults with your values. Later files override earlier ones, and command-line --set options override files. Maps can be overridden by key; lists are replaced rather than merged item by item.
For example:
helm template basyx basyx/basyx --version "${BASYX_CHART_VERSION:?Select a chart version first}" \
--namespace basyx-evaluation \
-f values.cluster-base.yaml -f values.cluster.yaml -f values.observability.yaml
This continues the installation walkthrough: load its downloaded base profile first, your cluster-specific overlay second, and any additional overlay last. Only add an observability file that you have created or copied from the matching chart release. Keep environment-specific files small enough to review. Save the full intended configuration for later upgrades instead of relying on remembered --set arguments or blindly reusing old values.
Main configuration groups#
Values |
Responsibility |
|---|---|
|
Browser-facing host and public service routes. |
|
Controller class, annotations, and routing for Ingress. |
|
Alternative Gateway API routing. |
|
Ingress certificates, issuer resources, and outbound CA trust. These are separate concerns. |
|
Managed or external PostgreSQL connections and storage settings. |
|
Schema initialization/migration Job and hook behavior. |
|
Whether to deploy a component. Disabling a service does not migrate or erase its data. |
|
Container image tag or digest. Empty tags for Go runtimes resolve to the chart’s |
|
CPU and memory requests/limits for that component; configured independently for each workload. |
|
Structured Go runtime configuration; use the selected release’s schema for the exact keys. |
|
Explicit environment overrides. They may take precedence over structured runtime values. |
|
Which APIs the Web UI uses and how it signs in. |
|
Identity provider, authorization policies, and trusted token issuers. |
CPU and memory requests and limits#
Resource requests and limits can be configured in your cluster-specific values overlay. Set them separately for each enabled component using its resources block, for example aasEnvironment.resources, aasWebGui.resources, or configurationService.resources. For the managed PostgreSQL instances, use database.resources. Check the selected release’s values.yaml for the available components and any additional resource blocks for init containers or poolers. There is no single global resource setting for all workloads.
The following example illustrates the syntax, not recommended production sizing. Merge the relevant blocks into values.cluster.yaml alongside your existing settings:
aasEnvironment:
resources:
requests:
cpu: 250m
memory: 256Mi
limits:
cpu: "2"
memory: 1Gi
aasWebGui:
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: "1"
memory: 512Mi
250m means one quarter of a CPU core; Mi and Gi are binary memory units. Requests inform Kubernetes scheduling and resource allocation; they are not usage caps. CPU limits can throttle a busy container, while exceeding a memory limit can cause it to be terminated (OOMKilled). Keep requests less than or equal to the corresponding limits. Limits are optional: decide whether to cap CPU according to your platform policy and latency requirements rather than copying an example unchanged.
Size each workload from observed usage and load tests, allowing headroom for startup and peak traffic. Settings apply per pod/container, so account for replicas and other enabled components when planning node capacity. Empty resources: {} blocks do not explicitly set requests or limits in the chart; namespace LimitRange defaults and ResourceQuota restrictions may still apply. Application memory settings, such as a JVM heap, are separate from the container memory limit and must leave room for other memory usage.
Render and lint your merged values as described in configuration checks, then apply them through the values-only upgrade procedure. Verify the resulting pod specifications and monitor resource usage after rollout. Updating Deployment resource settings normally replaces pods; plan for possible interruption in single-replica deployments.
Web UI addresses and component selection#
The browser calls the API URLs stored in the UI’s infrastructure configuration. These must be reachable from the browser, not only from another pod. A URL such as http://basyx-aas-registry:8080 is normally not suitable for an external user’s browser.
The minimal profile maps UI operations to AAS Environment endpoints, including /shells and /submodels. A split deployment instead maps them to the respective services. For same-host HTTPS ingress, the defaults derive addresses from host and paths.*.
Check the rendered infrastructure after changing component selection. The combined AAS Environment still provides Registry and Discovery APIs even when the separate workloads are disabled. Disabling aasRegistry therefore does not mean that all references to its API area should be deleted from a combined AAS Environment setup. Consult the selected release’s Web UI configuration guidance for how it handles disabled services and explicit external URLs.
Disabling Keycloak alone does not disable the Web UI’s sign-in settings. An unsecured profile must also set the infrastructure’s security.type to None, as the minimal cluster profile does. For secured configurations, see security.
Managed or external PostgreSQL#
The default managed database uses CloudNativePG. Choose database.instances, database.storage.size, and optionally database.storage.storageClass for your platform. The instance count does not replace a backup strategy.
For external PostgreSQL, the chart can reference an existing Secret:
database:
type: external
existingSecret: basyx-postgres
The Secret must already exist in the release namespace with these keys: host, port, dbname, user, password, and jdbc-uri. Store it through your approved secret-management process. Optional TLS settings and component-specific database overrides are described in the chart reference.
The Configuration Service also needs the intended database connection. Do not point it at an unrelated database or silently disable it: Go runtimes require a compatible, clean schema. External database deployment, connectivity, permissions, and backups remain the database operator’s responsibility.
Repository-to-Registry integration is not automatic HTTP synchronization between two pods. Review the shared-database integration contract before splitting services across different databases.
Images and custom files#
Prefer the chart’s compatible image set initially. When overriding it, keep the Configuration Service compatible with every runtime using its database. Set image digests when immutable image selection is required.
Chart-local logos and certificate files are read from the chart package/checkout with Helm’s file access. Placing an arbitrary file beside your values file does not put it inside the chart. For certificates outside the chart package, use the supported existing Secret/ConfigMap trust-store references instead of assuming Helm can read any local path.
Next: Security and production readiness, advanced deployment, or operations.