Skip to main content

Helm Deployment and Updates

The supported ACP Engine Helm chart installs the application workloads and coordinates first-install database bootstrap, ordered upgrades, verification, and release version reporting. Use the chart packaged with the application release; do not combine templates, migration files, or operational images from different releases.

Release components​

The chart deploys Manager, Engine, MCP, Auth, Runtime, AI, Catalog, Usage, Enrichment, Data, and the configured platform dependencies. Manager, Engine, and the public MCP endpoint may be exposed through separate TLS ingresses. Domain services and data stores should remain private.

Safe Zone is delivered and operated separately unless the supplied deployment package explicitly says otherwise.

Before installation​

Confirm that the target environment provides:

  • a supported Kubernetes cluster and a CNI that enforces NetworkPolicy;
  • persistent storage for every bundled stateful component;
  • DNS and TLS names for the public Manager, Engine, and MCP endpoints;
  • an ACP PostgreSQL database or approval to use the bundled database profile;
  • an approved Secret-management method;
  • immutable ACP image digests and the supplied registry pull credential;
  • backup and point-in-time recovery appropriate to the database;
  • the stable ACP license installation ID and licensing configuration.

Keep customer-specific hostnames, credentials, tenant configuration, Flows, prompts, and routing in protected deployment values, Secrets, or Manager. Do not edit shared chart templates for a customer installation.

Secrets and customer values​

Production deployments should use secrets.create=false with a pre-provisioned Kubernetes Secret or an approved external secret controller:

secrets:
create: false
name: acp-engine-secrets

registryCredentials:
enabled: true
create: false
name: acp-engine-registry

The delivered values reference documents the required Secret keys. Do not pass database URLs, API keys, registry tokens, license activation material, or encryption keys with --set; Helm retains release values.

Use a private, access-controlled values file for non-secret environment configuration:

config:
licenseMode: online
licenseServerUrl: https://license.thyris.cloud
licenseInstallationId: <stable-installation-id>
licenseProductKey: acp-engine

managerIngress:
enabled: true
hosts:
- host: manager.example.com
paths:
- path: /
pathType: Prefix

ingress:
enabled: true
hosts:
- host: engine.example.com
paths:
- path: /
pathType: Prefix

mcpIngress:
enabled: true
hosts:
- host: mcp.example.com
paths:
- path: /
pathType: Prefix

See ACP Engine Licensing for activation and supported license modes.

Images​

Customer releases should use the repository mapping and digest manifest delivered with that release. A digest, not a mutable tag, is the deployment identity. Keep registry credentials outside the chart release whenever possible.

If the package includes a signature admission policy, enable it only after the corresponding public verification key and signed image evidence have been validated. An unsigned image cannot be described as signature-enforced merely because a policy template exists.

First installation​

The chart runs one schema-bootstrap Job. It inspects the target database before starting application workloads:

  • An empty database receives the canonical baseline and a migration ledger.
  • A database already initialized by the same release is verified.
  • A partial, incompatible, or untracked ACP schema is reported and rejected without replaying init.sql.

This prevents replica races and prevents a first Helm installation from silently repairing customer-owned data. Do not place bootstrap logic in each service container.

Install using the exact release package and customer values:

helm upgrade --install acp-engine ./deployment/helm-chart \
--namespace acp-engine \
--create-namespace \
-f CUSTOMER_VALUES.yaml \
-f RELEASE_IMAGE_VALUES.yaml \
--wait

File names above are placeholders for the protected customer values and the digest-locked image manifest delivered through the approved channel.

Mandatory update sequence​

Every feature release follows the same four gates, whether or not its headline change mentions the database:

  1. Preflight performs a read-only schema and migration-ledger inventory.
  2. Approved change applies only packaged, immutable forward migrations and records the approved backup/PITR reference.
  3. Verify requires zero canonical schema gaps, pending migrations, or checksum mismatches.
  4. Workload rollout begins only after verification succeeds.

Take and verify a database snapshot or PITR checkpoint before the change. Run the release-matched migration plan through the supplied acpctl image or the customer's approved external pipeline. Then perform the upgrade with the reviewed backup reference:

