Bundle and CRD reference
Bundle fields, the reconcile / deletion / import-export semantics, and the CRDs PackingTable installs itself.
PackingTable's CRDs at a glance
All CRs use apiVersion: fewbox.com/v1.
| Kind | Scope | Purpose | Created by |
|---|---|---|---|
Tenant |
Namespaced | Records a tenant: spec.logo, spec.domains, spec.registry. A record only, with no controller — the namespace, ServiceAccount and Gateway are created by tethys-shipping through POST /api/v1/tenants |
Console "Add tenant"; applying one by hand only creates the record, nothing else |
Bundle |
Namespaced | Declares "which applications/jobs should run in this tenant"; this is the focus of this document | Console export/import, or apply by hand |
Infrastructure |
Namespaced | Environment-level infrastructure (NFS, RabbitMQ operator, MySQL operator) | Environment install script/console |
Middleware |
Namespaced | Middleware instances (version, storage and password of RabbitMQ, Verdaccio, PostgreSQL, Redis) | Environment install script/console |
Registry |
Cluster-scoped | Image registry address and default tag; the operator reads it when materializing pull secrets | Pre-installed on the platform side (the operator does not install it) |
A Bundle depends on the tenant prerequisites already being in place: the namespace, the ServiceAccount <tenant>, the ServiceAccount fewbox (used by packs with isRunAsClusterAdmin) and the Istio Gateway internet
must all exist before you apply, because the applications in the Bundle run as them. The checklist is in
"One-click deployment / tenant prerequisites".
Deleting the Tenant CR does not clean up the namespace — it has no controller, so tear the applications and the namespace down yourself.
Bundle format
9.1 Skeleton
A Bundle is a namespaced resource, metadata.namespace is the target tenant; every application in the bundle belongs to that tenant,
so the tenant is not repeated inside the pack. One tenant can have multiple Bundles, but do not declare the same application name twice.
apiVersion: fewbox.com/v1
kind: Bundle
metadata:
name: <bundle-name>
namespace: <tenant> # target tenant namespace
spec:
isRetainOnDelete: false # whether to keep the applications below when the Bundle is deleted
packs: [] # applications without config files
customPacks: [] # applications with 1..n config file mounts
standardTaskPacks: [] # one-off tasks
customStandardTaskPacks: []
scheduledTaskPacks: [] # scheduled jobs
customScheduledTaskPacks: []
The only difference between packs and customPacks, or between single-config and multi-config task packs, is "whether there is a config file"; the same application must not appear in
both groups at once.
9.2 Fields common to all packs
| Field | Type | Description |
|---|---|---|
registry |
string | Image prefix, no trailing slash. When empty, the image degrades to <app>:<version> |
app |
string | Application name, which is also the Deployment/Service name. Must equal the image repository name (see the known limitations in 9.9) |
version |
string | Image tag, usually starting with v (e.g. v1.2.3). It is not the version identity |
releaseVersion |
string | Version identity, in the form v3; determines the Deployment name (<app>-v3), the version/release labels and the Istio subset. Can be omitted; when omitted it is inferred by truncating version at the first dot (v3.1 → v3) |
runtimeVariables |
array | Runtime environment variables, see 9.3 |
imagePullSecret |
string | Name of the Secret used to pull images, not its contents |
isIgnore |
bool | When true, skip this pack; used to temporarily take an application offline |
There is only one rule for assembling the image string:
registry empty → {app}:{version}
registry non-empty → {registry}/{app}:{version}
imagePullSecret handling works together with it:
- The operator first matches the pack's
registryagainst the cluster'sRegistryCRs, finds the platform credential, and materializes a pull Secret in the target tenant (the name is generated by platform rules). - If the pack explicitly sets
imagePullSecretand that name really exists in the target tenant, the user's choice is respected. - If the name does not exist (typical for a cross-cluster import), the freshly materialized Secret is used instead; if no platform credential matches, it only warns and
the application is still created, but the Pod may go into
ImagePullBackOff.
So the exported file contains only Secret names, never credential contents; whether a cross-environment import heals itself depends on whether the target cluster has credentials for the corresponding registry pre-installed.
9.3 runtimeVariables
runtimeVariables:
- name: LOG_LEVEL
value: info
source: Manual
- name: DATABASE_URL
value: ""
source: Secret
secretName: <tenant-secret-name>
secretKey: DATABASE_URL
| Field | Description |
|---|---|
name |
Variable name injected into the container |
value |
Plaintext value when source: Manual |
source |
String enum: Manual (default) or Secret. It must be a string; writing 0/1 is rejected by the apiserver |
secretName / secretKey |
With source: Secret, reference an existing Secret in the target tenant and one of its keys; value is ignored |
Secret sources store only references; credential contents never travel with the Bundle.
9.4 Pack and CustomPack
The two have essentially the same fields; the difference is whether there is a settings.
| Field | Applies to | Description |
|---|---|---|
replicas |
Both | Replica count; setting 1 explicitly is recommended |
isPublic |
Both | When true, expose the application (create/update a VirtualService) |
publicPrefix |
Both | Public path prefix; when empty, the platform default is used |
isRunAsClusterAdmin |
Both | When true, start with the fewbox ServiceAccount (for applications that need extra cluster permissions) |
supplyMode |
Both | String enum OnDemand / RealTime / Offline; invalid or empty is treated as OnDemand |
command |
Both | Override the image's start command (array) |
isWaitingForNetwork |
Both | Wait for the network to be ready at startup |
isRawNetwork |
Both | Use a direct network without sidecar interception |
settings |
CustomPack only | Array of config file mounts, see 9.5 |
A plain Pack does not mount config files. Even if you write a settingsTemplate, the Bundle reconcile will not pass it to Launch;
to mount config files, put them in customPacks. Console export groups them by the same rule.
9.5 settings: config file mounts
Both customPacks[].settings and custom*TaskPacks[].settings are arrays of ConfigFileMountTemplate:
settings:
- name: agentic.yaml
path: /app/config/agentic.yaml
source: Manual
mountMode: SingleFile
settingsTemplate: <base64-of-file-content>
settingsVariables:
MODEL_ENDPOINT: https://<model-api>
- name: credentials
path: /app/secrets
source: Secret
secretName: <tenant-secret-name>
mountMode: Directory
| Field | Description |
|---|---|
name |
Mount entry name. With mountMode: SingleFile it is also the key in the Secret |
path |
Absolute path inside the container |
source |
String enum: Manual (inline content) or Secret (reference an existing Secret) |
secretName |
Required with source: Secret; it is the Secret name in the target tenant |
mountMode |
SingleFile (default, a single file) or Directory (mount the whole Secret as a directory) |
settingsTemplate |
With source: Manual, the file content as UTF-8 base64; leave empty for a Secret source |
settingsVariables |
Key-value pairs; after base64 decoding, a plain string replacement is done on the content (Replace(key, value)), not shell expansion and not environment variable substitution |
settingsVariables is commonly used for "keep ${VAR} placeholders in the template and only swap addresses when importing into a different environment".
The replacement happens before mounting, so the placeholders are replaced with literal values directly in the final file.
9.6 Task packs
| Type | Fields | Description |
|---|---|---|
standardTaskPacks |
command, settingsTemplate, settingsVariables |
One-off Job; when command is empty, the image's default ENTRYPOINT is used |
customStandardTaskPacks |
the same + settings[] |
One-off Job that can mount multiple config files |
scheduledTaskPacks |
schedule, command, settingsTemplate, settingsVariables |
Scheduled CronJob; schedule is a standard cron expression |
customScheduledTaskPacks |
the same + settings[] |
Scheduled CronJob that can mount multiple config files |
Task packs also support runtimeVariables, imagePullSecret, isRawNetwork, isIgnore; they do not create a long-running Deployment, and
the corresponding Job/CronJob is removed when the Bundle is deleted.
9.7 Reconcile semantics
The Bundle controller is convergent: each reconcile moves the current state toward the declaration, rather than "running a deployment script once".
| Current state | Action |
|---|---|
| No Service for this application in the tenant | Launch: create the Service/Deployment from the pack (isRunAsClusterAdmin decides which ServiceAccount to use) |
A Service exists, but not the <app>-<release> Deployment |
UpgradeMajor to the target image, then Promote (switch traffic to the new version; the old version is scaled to 0 replicas but kept) |
<app>-<release> already exists |
Treated as ready, left alone — within the same major version, changing only version and applying again is a no-op |
isPublic: true |
Every reconcile ensures the VirtualService points at the application (the default is used when publicPrefix is empty) |
Meaning and boundaries:
- Configuration changes do not converge. Changes to
runtimeVariables/settingson an existing Deployment do not trigger reconfiguration; runtime tweaks go through the console's reconfigure/merge feature. The Bundle only governs "does it exist, and is it this version". - Upgrades require an increasing identity, and the identity is a DNS label.
UpgradeMajorrequires the version identity to matchv\d+and be greater than the current identity; a value with a dot is an image tag, and putting it inreleaseVersionis rejected (the Istio subset does not accept dots). If this is not met, the Bundle entersFailed. Therefore a Bundle cannot be used to roll back — rollback goes through the console's "revert". - If any pack throws, the whole Bundle is marked failed and retried after 30 seconds; applications that already succeeded are not rolled back.
- Removing a pack from a Bundle does not automatically take the corresponding application offline; either delete the Bundle and let it run its finalizer, or take the application offline manually in the console.
9.8 Status and conditions
status is written back explicitly by the operator:
status:
phase: Ready # Pending → Provisioning → Ready / Failed
message: <failure-text>
observedGeneration: <generation>
conditions:
- type: BundleReady # all packs deployed
status: "True"
reason: BundleDeployed
- type: Reconciled # result of this reconcile
status: "True"
reason: ReconcileSucceeded
When troubleshooting, look at status.phase and status.message first, then at the reason in the conditions. When phase: Failed and the message mentions
upgrade failed, check the version tag rules and whether the image exists first.
9.9 Deletion semantics
A Bundle carries the finalizer fewbox.com/bundlefinalizer. On deletion:
isRetainOnDelete |
Behavior |
|---|---|
true |
Keep all deployed applications and tasks; delete only the Bundle itself |
false (default) |
Shutdown each application (delete Deployment/Service); for isPublic ones also delete the VirtualService; task packs clear the corresponding Job/CronJob |
When the tenant namespace is deleted, the Bundles in it run their own finalizers first, then disappear along with the namespace. If a CR is stuck in
Terminating, it is usually because the finalizer name does not match the registered name (in KubeOps 10 the finalizer name is always
{group}/{lowercased class name}).
9.10 Console export/import
Export (select multiple in the microservice list → export Bundle):
- Group by tenant, generating one Bundle per tenant;
metadata.namespaceis the source tenant. - Each application's image is split into
registry+app+version;registrycan be overridden uniformly at export time. - Applications with config file mounts go into
customPacks, the rest intopacks. - Config content is written into
settingsTemplateas base64; mounts and runtime variables from a Secret source export onlysecretName/secretKey, the content is not exported. imagePullSecretwrites the name only.isRetainOnDeleteis decided by the export dialog.
Import (Kits/Bundles page → paste YAML):
- Only documents with
kind: Bundleare processed; other kinds are ignored. - Each source tenant is mapped to a target tenant, and
metadata.namespaceis rewritten after mapping; when different source tenants map to the same target, Bundles with the same name are treated as a conflict and rejected. - The whole YAML is submitted to the gateway as one GraphQL variable, subject to two limits:
GRAPHQL_BODY_LIMIT(default 10mb) and the edge nginxclient_max_body_size(default 1MB); exceeding either shows up as 413.
Known limitations:
appmust equal the image repository name. When a cloned microservice's app name differs from its image name, the exported image string is assembled incorrectly and the image cannot be pulled after import.- Secret contents do not travel with the file. The target environment must already have a config Secret with the same name, or you must create it in the target tenant first; platform registry credentials can be materialized automatically, but business config Secrets are not.
settingsVariablesis not exported. If the source environment's config file relies on runtime replacement, the exported file contains only the base64 original, and you need to add the replacement table back in the YAML.- The same version is treated as ready. Trying to change configuration or replica count with a Bundle will not take effect, see 9.7.
- The version must increase. Using a Bundle to "roll back to an old version" will not succeed; rollback goes through the console's version switch.
- Import does not create tenants. The namespace, the ServiceAccounts and the
Gateway internetmust already exist, see tenant prerequisites. - The import dialog closes immediately after submission; a failed save (for example 413 or a validation error) is only written to the browser console and shows no error prompt.
After importing a large file, go to the Bundle list and confirm
phase.
9.11 A sanitized example
The snippet below shows the field shape only. A complete, sanitized export from a reference environment —
21 applications, with customPacks, several Secret references and the field combinations that actually occur —
is in Sample manifests.
apiVersion: fewbox.com/v1
kind: Bundle
metadata:
name: example-suite
namespace: <tenant>
spec:
isRetainOnDelete: false
packs:
- registry: registry.example.com/example
app: example-web
version: v1.2.3
replicas: 2
isPublic: true
publicPrefix: /
supplyMode: RealTime
runtimeVariables:
- name: LOG_LEVEL
value: info
source: Manual
- name: SESSION_TOKEN
value: ""
source: Secret
secretName: <tenant-secret-name>
secretKey: SESSION_TOKEN
customPacks:
- registry: registry.example.com/example
app: example-agent
version: v2.0.0
replicas: 1
isPublic: false
command: ["node", "dist/index.js"]
runtimeVariables:
- name: DATABASE_URL
value: ""
source: Secret
secretName: <tenant-secret-name>
secretKey: DATABASE_URL
settings:
- name: agentic.yaml
path: /app/config/agentic.yaml
source: Manual
mountMode: SingleFile
settingsTemplate: <base64-of-file-content>
settingsVariables:
MODEL_ENDPOINT: https://<model-api>/api/v3
- name: credentials
path: /app/secrets
source: Secret
secretName: <tenant-secret-name>
mountMode: Directory
standardTaskPacks:
- registry: registry.example.com/example
app: example-migrate
version: v2.0.0
command: ["/app/migrate", "--yes"]
scheduledTaskPacks:
- registry: registry.example.com/example
app: example-tick
version: v2.0.0
schedule: "0 * * * *"
command: ["/app/tick"]