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:
- Preflight performs a read-only schema and migration-ledger inventory.
- Approved change applies only packaged, immutable forward migrations and records the approved backup/PITR reference.
- Verify requires zero canonical schema gaps, pending migrations, or checksum mismatches.
- 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 status | Meaning | Operator response |
|---|---|---|
Current | Latest migration and packaged count match the running application. | Continue with normal post-update validation. |
Update required | The database is behind the packaged application boundary. | Stop workload promotion and run the approved update sequence. |
Newer than application | The database contains a migration newer than the application expects. | Stop rollback or promotion until compatibility is reviewed. |
Ledger drift | The latest version matches but migration count/history does not. | Inspect immutable release assets and ledger evidence; do not edit the ledger manually. |
Untracked | The 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:
- Confirm the Helm release and every ACP workload are healthy.
- Confirm Updates & Versions reports the expected application version and a current database boundary.
- Validate license status and the Manager, Engine, and MCP health surfaces.
- Run the release-specific API and business-flow smoke tests.
- Review alerts, logs, and error rates before completing the change.
- 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.