Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
230 lines (203 sloc) 9.81 KB
---
title: services.xml - Vespa Cloud
---
<p>
<em>services.xml</em> is the primary Vespa configuration file.
This documents services.xml for Vespa Cloud - see
<a href="http://docs.vespa.ai/documentation/reference/services.html">services.xml</a>
for the full reference.
</p>
<h2 id="nodes">nodes</h2>
<p>
In cloud applications nodes are specified by count and node resources.
</p><p>
<strong>Subelements:</strong> <a href="#resources">resources</a>
</p><p>
<strong>Attributes:</strong>
<ul>
<li><strong>count</strong>: Positive integer. The number of nodes of the cluster.
</ul>
In addition there are some attributes for specific cluster types, listed below.
</p>
<h3 id="nodes-for-container">&lt;nodes&gt; for &lt;container&gt;</h3>
<ul>
<li><strong>of</strong> (optional): A content cluster id.
This attribute can be used to specify that this container service should run on the nodes of a content service.
If <em>of</em> is specified, only <em>jvmargs</em> can be set in addition.
No other attributes can be set, as the ones of the referenced content cluster will be used instead.
</li>
</ul>
<h3 id="nodes-for-content">&lt;nodes&gt; for &lt;content&gt;</h3>
<ul>
<li><strong>groups</strong> (optional): Non-negative integer.
Sets the number of <em>groups</em> into which content nodes should be divided.
Each group will have an equal share of the nodes and <em>redundancy</em> copies of the corpus,
and each query will be routed to just one group. This allows scaling to a higher query load than is efficient
within a single group. Note that taking redundancy to mean the number of copies per group is different
than when listing groups and nodes explicitly outside Vespa Cloud, where redundancy means the number
of copies across all groups.
If this is set, no groups can be specified as subelements of this.
WARNING: Changing from a non-grouped configuration to multiple groups will lead to temporary reduced coverage
in query serving as data is migrated.
</li>
</ul>
<h3 id="nodes-for-controllers-slobroks-and-logservers">&lt;nodes&gt; for &lt;controllers&gt; &lt;slobroks&gt; and &lt;logservers&gt;</h3>
<p>
The nodes element nested in these elements allow specifying whether the nodes used should be dedicated to the service
or if it should run on existing nodes. Attribute:
<ul>
<li><strong>dedicated</strong> (optional): true or false (default false).
Whether or not separate nodes should be allocated for this service.</li>
</ul>
</p>
<h2 id="resources">resources</h2>
<p>
Contained in the <a href="#nodes">nodes</a> element, specifies each node's resource requirements.
Resources is a powerful way to optimize cost and performance.
For new launches, allocate enough to reduce risk -
then use the <a href="https://docs.vespa.ai/documentation/performance/">performance guides</a>
to find the sweet spot to balance cost and free capacity, based on real production load.
Migration to new capacity is automated,
read more in <a href="https://docs.vespa.ai/documentation/elastic-vespa.html">elastic Vespa</a>.
</p><p>
<b>Subelements:</b> None
</p><p>
<b>Attributes:</b>
<table class="table">
<tr><td><b>vcpu</b></td><td>float</td>
<td>CPU, virtual threads</td></tr>
<tr><td><b>memory</b></td><td>float, followed by a byte unit, such as "Gb"</td>
<td>Memory</td></tr>
<tr><td><b>disk</b></td><td>float followed by a byte unit, such as "Gb"</td>
<td>Disk space</td></tr>
<tr><td><b>storage-type</b> (optional)<td>string (enum)</td>
<td>The type of storage to use. This is useful to specify local storage when network storage provides insufficient
io operations or too noisy io performance.
<table class="table">
<tr><td><code><b>local</b></code></td><td>Node-local storage is required.</td></tr>
<tr><td><code><b>remote</b></code></td><td>Network storage must be used.</td></tr>
<tr><td><code><b>any</b></code> (default)</td><td>Both remote or local storage may be used.</td></tr>
</table>
</td></tr>
<tr><td><b>disk-speed</b> (optional)<td>string (enum)</td>
<td>The required disk speed category.
<table class="table">
<tr><td><code><b>fast</b></code> (default)</td><td>SSD-like disk speed is required</td></tr>
<tr><td><code><b>slow</b></code></td><td>This is sized for spinning disk speed</td></tr>
<tr><td><code><b>any</b></code></td> <td>Performance does not depend on disk speed (often suitable for container clusters).</td></tr>
</table>
</td></tr>
</table>
Example:
<pre>
&lt;nodes count="4"&gt;
&lt;resources vcpu="2.5" memory="32Gb" disk="100Gb" disk-speed="any"/&gt;
&lt;/nodes&gt;
</pre>
</p>
<h2 id="admin-version-4-0">&lt;admin version="4.0"&gt;</h2>
<p>
Admin version 4 is used for explicit control over the number of admin services running and whether these should run on
dedicated nodes or on some existing container cluster in the application.
In most cases, there is no need to specify this explicitly.
</p>
<h3>Sub-elements</h3>
<table class="table table-striped">
<thead>
<tr><th>Element<th>Quantity<th>Description</tr>
</thead><tbody>
<tr><td><code>&lt;slobroks&gt;&lt;nodes .../&gt;</code></a>
<td>0 or 1</td>
<td>Controls the nodes used for instance internal service location brokering</td></tr>
<tr><td><code>&lt;logservers&gt;&lt;nodes dedicated='true' .../&gt;</code></a>
<td>0 or 1</td>
<td>Controls the node used as log server. At most 1 node can be configured.</td></tr>
</tbody>
</table>
<h2 id="instance-environment-and-region-variants">Instance, environment and region variants</h2>
<p>
Application packages support defining different configuration settings
for different <em>instances</em>, <em>environments</em> and <em>regions</em>.
To use this you must import the <em>deploy</em> namespace:
<pre>
&lt;services version="1.0" <strong style="background-color: yellow;">xmlns:deploy="vespa"</strong>&gt;
</pre>
Deploy directives are used to specify in which instance, environment and/or region an XML element should be included:
<pre>
&lt;content version="1.0"&gt;
&lt;redundancy&gt;1&lt;/redundancy&gt;
&lt;documents&gt;
&lt;document type="music.sd" mode="index" /&gt;
&lt;/documents&gt;
&lt;nodes <strong style="background-color: yellow;">deploy:environment="dev"</strong> count="1" /&gt;
&lt;nodes <strong style="background-color: yellow;">deploy:environment="prod"</strong> <strong style="background-color: yellow;">deploy:region="us-west-1"</strong> count="20" /&gt;
&lt;nodes <strong style="background-color: yellow;">deploy:environment="prod"</strong> <strong style="background-color: yellow;">deploy:region="us-east-3"</strong> count="40" /&gt;
&lt;nodes <strong style="background-color: yellow;">deploy:environment="prod"</strong> <strong style="background-color: yellow;">deploy:region="us-east-3"</strong> <strong style="background-color: yellow;">deploy:instance="alpha"</strong> count="4" /&gt;
&lt;/content&gt;
</pre>
This example configures a different node count depending on the deployment target.
Deploying the application in the <em>dev</em> environment gives:
<pre>
&lt;content version="1.0"&gt;
&lt;redundancy&gt;1&lt;/redundancy&gt;
&lt;documents&gt;
&lt;document type="music.sd" mode="index" /&gt;
&lt;/documents&gt;
&lt;nodes count="1" /&gt;
&lt;/content&gt;
</pre>
Whereas in <em>prod.us-west-1</em> it is:
<pre>
&lt;content version="1.0"&gt;
&lt;redundancy&gt;1&lt;/redundancy&gt;
&lt;documents&gt;
&lt;document type="music.sd" mode="index" /&gt;
&lt;/documents&gt;
&lt;nodes count="60" /&gt;
&lt;/content&gt;
</pre>
This can be used to modify any config by deployment target.
</p><p>
The deploy directives have a set of override rules:
<ul>
<li>A directive specifying more conditions will override one specifying fewer.</li>
<li>Directives are inherited in child elements.</li>
<li>When multiple XML elements with the same name is specified
(e.g. when specifying search or docproc chains), the <em>id</em> attribute of the element
is used together with the element name when applying directives.</li>
</ul>
</p>
<p>Some overrides are applied by default in some environments, see <a href="environments">environments</a>.
Any override made explicitly for an environment will override the defaults for it.</p>
<h3 id="advanced">Advanced</h3>
<p>
More than one instance, region or environment can be specified in the attribute, separated by space. Notes:
<ul>
<li>The region attribute is only respected if given environment exists in multiple regions.
This is currently true for <em>prod</em> and <em>dev</em></li>
<li>An element which only specifies region, will match both prod and dev environment in that region</li>
</ul>
The namespace can be applied to any element. Example:
<pre>
&lt;container id="default" version="1.0" <span style="background: yellow">deploy:environment="perf test staging prod"</span>&gt;
&lt;search&gt;
&lt;chain id="default" inherits="vespa"&gt;
&lt;searcher bundle="basic-application" id="com.yahoo.example.ExampleSearcher"&gt;
&lt;config name="example.message"&gt;
&lt;message&gt;Hello from application config&lt;/message&gt;
&lt;message <span style="background: yellow">deploy:region="us-east-3"</span>&gt;Hello from east colo!&lt;/message&gt;
&lt;/config&gt;
&lt;/searcher&gt;
&lt;/chain&gt;
&lt;/search&gt;
</pre>
Above, the <em>container</em> element is configured for the 4 environments only (it will not apply to <em>dev</em>) -
and in region <em>us-east-3</em>, the config is different.
</p>
<h2 id="controllers">controllers</h2>
<p>
Under <code>content</code> provides control over the nodes used as cluster controllers in this cluster on Vespa Cloud.
If this element is not specified, 3 nodes from the content cluster are assigned as cluster controllers
(from different groups if applicable).
If this is specified, there is one mandatory sub-element, <a href="#nodes">nodes</a>.
</p>
You can’t perform that action at this time.