helm upgrade --install acp-engine ./deployment/helm-chart \
--namespace acp-engine \
-f CUSTOMER_VALUES.yaml \
-f RELEASE_IMAGE_VALUES.yaml \
--set migration.mode=apply \
--set-string migration.backupReference=CHANGE_OR_SNAPSHOT_REFERENCE \
--wait

The preflight Job logs each schema gap and each applied or pending migration. The migration Job takes a PostgreSQL advisory lock and applies every pending migration in its own transaction. The verify Job blocks the Helm upgrade if the target boundary is not exact.

Collect update evidence before closing the change:

kubectl -n acp-engine logs job/acp-engine-schema-preflight \
-c migration-preflight
kubectl -n acp-engine logs job/acp-engine-schema-preflight \
-c schema-preflight
kubectl -n acp-engine logs job/acp-engine-schema-verify \
-c schema-doctor
kubectl -n acp-engine logs job/acp-engine-schema-verify \
-c migration-verify
kubectl -n acp-engine get jobs \
-l app.kubernetes.io/component=schema-update --show-labels

Job names use the Helm release fullname. Replace acp-engine when the release name or fullname override differs.

External database pipelines​

If database lifecycle is controlled outside Helm, the external pipeline must perform equivalent preflight, immutable migration, and blocking verification before application workloads change. Set updatePolicy.enabled=false only with a non-secret updatePolicy.externalControllerReference identifying that approved pipeline or change record.

Disabling the built-in Jobs is not an exception to the update policy.

Databases without a migration ledger​

An existing database created before the migration ledger is reported as UNTRACKED; automatic apply refuses to mutate it. Inventory the schema, review the environment-specific diff, and confirm backup/PITR evidence first.

Only then may an authorized operator use migration.allowUntrackedBaseline=true for one approved run. Remove it immediately afterward. It is not a general drift-repair switch.

Versions in Manager​

Platform administrators can open Updates & Versions from the main Manager dashboard. The page shows:

  • the running ACP application version;
  • the packaged database target and actual migration-ledger boundary;
  • the update-policy version;
  • the most recent migration entries and their release references;
  • whether the database is current, behind, ahead, drifted, or untracked.

The footer displays the same running application version. This screen is read-only operational evidence; it does not replace retained preflight, backup, migration, verify, or post-rollout evidence.

Database statusMeaningOperator response
CurrentLatest migration and packaged count match the running application.Continue with normal post-update validation.
Update requiredThe database is behind the packaged application boundary.Stop workload promotion and run the approved update sequence.
Newer than applicationThe database contains a migration newer than the application expects.Stop rollback or promotion until compatibility is reviewed.
Ledger driftThe latest version matches but migration count/history does not.Inspect immutable release assets and ledger evidence; do not edit the ledger manually.
UntrackedThe migration ledger is missing.Perform a read-only inventory and the approved one-time baseline review.

Footer license information is independent of the database status. It is read from the local License Service and refreshes automatically; a blocked license and a database version mismatch are separate release gates.

Failure and rollback​

If preflight or verify fails, stop the release and inspect the Job logs. Do not edit a shipped migration, manually mark it complete, replay init.sql, or enable the untracked-baseline override as a shortcut.

ACP migrations use additive expand/migrate/contract changes so the prior application image can remain compatible during a controlled workload rollback. A Helm rollback does not automatically reverse database changes. Confirm the release-specific compatibility statement before rolling application images back; restore the database only through the approved recovery procedure.

Post-update checks​

After the rollout:

  1. Confirm the Helm release and every ACP workload are healthy.
  2. Confirm Updates & Versions reports the expected application version and a current database boundary.
  3. Validate license status and the Manager, Engine, and MCP health surfaces.
  4. Run the release-specific API and business-flow smoke tests.
  5. Review alerts, logs, and error rates before completing the change.
  6. Retain the rendered values fingerprint, image digests, Job logs, backup reference, verification result, and operator/change reference.

Network and exposure​

The chart is default-deny when NetworkPolicy is enabled. New external systems require an explicit, narrow egress rule. Public URLs configure links and service routing; they do not create DNS records, certificates, firewalls, or provider load balancers.

Keep PostgreSQL, Redis, OpenSearch, internal domain services, Prometheus, and Alertmanager private unless a separately approved architecture requires exposure. Use TLS, authentication, retention, backup, and high-availability settings appropriate to the target environment.