> 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/service.md).

# Service

A Service is a long-running DataOS workload that runs continuously and exposes one or more network ports. Use a Service when an application must stay available to receive traffic, serve APIs, process streams, or host a server such as Postgres, an HTTP API, or a custom containerized application.

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

## Access requirements

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

## When to use

Use a Service when you need to:

* Run a long-lived process.
* Expose TCP or HTTP ports.
* Host a custom container image.
* Run a stateful application with an attached disk or Volume.
* Keep one or more replicas of the same application available.

Common examples include API servers, model-serving endpoints, webhook receivers, streaming consumers, and test databases used by other workloads.

## Manifest structure

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

```yaml
version: v2alpha
name: ${{service-name}}
type: service
tags:
  - ${{tag}}
description: ${{description}}
spec:
  hostname: ${{service-hostname}}
  compute: ${{compute-resource}}
  replicas: ${{replica-count}}
  servicePorts:
    - name: ${{port-name}}
      port: ${{port-number}}
  stack: ${{stack-name}}
  stackSpec:
    ${{stack-specific-configuration}}
```

## Create a Service

Create a Service in four steps:

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

### 1. Define how the workload should run

Start with the required fields:

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

Then decide whether the Service also needs:

* `servicePorts` for network access
* `replicas` for horizontal availability
* `stateful: true` with `disk` or `use.volumes` for persistent data
* `use.projection` for Secrets and environment variables

### 2. Add supporting Resources

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

Common dependencies include:

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

### 3. Apply the manifest

Apply the supporting Resources first, then apply the Service.

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

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

### 4. Verify the Service

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

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

If the Service exposes a port, test connectivity from the intended client after the runtime is healthy.

## Learn the building blocks

Use [Core concepts](/references/dataos-resources/service/core-concepts.md) for the full runtime model.

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

For projection-specific setup and syntax, see [Projections](/references/dataos-resources/secret/projections.md).

## Apply and manage

Apply the Secret before applying the Service, unless both are packaged in a Bundle.

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

Apply a Bundle:

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

Check the Service:

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

Delete the Service:

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

{% hint style="warning" %}
If the Service uses an inline `disk`, deleting the Service also deletes the disk and its data. If the Service mounts an existing Volume with `use.volumes`, deleting the Service does not delete the Volume.
{% endhint %}

## Field reference

See [Field reference](/references/dataos-resources/service/field-reference.md) for the complete Service manifest field reference, including nested `spec.servicePorts`, `spec.disk`, and `spec.use.volumes` 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/service.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.