# services.xml - container

[](/en/reference/applications/services/container.html.md "View as Markdown") 

This is the reference for the container cluster configuration in [services.xml](services.html).

```
container [version, id][http](http.html)[server [id, port]](http.html#server)[filtering](http.html#filtering)[handler [id, class, bundle]](#handler)[binding](#binding)[component](#component)[server [id, class, bundle]](#server)[clients](#clients)[client [id, permissions]](#client)[certificate [file]](#certificate)[token [id]](#token)[components](#components)[component](#component)[search](search.html)[include [dir]](#include)[binding](search.html#binding)[searcher](search.html#searcher)[federation](search.html#federation)[provider](search.html#provider)[chain](processing.html#chain)[renderer](search.html#renderer)[threadpool](search.html#threadpool)[significance](search.html#significance)[document-processing](docproc.html)[include [dir]](#include)[documentprocessor](docproc.html#documentprocessor)[chain](processing.html#chain)[threadpool](docproc.html#threadpool)[processing](processing.html)[include [dir]](#include)[binding](processing.html#binding)[processor](processing.html#processor)[chain](processing.html#chain)[renderer](processing.html#renderer)[document-api](#document-api)[abortondocumenterror](#abortondocumenterror)[retryenabled](#retryenabled)[route](#route)[maxpendingdocs](#maxpendingdocs)[maxpendingbytes](#maxpendingbytes)[retrydelay](#retrydelay)[timeout](#timeout)[tracelevel](#tracelevel)[mbusport](#mbusport)[ignore-undefined-fields](#ignore-undefined-fields)[max-document-size](#max-document-size)[model-evaluation](../../../ranking/stateless-model-evaluation.html)[onnx](../../../ranking/stateless-model-evaluation.html#onnx-inference-options)[inference](#inference)[memory](#inference-memory)[document [type, class, bundle]](#document)[accesslog [type, fileNamePattern, symlinkName, rotationInterval, rotationScheme]](#accesslog)[request-content [samples-per-second, path-prefix, max-bytes]](#request-content)[config](../config-files.html#generic-configuration-in-services-xml)[nodes [count, allocated-memory, jvm-gc-options, jvm-options]](#nodes)[resources](services.html#resources)(Vespa Cloud)[node [hostalias]](services.html#node)(Self managed)[environment-variables](#environment-variables)[jvm [allocated-memory, options, gc-options]](#jvm)[secrets](#secrets)[secret-store [type]](#secret-store)[group [name, environment]](#group)[zookeeper](#zookeeper)[threadpool](#threadpool)
```

