> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/bundle.md). # Bundle A Bundle is a DataOS Resource that deploys a collection of Resources in one operation. Use a Bundle to package the resources that make up an application, test, or Data Product so they can be applied, verified, and deleted together. As its name suggests, a Bundle groups resources into a flattened directed acyclic graph (DAG). Each resource in the Bundle is a node, and dependency rules define the order in which resources are created. {% hint style="info" %} A Bundle is an instance-level Resource. The resources referenced by the Bundle can be instance-level or workspace-level resources. {% endhint %} ## Prerequisites To create a Bundle, you need a tenant-specific role (**Tenant Admin** or **Data Developer**). To use a Bundle, you need resource-specific permission granted by the Bundle owner. ## Why use a Bundle Use a Bundle when you need to: * Deploy multiple related Resources in a single operation. * Define dependencies between Resources. * Wait for a Resource to become active or running before deploying the next Resource. * Package verification Workflows with the Resources they validate. * Keep deployment logic in source control for review and CI/CD. * Delete a grouped set of Resources in a controlled order. Common examples include a Worker with a verification Workflow, a Service with a Secret and verification Workflow, or a Data Product deployment that includes Depots, Secrets, Workflows, Services, and Monitors. ## Manifest structure A Bundle manifest uses the common Resource metadata fields and a `bundle` section that defines the resources to deploy. {% tabs %} {% tab title="Syntax" %} ```yaml version: v2alpha name: ${{bundle-name}} type: bundle description: ${{description}} tags: - ${{tag}} bundle: resources: - id: ${{resource-id}} file: ${{resource-manifest-path}} dependencies: - ${{dependency-resource-id}} dependencyConditions: - resourceId: ${{dependency-resource-id}} status: is: - ${{expected-status}} contains: - ${{expected-status-fragment}} runtime: is: - ${{expected-runtime}} contains: - ${{expected-runtime-fragment}} ``` {% endtab %} {% tab title="Example" %} ```yaml version: v2alpha name: test-worker-sleep type: bundle description: "Integration test: deploy a minimal long-running worker and verify pod runtime is running" tags: - test - worker - container bundle: resources: - id: sleep-worker file: tests/worker/sleep-worker/worker.yaml - id: verify-sleep-worker file: tests/worker/sleep-worker/verify-workflow.yaml dependencies: - sleep-worker dependencyConditions: - resourceId: sleep-worker status: is: - active runtime: contains: - "running" ``` {% endtab %} {% endtabs %} ## Core concepts ### Resources `bundle.resources` lists the resources that belong to the Bundle. Each resource entry needs an `id` so other entries can reference it. ```yaml bundle: resources: - id: sleep-worker file: tests/worker/sleep-worker/worker.yaml ``` Use `file` when the Resource is defined in a separate manifest. This keeps each Resource reusable and easier to review. ### Dependencies `dependencies` defines the resource IDs that must be processed before the current resource. ```yaml bundle: resources: - id: verify-sleep-worker file: tests/worker/sleep-worker/verify-workflow.yaml dependencies: - sleep-worker ``` Dependencies create the Bundle DAG. A verification Workflow, for example, should depend on the Worker or Service it verifies. ### Dependency conditions `dependencyConditions` controls when a dependent Resource is ready. Conditions can check the dependent Resource status, runtime state, or both. ```yaml bundle: resources: - id: verify-sleep-worker file: tests/worker/sleep-worker/verify-workflow.yaml dependencies: - sleep-worker dependencyConditions: - resourceId: sleep-worker status: is: - active runtime: contains: - "running" ``` In this example, the verification Workflow is applied only after `sleep-worker` is active and its runtime contains `running`. ### Workspace placement Use `workspace` on a Bundle resource entry when the referenced Resource must be created in a specific workspace. ```yaml bundle: resources: - id: worker-in-sandbox workspace: sandbox file: tests/worker/sleep-worker/worker.yaml ``` Workspace-level resources, such as Workers, Workflows, Services, and Secrets, can be placed in workspaces. Instance-level resources are not scoped to a workspace. ### Inline specifications Use `spec` when you want to define a Resource inline in the Bundle instead of referencing a file. ```yaml bundle: resources: - id: inline-worker spec: version: v2alpha name: sleep-worker type: worker spec: compute: runnable-default replicas: 1 executionMode: default stack: container stackSpec: image: docker.io/library/alpine:3.20 command: - sh arguments: - -c - "while true; do echo heartbeat; sleep 30; done" ``` For most production bundles, separate files are easier to maintain than large inline resource definitions. ### Schedule, properties, and management user Bundles can also include optional sections for scheduled create/delete operations, workspace creation, custom properties, and management user context. ```yaml bundle: schedule: initialState: create timezone: Asia/Kolkata create: - cron: "5 0 24 1 *" delete: - cron: "25 0 24 1 *" workspaces: - name: bundlespace description: "Workspace for bundled resources" tags: - bundle labels: purpose: testing layer: user properties: purpose: integration-test manageAsUser: iamgroot ``` Use these sections only when the Bundle needs them. Simple Bundles often contain only `bundle.resources`. ## Examples ### Deploy a Workflow with a Bundle You can package a Workflow inside a Bundle. A **Bundle** is a wrapper that groups resources together. A Bundle can include the following as part of the deployment: * a **Workflow,** a **Service,** a **Worker** * other resources like **Secrets**, **Depots**, and **Volumes** So the relationship is: * **Bundle** manages resource packaging and deployment order * **Workflow / Service / Worker** manages runtime behavior * **Stacks** provide the actual execution environment Example: ```yaml version: v2alpha name: workflow-bundle type: bundle description: Bundle for deploying a basic workflow bundle: resources: - id: data-processing-job file: workflow.yaml ``` ### Bundle-based orchestration ```yaml # Bundle that orchestrates multiple resource types version: v2alpha name: complete-data-platform type: bundle description:"Complete data platform with API, processing, and monitoring" bundle: resources: # Phase 1: Deploy supporting infrastructure -id: customer-database file: artifacts/depots/postgres/create-postgres-depot.yaml -id: storage-volume file: artifacts/volumes/data-storage-volume.yaml # Phase 2: Deploy processing services -id: customer-api file: artifacts/services/customer-api-service.yaml dependencies:[customer-database] dependencyConditions: -resourceId: customer-database status:{is:[active]} # Phase 3: Deploy batch processing -id: nightly-etl file: artifacts/workflows/customer-etl-workflow.yaml dependencies:[customer-database, customer-api] dependencyConditions: -resourceId: customer-database status:{is:[active]} -resourceId: customer-api status:{is:[active]} # Phase 4: Deploy continuous monitoring -id: event-monitor file: artifacts/workers/event-monitoring-worker.yaml dependencies:[customer-api] dependencyConditions: -resourceId: customer-api status:{is:[active]} ``` ### Worker verification Bundle This Bundle deploys a long-running Worker, then runs a Workflow to verify that the Worker is active and running. ```yaml version: v2alpha name: test-worker-sleep type: bundle description: "Integration test: deploy a minimal long-running worker (container stack) and verify pod runtime is running" tags: - test - worker - container bundle: resources: # Step 1: Deploy the sleep worker (single replica, container stack) - id: sleep-worker file: tests/worker/sleep-worker/worker.yaml # Step 2: Verify the worker via the Poros API once the pod is reported running - id: verify-sleep-worker file: tests/worker/sleep-worker/verify-workflow.yaml dependencies: - sleep-worker dependencyConditions: - resourceId: sleep-worker status: is: - active runtime: contains: - "running" ``` The first entry deploys the Worker. The second entry runs only after the Worker reports `active` status and a runtime state containing `running`. ## Apply and manage Apply the Bundle: ```bash dataos-ctl resource apply -f bundle.yaml ``` Check a Bundle: ```bash dataos-ctl resource get -t bundle -n ${{bundle-name}} -d ``` List Bundles: ```bash dataos-ctl resource get -t bundle dataos-ctl resource get -t bundle -a ``` Delete the Bundle: ```bash dataos-ctl resource delete -t bundle -n ${{bundle-name}} ``` Delete by identifier: ```bash dataos-ctl resource delete -i "${{bundle-name}}|v2alpha|bundle" ``` Delete by manifest: ```bash dataos-ctl resource delete -f bundle.yaml ``` {% hint style="warning" %} Deleting a Bundle can trigger deletion of resources associated with the Bundle. Resource deletion follows the reverse dependency order so dependent resources are removed before the resources they depend on. {% endhint %} ## Field reference | Field | Description | Required | | ------------------------------------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------- | | `version` | Manifest version. Use `v2alpha`. | Yes | | `name` | Bundle Resource name. | Yes | | `type` | Resource type. Use `bundle`. | Yes | | `description` | Human-readable description of the Bundle. | No | | `tags` | Labels for grouping and discovery. | No | | `bundle` | Bundle-specific configuration. | Yes | | `bundle.resources` | List of Resources included in the Bundle. | Yes | | `bundle.resources[].id` | Unique ID for the Resource inside the Bundle DAG. | Yes | | `bundle.resources[].file` | Path to a Resource manifest file. | No | | `bundle.resources[].spec` | Inline Resource manifest. | No | | `bundle.resources[].workspace` | Workspace where a workspace-level Resource should be created. | No | | `bundle.resources[].dependencies` | Resource IDs that must be processed before this Resource. | No | | `bundle.resources[].dependencyConditions` | Conditions that dependencies must satisfy before this Resource is processed. | No | | `bundle.resources[].dependencyConditions[].resourceId` | ID of the dependent Resource being checked. | Yes, when `dependencyConditions` is used | | `bundle.resources[].dependencyConditions[].status.is` | Accepted exact status values. | No | | `bundle.resources[].dependencyConditions[].status.contains` | Accepted status fragments. | No | | `bundle.resources[].dependencyConditions[].runtime.is` | Accepted exact runtime values. | No | | `bundle.resources[].dependencyConditions[].runtime.contains` | Accepted runtime fragments. | No | | `bundle.schedule` | Optional create/delete schedule for the Bundle. | No | | `bundle.workspaces` | Optional workspace definitions used by bundled Resources. | No | | `bundle.properties` | Additional key-value metadata for the Bundle. | No | | `bundle.manageAsUser` | User context used to manage the Bundle. | No | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/concepts/resources/bundle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.