> 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/references/dataos-resources/worker.md).

# Worker

A Worker is a long-running DataOS workload for background execution. Use a Worker when a process must keep running without exposing a Service endpoint, such as a stream processor, queue consumer, scheduler loop, or custom container that continuously performs work.

Workers are different from Workflows. A Workflow executes one or more jobs and then completes. A Worker is reconciled as a running workload and remains active until it is updated, suspended, or deleted.

Workers are also different from Services. A Service exposes one or more network ports for consumers. A Worker runs background logic and does not need to expose a port.

## Access requirements

Before creating or managing a Worker, ensure you have the required permissions. See [Worker: Access control](https://v2.dataos.info/operate/access-model/resource-level-permissions/worker-access-control).

## When to use

Use a Worker when you need to:

* Run a long-lived process without an exposed endpoint.
* Continuously consume or process events.
* Run a containerized background loop.
* Keep one or more replicas of the same background process active.
* Run stream processing or sinking logic using a supported stack.

Common examples include stream processors, queue consumers, data sinkers, schedulers, and monitoring or reconciliation loops.

## Manifest structure

A Worker manifest uses the common Resource metadata fields and a `spec` section that defines how the Worker runs.

```yaml
version: v2alpha
name: ${{worker-name}}
type: worker
tags:
  - ${{tag}}
description: ${{description}}
spec:
  compute: ${{compute-resource}}
  replicas: ${{replica-count}}
  executionMode: ${{execution-mode}}
  resources:
    requests:
      cpu: ${{cpu-request}}
      memory: ${{memory-request}}
    limits:
      cpu: ${{cpu-limit}}
      memory: ${{memory-limit}}
  stack: ${{stack-name}}
  stackSpec:
    ${{stack-specific-configuration}}
```

## Create a Worker

Create a Worker in four steps:

1. Define how the background process should run.
2. Add any supporting Resources.
3. Apply the manifest.
4. Verify the runtime state.

### 1. Define how the background process should run

Start with the required fields:

* `name` and `type: worker`
* `spec.compute`
* `spec.stack`
* `spec.stackSpec`

Then decide whether the Worker also needs:

* `replicas` for parallel background execution
* `executionMode` for runtime-specific behavior
* `resources` for CPU and memory controls
* `disk` or `use.volumes` for persistent files
* `use.projection` for Secrets, environment variables, and files

### 2. Add supporting Resources

Create supporting Resources before the Worker when the runtime depends on them.

Common dependencies include:

* a Secret for credentials
* a Volume for persistent storage
* a Bundle when deployment order or verification must be enforced

### 3. Apply the manifest

Apply the supporting Resources first, then apply the Worker.

```bash
dataos-ctl resource apply -f secret.yaml
dataos-ctl resource apply -f worker.yaml
```

If the Worker depends on multiple Resources, apply them as one Bundle instead.

### 4. Verify the Worker

Check that the Worker is `active` and that the runtime is `running`.

```bash
dataos-ctl resource get -t worker -n ${{worker-name}} -d
```

If needed, inspect Worker logs after the runtime is healthy.

## Learn the building blocks

Use [Core concepts](/references/dataos-resources/worker/core-concepts.md) for replicas, execution mode, resources, stacks, projections, and storage.

Use [Example](/references/dataos-resources/worker/example.md) for end-to-end Worker manifests.

## Apply and manage

Apply the Worker:

```bash
dataos-ctl resource apply -f worker.yaml
```

Apply a Bundle:

```bash
dataos-ctl resource apply -f bundle.yaml
```

Check the Worker:

```bash
dataos-ctl resource get -t worker -n ${{worker-name}} -d
```

List Workers:

```bash
dataos-ctl resource get -t worker
dataos-ctl resource get -t worker -a
```

Get Worker logs:

```bash
dataos-ctl resource log -t worker -n ${{worker-name}}
```

Delete the Worker:

```bash
dataos-ctl resource delete -t worker -n ${{worker-name}}
```

Delete by identifier:

```bash
dataos-ctl resource delete -i "${{worker-name}}|v2alpha|worker"
```

Delete by manifest:

```bash
dataos-ctl resource delete -f worker.yaml
```

## Field reference

See [Field reference](/references/dataos-resources/worker/field-reference.md) for the complete Worker manifest field reference, including nested runtime fields.


---

# 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/references/dataos-resources/worker.md?ask=<question>&goal=<endgoal>
```

`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.