[config](../config-files.html#generic-configuration-in-services-xml) elements are also allowed most places.

Example:

```

```

## \<container\>

Contained in [\<services\>](services.html). Each container tag specifies a separate container cluster.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| version | required | number | | 

1.0 in this version of Vespa

 |
| id | required | string | | 

the id of this cluster

 |

## handler

The `handler` element holds the configuration of a request handler. For each `binding` tag, the handler will be bound to the pertinent JDisc interfaces using the given binding.

- `binding` For JDisc request handlers, add this server binding to this handler.
- [`component`](#component) for injecting another component. Must be a declaration of a new component, not a reference.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| id | required | string | | 

The component ID

 |
| class | optional | string | | 

The class of the handler, defaults to id

 |
| bundle | optional | string | | 

The bundle to load the handler from: The name in \<artifactId\> in pom.xml. Defaults to class or id (if no class is given)

 |

Example:

```
<container id="default" version="1.0">
    <handler id="com.yahoo.search.handler.LegacyBridge">
        <binding>http://*/*</binding>
    </handler>
    <handler bundle="the name in <artifactId> in pom.xml" id="com.mydomain.vespatest.RedirectingHandler"/>
    <handler bundle="the name in <artifactId> in pom.xml" id="com.mydomain.vespatest.ExampleHandler"/>
    <nodes>
        <node hostalias="node1"/>
    </nodes>
</container>
```

## binding

The URI to map a Handler to. Multiple elements are allowed. See example above.

## server

The `server` element holds the configuration of a JDisc server provider.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| id | required | string | | 

The component ID

 |
| class | optional | string | | 

The class of the server, defaults to id

 |
| bundle | optional | string | | 

The bundle to load the server from: The name in \<artifactId\> in the pom.xml. Defaults to class or id (if no class is given).

 |

Example:
```
<server id="com.mydomain.vespatest.DemoServer">
    <config name="vespatest.demo-server">
        <response>Hello, world!
        </response>
        <port>16889</port>
    </config>
</server>
```

## clients

Vespa Cloud only. The `clients` element is a parent element for [client](#client) security configuration. Find details and practical examples in the [security guide](../../../security/guide#configuring-tokens). Example:

```
```
<container id="query" version="1.0">
    <clients>
        <client id="mtls" permissions="read">
            <certificate file="security/clients.pem"/>
        </client>
        <client id="query-token-client" permissions="read">
            <token id="query-token"/>
        </client>
    </clients>
</container>
```
```

## client

Vespa Cloud only. Child element of [clients](#clients). Use to configure security credentials for a container cluster, using [certificate](#certificate) and/or [token](#token).

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| id | required | string | | 

The client ID

 |
| permissions | required | string | | 

Permissions, see the [security guide](../../../security/guide#permissions). One of:

- `read`
- `write`
- `read,write`

 |

## certificate

Vespa Cloud only. Child element of [client](#client). Configure certificates using the _file_ attribute.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| file | required | string | | 

Path to the certificate file, see the [security guide](../../../security/guide#configuring-mtls).

 |

## token

Vespa Cloud only. Child element of [client](#client). Configure tokens using the _id_ attribute.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| id | required | string | | 

Token ID, see the [security guide](../../../security/guide#configuring-tokens).

 |

## components

Contains [component](#component) elements. Can be used in conjunction with [include](#include) for modular config of components.

## component

The `component` element holds the configuration of a [generic component](../../../applications/dependency-injection.html#special-components). Must be a declaration of a new component, not a reference.

Nested [`component`](#component) child elements can be added for injecting specific component instances. This is useful if there is more than one declared component of the same Java class. Refer to [Injecting components](../../../applications/dependency-injection.html) for details and examples.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| id | required | string | | 

The component ID

 |
| class | optional | string | | 

The class of the component, defaults to id

 |
| bundle | optional | string | | 

The bundle to load the component from: The name in \<artifactId\> in the pom.xml. Defaults to class or id (if no class is given).

 |

Example:

```
<component id="com.mydomain.demo.DemoComponent" bundle="the name in <artifactId> in pom.xml" />
```

## document-api

Use to enable [Document API](../../api/api.html) operations to a container cluster. Children elements:

| Name | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| binding | optional | string | http://\*/ | 

The URI to map the document-api handlers to. Multiple bindings are valid. Must end with a '/'. Note that each document-api handler will get its individual binding by adding a suffix, e.g. the feed handler will add 'feed/', the remove handler will add 'remove/' and so on. Example:

```
<document-api>
    <binding>http://*/document-api/</binding>
    <binding>https://*/document-api/</binding>
</document-api>
```
 With these configured bindings, the feed handler will be available at `http://*/document-api/feed/` and `https://*/document-api/feed/`. For other handlers, just replace 'feed/' with the appropriate suffix, e.g. 'get/', 'remove/' etc. |
| abortondocumenterror | optional | true/false | true | 

Controls whether to abort the entire feed or not if a document-related error occurs, i.e. if a document contains an unknown field. Setting this field to `true` will abort the feed on such errors, while setting it to `false` will cause Vespa to simply skip to the next document in the feed. Note that malformed XML in the input will abort the feed regardless of this setting.

 |
| maxpendingbytes | optional | number | | 

The maximum number of pending bytes. If `<maxpendingdocs>` is 0 and this is set to 0, this defaults to 100 MB. If `<maxpendingdocs>` is more than 0, and this is set to 0, the send-window is only limited by number of messages sent, not the memory footprint.

 |
| maxpendingdocs | optional | number | | 

The maximum number of pending documents the client can have. By default, the client will dynamically adjust the window size based on the latency of the performed operations. If the parameter is set, dynamic window sizing will be turned off in favor of the configured value.

 |
| mbusport | optional | number | | 

Set the MessageBus port

 |
| retrydelay | optional | double | 1.0 | 

Delay in seconds between retries

 |
| retryenabled | optional | true/false | | 

Enable or disable retrying documents that have failed.

 |
| route | optional | string | default | 

Set the route to feed documents to

 |
| timeout | optional | double | 180.0 | 

Set the timeout value in seconds for an operation

 |
| tracelevel | optional | 0-9 | 0 | 

Configure the level of which to trace messages sent. The higher the level, the more detailed descriptions.

 |
| ignore-undefined-fields | optional | true/false | false | 

Set to true to ignore undefined fields in document API operations and let such operations complete successfully, rather than fail. A [response header is returned](../../api/document-v1.html#x-vespa-ignored-fields) when field operations are ignored.

 |
| max-document-size | optional | string | 100MiB | 

Specifies the maximum size of a document operation request accepted by the container, measured as the uncompressed size of the request body. The limit applies to all document types in the container cluster. A request larger than this limit will be rejected by the container before the operation is forwarded to the content cluster.

Valid values are numbers including a unit (e.g. _10MiB_) and the value must be between 1MiB and 2048MiB (inclusive). Values will be rounded to the nearest MiB, so using MiB as a unit is preferable.

The value should normally not exceed the smallest [max-document-size](content.html#max-document-size) configured in any content cluster that this container feeds to; a deployment warning is emitted otherwise.

Example:

```
```
<document-api>
    <max-document-size>10MiB</max-document-size>
</document-api>
```
```
 |

Example:

```
<document-api>
    <binding>http://*/document-api/</binding>
    <binding>https://*/document-api/</binding>
    <abortondocumenterror>false</abortondocumenterror>
    <maxpendingbytes>1048576</maxpendingbytes>
    <maxpendingdocs>1000</maxpendingdocs>
    <mbusport>1234</mbusport>
    <retrydelay>5.5</retrydelay>
    <retryenabled>false</retryenabled>
    <route>default</route>
    <timeout>250.5</timeout>
    <tracelevel>3</tracelevel>
    <max-document-size>10MiB</max-document-size>
</document-api>
```

## inference

Vespa Cloud only. Configures resources used for model inference in the container, for example [embedders](../../../rag/embedding.html), [local LLMs](../../../rag/local-llms.html), and [stateless model evaluation](../../../ranking/stateless-model-evaluation.html).

| Element | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| memory | optional | string | auto-estimated | 

Container memory reserved for model inference, covering both model weights and inference requests. This memory is subtracted from the memory available to the JVM heap on the same node.

When not set, Vespa estimates the required inference memory automatically. The automatic estimate can be inaccurate for some models and workloads, which may lead to out-of-memory errors. Set this element explicitly to override the estimate.

 |

Example:

```
```
<container id="default" version="1.0">
    <inference>
        <memory>1500Mb</memory>
    </inference>
    ...
</container>
```
```

## document

[Concrete document type](../../../schemas/concrete-documents.html) bindings for the container. Example:

```
<container id="default" version="1.0">
    <document class="com.mydomain.concretedocs.Vehicle"
              bundle="the name in <artifactId> in pom.xml"
              type="vehicle"/>
    <document class="com.mydomain.concretedocs.Vehicle"
              bundle="the name in <artifactId> in pom.xml"
              type="ship"/>
    <document class="com.mydomain.concretedocs2.Disease"
              bundle="the name in <artifactId> in pom.xml"
              type="disease"/>
    <search/>
    <document-processing>
        <chain id="default">
            <documentprocessor bundle="the name in <artifactId> in pom.xml"
                               id="concretedocs.ConcreteDocDocProc"/>
        </chain>
    </document-processing>
    ...
</container>
```

## accesslog

Configures properties of the accesslog. The default type is `json` that will give output in (line-based) [JSON format](../../../operations/access-logging.html). See [Access logging](../../../operations/access-logging.html) for configuration details. Setting the type to `vespa` gives a classic Apache CLF-like format.

Access logging can be disabled by setting the type to `disabled`.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| type | optional | string | json | 

The accesslog type: _json_, _vespa_ or _disabled_

 |
| fileNamePattern | required\* | string | JsonAccessLog.\<container id\>.%Y%m%d%H%M%S | 

File name pattern. \* Note: Optional when _type_ is _disabled_

 |
| symlinkName | optional | string | JsonAccessLog.\<container id\> | 

Symlink name

 |
| rotationInterval | optional | string | 0 60 ... | 

Rotation interval

 |
| rotationScheme | optional | string | date | 

Valid values are _date_ or _sequence_

 |

### request-content

The `request-content` element is a child of `accesslog` and configures logging of request content. Multiple `request-content` elements can be specified to log different request paths with different configurations.

| Element | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| samples-per-second | required | double | | 

Probabilistic sample rate per second

 |
| path-prefix | required | string | | 

URI path prefix to match for logging

 |
| max-bytes | required | integer | | 

Maximum size in bytes to log, only prefix will be kept for larger requests

 |

Example:

```
<accesslog fileNamePattern="$VESPA_HOME/logs/vespa/access/JsonAccessLog.<container id>.%Y%m%d%H%M%S"
             symlinkName="JsonAccessLog.<container id>"
             rotationInterval="0 1 ..."
             type="json" >
    <request-content>
        <samples-per-second>0.2</samples-per-second>
        <path-prefix>/search</path-prefix>
        <max-bytes>65536</max-bytes>
    </request-content>
  </accesslog>
```

## include

Allows including XML snippets contained in external files. All files from all listed directories will be included. All files must have the same outer tag as they were referred from, i.e. search, document-processing or processing. The path must be relative to the application package root, and must never point outside the package.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| dir | required | string | | 

The directory to include files from. File inclusion order is undefined.

 |

Example:

```
<include dir="included_configs/search" />
```

## nodes

See [nodes](services.html#nodes) in the general services.xml documentation.

Additional container cluster specific attributes:

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| allocated-memory | optional | percentage | | 

 **Deprecated:** See [jvm](#jvm).
 |
| jvm-options | optional | string | | 

 **Deprecated:** See [jvm](#jvm).
 |
| jvm-gc-options | optional | string | | 

 **Deprecated:** See [jvm](#jvm).
 |

## environment-variables

Add child elements to set environment variables accessible in the container JVM runtime.

Example:

```
```
<nodes>
    <environment-variables>
        <KMP_SETTING>1</KMP_SETTING>
        <KMP_AFFINITY>granularity=fine,verbose,compact,1,0</KMP_AFFINITY>
    </environment-variables>
</nodes>
```
```

## jvm

JVM settings for container nodes.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| allocated-memory | optional | percentage | | Memory to allocate to each JVM instance as a percentage of available memory. Must be an integer percentage followed by _%_ |
| options | optional | string | | Generic JVM options |
| gc-options | optional | string | | JVM GC options. Garbage Collector specific parameters |

Example where 50% of the node total memory is used as the Max heap size of the JVM:

```
```
<nodes>
    <jvm gc-options="-XX:+UseG1GC -XX:MaxTenuringThreshold=10"
         options="-XX:+PrintCommandLineFlags"
         allocated-memory="50%" />
</nodes>
```
```

## secrets

Use to access secrets configured in Vespa Cloud - refer to the [secret store](../../../security/secret-store).

## secret-store

The `secret-store` element holds configuration for custom implementations. Contains one or more `group` elements.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| type | required | string | | 

Value: "oath-ckms"

 |

## group

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| name | required | string | | 

Key group name

 |
| environment | required | string | | 

Value one of: "alpha" "corp" "prod" "aws" "aws\_stage"

 |

Example:

```
<secret-store type="my-ckms">
    <group name="[key group]" environment="[environment]"/>
</secret-store>
```

## zookeeper

The _zookeeper_ element declares that the container cluster should run ZooKeeper and configure the necessary components. This element has no attributes or children.

## threadpool

Available since Vespa 8.611.13 .

Specifies configuration for the default thread pool in the container. All parameters are relative to the number of CPU cores—see the [container tuning example](../../../performance/container-tuning.html#container-worker-threads-example). This thread pool also supports the optional `max` attribute, which lets the pool grow up to `max * vCPU` threads under load before shrinking back after 5 seconds of idleness. Requests are rejected once the allowed number of threads is reached, all are busy, and the queue is full.

### threads

The number of permanent threads relative to number of vCPU cores. Default value is `2`.

| Attribute | Required | Value | Default | Description |
| --- | --- | --- | --- | --- |
| max | optional | number | 100 | 

The maximum number of threads relative to vCPU cores. Value must be greater than or equal to `<threads>`.

 |

### queue

The size of the request queue relative to effective number of threads. Specify `0` to disable queuing. Queueing is disabled by default.

 Copyright © 2026 - [Cookie Preferences](#)

### On this page:

- [services.xml - container](#page-title)
- [\<container\>](#)
- [handler](#handler)
- [binding](#binding)
- [server](#server)
- [clients](#clients)
- [client](#client)
- [certificate](#certificate)
- [token](#token)
- [components](#components)
- [component](#component)
- [document-api](#document-api)
- [inference](#inference)
- [document](#document)
- [accesslog](#accesslog)
- [request-content](#request-content)
- [include](#include)
- [nodes](#nodes)
- [environment-variables](#environment-variables)
- [jvm](#jvm)
- [secrets](#secrets)
- [secret-store](#secret-store)
- [group](#group)
- [zookeeper](#zookeeper)
- [threadpool](#threadpool)
- [threads](#threadpool-threads)
- [queue](#threadpool-queue)