services.xml - container
This is the reference for container cluster configuration:
container [version, id] http server [id, port] filtering rest-api components [bundle] package servlet [id, class, bundle] path servlet-config handler [id, class, bundle] binding clientbinding component client [id, class, bundle] binding clientbinding component server [id, class, bundle] components component search include [dir] binding searcher federation provider chain renderer document-processing include [dir] documentprocessor chain processing include [dir] binding processor chain renderer document-api abortondocumenterror retryenabled route maxpendingdocs maxpendingbytes retrydelay timeout tracelevel mbusport http-client-api threadpool max-threads min-threads queue-size model-evaluation document [type, class, bundle] accesslog [type, fileNamePattern, symlinkName, rotationInterval, rotationScheme] config nodes [jvmargs, allocated-memory, jvm-gc-options, jvm-options] environment-variables jvm [allocated-memory, options, gc-options] node [hostalias] secret-store [type] group [name, environment] zookeeperNote: container is equivalent to jdisc - use container, as jdisc will be discontinued.
Contained in services, zero or more container elements. The root element of a container cluster definition. Most elements takes optional config elements. Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
version | required | number | 1.0 in this version of Vespa | |
id | required | string | logical name of this cluster |
<container id="default" version="1.0"> <search> <chain id="default"> <searcher id="com.mydomain.search.SimpleSearcher"/> </chain> </search> <nodes> <node hostalias="node1"/> </nodes> </container>Each container cluster has a default http server port, unless it contains a http element. Hence, when running more than one
container
cluster on the same node,
it is necessary to manually assign a port to the http server to all but one cluster.
Otherwise, the application will not deploy. Assigning a port is done by adding a
server element with an explicit port number:
<container id="cluster2" version="1.0"> <http> <server id="myServer" port="8081" /> </http> ... </container>
rest-api
Add a Jersey web application with resources and providers to the container cluster.
Multiple web applications can be created by adding multiple rest-api
elements with unique paths. Bundles containing Jersey components are added by giving the
symbolic name (and optional version) in components
sub-elements.
From each given bundle, all classes with root annotations will be included in the corresponding web application.
Note: No extra dependencies in pom.xml -
the relevant artifacts are already pulled in via container
.
The
bundle plugin ensures that the Jersey resources are available. Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
path | required | string | The path to bind the rest-api. |
- Components can be injected directly into Jersey resources
- Injecting Config without wrapping it in a Component will not work
- While Jersey creates a new resource instance for each request, the Components is the same object until the application is restarted or redeployed
- Injected components can be a subclass of the parameter class required by the resource constructor
components
Add a bundle to scan for Jersey components. Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
bundle | required | string | The bundle to include Jersey components from. Format: 'symbolicName:version' |
package
Scan for components only in the given packages. If no package elements are given, all packages will be scanned. Example:
<rest-api path="my-app"> <components bundle="my-bundle"> <package>com.mydomain.foo</package> <package>com.mydomain.bar</package> </components> <components bundle="other-bundle:2.0.0" /> </rest-api>
servlet
Add a Servlet, one per servlet
element.
Minimum one path child element is required. Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
id | required | string | A unique id | |
class | required | string | The class to load as a Servlet | |
bundle | required | string | The bundle that the Servlet resides in |
path
The path the Servlet will bind to.
servlet-config
An alternative to regular config to support legacy ServletConfig. It is a simple map of string keys to string values that will be available as ServletConfig inside the Servlet. Example:
<servlet id="my-servlet" class="com.mydomain.MyServlet" bundle="servlet-example"> <path>my-path</path> <servlet-config> <myKey>myValue</myKey> </servlet-config> </servlet>
handler
The handler
element holds the configuration of a handler.
If any binding tag, binding
or clientBinding
is present, the handler is a JDisc request handler, and will be bound
to the pertinent JDisc interfaces using the given bindings.
binding
For JDisc request handlers, add this server binding to this handler.clientBinding
For JDisc request handlers, add this client binding to this handler.component
for injecting another component. Must be a declaration of a new component, not a reference.
Name | 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, defaults to class or id (if no class is given) |
<container id="default" version="1.0"> <handler id="com.yahoo.search.handler.LegacyBridge"> <binding>http://*/*</binding> </handler> <handler bundle="myHandlers" id="com.mydomain.vespatest.RedirectingHandler"/> <handler bundle="myHandlers" 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.
clientbinding
ToDo
client
The client
element holds the configuration of a JDisc client provider.
It has one mandatory attribute, id
and must be bound to some URI pattern to be available for use.
Same subelements as handler. Attributes:
Name | 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, defaults to class or id (if no class is given) |
<client id="com.mydomain.vespatest.DemoClient"> <config name="vespatest.response"> <response>DemoClient says: Hello, world! </response> </config> <binding>http://remotehost/*</binding> <binding>http://another-remotehost/*</binding> <serverBinding>http://*:8080/DemoClient</serverBinding> </client>
server
The server
element holds the configuration of a JDisc server provider. Attributes:
Name | 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, defaults to class or id (if no class is given) |
<server id="com.mydomain.vespatest.DemoServer"> <config name="vespatest.demo-server"> <response>Hello, world! </response> <port>16889</port> </config> </server>
components
Contains component elements. Can be used in conjunction with include for modular config of components.
component
The component
element holds the configuration of a
generic component.
Must be a declaration of a new component, not a reference.
Nested 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 for details and examples.
Name | 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, defaults to class or id (if no class is given) |
<component id="com.mydomain.demo.DemoComponent" bundle="demo" />
document-api
Use to enable Document API operations to a container cluster, by setting up these handlers:
{ id: "com.yahoo.document.restapi.resource.RestApi", class: "com.yahoo.document.restapi.resource.RestApi", bundle: "vespaclient-container-plugin:7.0.0", serverBindings: [ "http://*/document/v1/*", "http://*/document/v1/*/" ] } { id: "com.yahoo.vespa.http.server.FeedHandler", class: "com.yahoo.vespa.http.server.FeedHandler", bundle: "vespaclient-container-plugin:7.0.0", serverBindings: [ "http://*/reserved-for-internal-use/feedapi", "http://*/reserved-for-internal-use/feedapi/" ] }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 or not to abort the entire feed if a document-related error occurs,
ie. 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 100MB.
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. |
http-client-api | optional | Configuration for the Vespa HTTP client API |
<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> <http-client-api> <threadpool> <max-threads>50</max-threads> <min-threads>10</min-threads> <queue-size>1000</queue-size> </threadpool> </http-client-api> <document-api>
http-client-api
<http-client-api> <threadpool> <max-threads>50</max-threads> <min-threads>10</min-threads> <queue-size>1000</queue-size> </threadpool> </http-client-api>Children elements:
Name | Required | Value | Default | Description | |
---|---|---|---|---|---|
threadpool | optional | Contains configuration of the threadpool for the http client api handler. The pool is initialized with minimum number of threads during startup. Additional threads will be created on demand once the request queue is full. Requests are rejected once maximum threads are reached, all threads are busy and the the request queue is full. |
document
Concrete document type bindings for the container. Example:
<container id="default" version="1.0"> <document class="com.mydomain.concretedocs.Vehicle" bundle="concretedocs" type="vehicle"/> <document class="com.mydomain.concretedocs.Vehicle" bundle="concretedocs" type="ship"/> <document class="com.mydomain.concretedocs2.Disease" bundle="concretedocs2" type="disease"/> <search/> <document-processing> <chain id="default"> <documentprocessor bundle="concretedocs" id="concretedocs.ConcreteDocDocProc"/> </chain> </document-processing> <nodes> <node hostalias="node1"/> </nodes> </container>
accesslog
Configures properties of the accesslog.
The default type is json
that will give output in (line-based)
JSON format. See Access logging for details on
the configuration options.
Setting the type to vespa
gives a classic Apache CLF-like format.
Access logging can be disabled by setting the type to disabled
. Attributes:
Name | 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 |
<accesslog fileNamePattern='$VESPA_HOME/logs/vespa/qrs/JsonAccessLog.<container id>.%Y%m%d%H%M%S' symlinkName='JsonAccessLog.<container id>' rotationInterval='0 1 ...' type='vespa' />
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 of the package. Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
dir | required | string | The directory to include files from. File inclusion order is undefined. |
<include dir="included_configs/search" />
nodes
The nodes
element specifies the nodes that comprise this container cluster
by adding node children. Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
jvmargs | optional | string | Deprecated, see jvm element | |
allocated-memory | optional | percentage | Deprecated, see jvm element | |
jvm-options | optional | string | Deprecated, see jvm element | |
jvm-gc-options | optional | string | Deprecated, see jvm element |
environment-variables
Add children elements to nodes
for environment variables - see example below.
These are set before the services are started on the container node - available for the Container.
jvm
JVM settings for container nodes:
Name | 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 |
<nodes> <jvm gc-options="-XX:+UseG1GC -XX:MaxTenuringThreshold=10" options="-XX:+PrintCommandLineFlags" allocated-memory="50%" /> </nodes>
node
Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
hostalias | required | string | logical hostname - mapped to hostnames in hosts.xml |
<nodes> <environment-variables> <KMP_SETTING>1</KMP_SETTING> <KMP_AFFINITY>granularity=fine,verbose,compact,1,0</KMP_AFFINITY> </environment-variables> <node hostalias="searchnode1" /> </nodes>
secret-store
The secret-store element holds configuration for custom implementations. Contains one or more group elements.
Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
type | required | string | Value: "oath-ckms" |
group
Attributes:
Name | Required | Value | Default | Description |
---|---|---|---|---|
name | required | string | Key group name | |
environment | required | string | Value one of: "alpha" "corp" "prod" "aws" "aws_stage" |
<secret-store type="oath-ckms"> <group name="[key group]" environment="[environment]"/> </secret-store>
zookeeper
The zookeper element declares that the container cluster should run ZooKeeper and configure the necessary components. This element has no attributes or children.