Skip to content

Commit 29372c2

Browse files
kkraunekkraune
authored
Merge pull request #3839 from vespa-engine/kkraune/deployment
Add config files
2 parents 6c439fb + 1f51368 commit 29372c2

File tree

3 files changed

+1102
-14
lines changed

3 files changed

+1102
-14
lines changed

‎_data/sidebar.yml

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -453,20 +453,25 @@ docs:
453453
url: /en/reference/schema-reference.html
454454
- page: services.xml
455455
url: /en/reference/services.html
456-
- page: services.xml - admin
457-
url: /en/reference/services-admin.html
458-
- page: services.xml - container
459-
url: /en/reference/services-container.html
460-
- page: services.xml - content
461-
url: /en/reference/services-content.html
462-
- page: services.xml - docproc
463-
url: /en/reference/services-docproc.html
464-
- page: services.xml - http
465-
url: /en/reference/services-http.html
466-
- page: services.xml - processing
467-
url: /en/reference/services-processing.html
468-
- page: services.xml - search
469-
url: /en/reference/services-search.html
456+
sub:
457+
- page: services.xml - admin
458+
url: /en/reference/services-admin.html
459+
- page: services.xml - container
460+
url: /en/reference/services-container.html
461+
- page: services.xml - content
462+
url: /en/reference/services-content.html
463+
- page: services.xml - docproc
464+
url: /en/reference/services-docproc.html
465+
- page: services.xml - http
466+
url: /en/reference/services-http.html
467+
- page: services.xml - processing
468+
url: /en/reference/services-processing.html
469+
- page: services.xml - search
470+
url: /en/reference/services-search.html
471+
- page: deployment.xml
472+
url: /en/reference/deployment.html
473+
- page: Deployment variants
474+
url: /en/reference/deployment-variants.html
470475
- page: hosts.xml
471476
url: /en/reference/hosts.html
472477
- page: validation-overrides.xml

‎en/reference/deployment-variants.html

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
# Copyright Vespa.ai. All rights reserved.
3+
title: "Instance, region, cloud and environment variants"
4+
category: cloud
5+
---
6+
7+
<p>
8+
Sometimes it is useful to create configuration that varies depending on properties of the deployment,
9+
for example to set region specific endpoints of services used by <a href="/en/searcher-development.html">Searchers</a>,
10+
or use smaller clusters for a "beta" instance.
11+
</p>
12+
<p>
13+
This is supported both for <a href="#services.xml-variants">services.xml</a> and
14+
<a href="#query-profile-variants">query profiles</a>.
15+
</p>
16+
17+
18+
19+
<h2 id="services.xml-variants">services.xml variants</h2>
20+
<p>
21+
<a href="services.html">services.xml</a> files support different configuration settings
22+
for different <em>tags</em>, <em>instances</em>, <em>environments</em>, <em>clouds</em> and <em>regions</em>.
23+
To use this, import the <em>deploy</em> namespace:
24+
</p>
25+
<pre>{% highlight xml %}
26+
<services version="1.0" xmlns:deploy="vespa">
27+
{% endhighlight %}</pre>
28+
<p>
29+
Deploy directives are used to specify with which tags, and in which instance, environment,
30+
cloud and/or region an XML element should be included:
31+
</p>
32+
<pre>{% highlight xml %}
33+
<content version="1.0">
34+
<min-redundancy>2</min-redundancy>
35+
<documents>
36+
<document type="music.sd" mode="index" />
37+
</documents>
38+
<nodes deploy:environment="dev"
39+
count="1" />
40+
<nodes deploy:environment="prod"
41+
deploy:region="aws-us-east-1c"
42+
count="20" />
43+
<nodes deploy:cloud="gcp" count="10" />
44+
<nodes deploy:environment="prod"
45+
deploy:region="aws-ap-northeast-1a"
46+
count="40" />
47+
<nodes deploy:environment="prod"
48+
deploy:region="aws-ap-northeast-1a"
49+
deploy:instance="alpha"
50+
count="4" />
51+
<nodes deploy:tags="myTag1 myTag2" count="8" />
52+
</content>
53+
{% endhighlight %}</pre>
54+
<p>
55+
The example above configures a different node count depending on the deployment target.
56+
Deploying the application in the <em>dev</em> environment gives:
57+
</p>
58+
<pre>{% highlight xml %}
59+
<content version="1.0">
60+
<min-redundancy>2</min-redundancy>
61+
<documents>
62+
<document type="music.sd" mode="index" />
63+
</documents>
64+
<nodes count="1" />
65+
</content>
66+
{% endhighlight %}</pre>
67+
<p>Whereas in <em>prod.us-west-1</em> it is:</p>
68+
<pre>{% highlight xml %}
69+
<content version="1.0">
70+
<min-redundancy>2</min-redundancy>
71+
<documents>
72+
<document type="music.sd" mode="index" />
73+
</documents>
74+
<nodes count="60" />
75+
</content>
76+
{% endhighlight %}</pre>
77+
<p>This can be used to modify any config by deployment target.</p>
78+
<p>The <code>deploy</code> directives have a set of override rules:</p>
79+
<ul>
80+
<li>A directive specifying more conditions will override one specifying fewer.</li>
81+
<li>Directives are inherited in child elements.</li>
82+
<li>
83+
When multiple XML elements with the same name is specified
84+
(e.g. when specifying search or docproc chains),
85+
the <em>id</em> attribute or the <em>idref</em> attribute of the element
86+
is used together with the element name when applying directives.
87+
</li>
88+
</ul>
89+
<p>
90+
Some overrides are applied by default in some environments,
91+
see <a href="https://cloud.vespa.ai/en/reference/environments">environments</a>.
92+
Any override made explicitly for an environment will override the defaults for it.
93+
</p>
94+
95+
96+
<h3 id="advanced">Specifying multiple targets</h3>
97+
<p>More than one tag, instance, region or environment can be specified in the attribute, separated by space.</p>
98+
<p>
99+
Note that <em>tags</em> by default only apply in production instances,
100+
and are matched whenever the tags of the element and the tags of the instance intersect.
101+
To match tags in other environments,
102+
an explicit <code>deploy:environment</code> directive for that environment must also match.
103+
Use tags if you have a complex instance structure which you want config to vary by.
104+
</p>
105+
<p>The namespace can be applied to any element. Example:</p>
106+
<pre>{% highlight xml %}
107+
<container id="default" version="1.0" deploy:environment="perf test staging prod">
108+
<search>
109+
<chain id="default" inherits="vespa">
110+
<searcher bundle="basic-application" id="vespa.ai.ExampleSearcher">
111+
<config name="example.message">
112+
<message>Hello from application config</message>
113+
<message deploy:region="aws-us-east-1c">Hello from east colo!</message>
114+
</config>
115+
</searcher>
116+
</chain>
117+
</search>
118+
</container>
119+
{% endhighlight %}</pre>
120+
<p>
121+
Above, the <em>container</em> element is configured for the 4 environments only (it will not apply to <em>dev</em>) -
122+
and in region <em>aws-us-east-1c</em>, the config is different.
123+
</p>
124+
125+
126+
127+
<h2 id="query-profile-variants">Query profile variants</h2>
128+
<p>
129+
<a href="/en/query-profiles.html">Query profiles</a> support different configuration settings
130+
for different <em>instances</em>, <em>environments</em> and <em>regions</em> through
131+
<a href="/en/query-profiles.html#query-profile-variants">query profile variants</a>.
132+
This allows you to set different query parameters for a query type depending on these deployment attributes.
133+
</p>
134+
<p>
135+
To use this feature, create a regular query profile variant with any of
136+
<code>instance</code>, <code>environment</code> and <code>region</code> as dimension names and
137+
let your query profile vary by that. For example:
138+
</p>
139+
<pre>{% highlight xml %}
140+
<query-profile id="default">
141+
142+
<dimensions>instance, environment, region</dimensions>
143+
144+
<field name="a">My default value</field>
145+
146+
<!-- Value for (any deployment of) the beta instance -->
147+
<query-profile for="beta">
148+
<field name="a">My beta value</field>
149+
</query-profile>
150+
151+
<!-- Value for (any) dev deployment -->
152+
<query-profile for="*, dev">
153+
<field name="a">My dev value</field>
154+
</query-profile>
155+
156+
<!-- Value for the default instance in prod -->
157+
<query-profile for="default, prod">
158+
<field name="a">My main instance prod value</field>
159+
</query-profile>
160+
161+
</query-profile>
162+
{% endhighlight %}</pre>
163+
<p>You can pick and combine these dimensions in any way you want with other dimensions sent as query parameters, e.g:</p>
164+
<pre>{% highlight xml %}
165+
<dimensions>device, instance, usecase</dimensions>
166+
{% endhighlight %}</pre>

0 commit comments

Comments
 (0)