1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
// Copyright 2016 Yahoo Inc. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.config.application.api;
import com.google.common.collect.ImmutableList;
import com.yahoo.config.provision.Environment;
import com.yahoo.config.provision.RegionName;
import com.yahoo.text.XML;
import org.w3c.dom.Element;
import java.io.BufferedReader;
import java.io.FileReader;
import java.io.Reader;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Optional;
/**
* Specifies the environments and regions to which an application should be deployed.
* This may be used both for inspection as part of an application model and to answer
* queries about deployment from the command line. A main method is included for the latter usage.
*
* @author bratseth
*/
public class DeploymentSpec {
private final Optional<String> globalServiceId;
private final UpgradePolicy upgradePolicy;
private final List<DeclaredZone> zones;
public DeploymentSpec(Optional<String> globalServiceId, UpgradePolicy upgradePolicy, List<DeclaredZone> zones) {
this.globalServiceId = globalServiceId;
this.upgradePolicy = upgradePolicy;
this.zones = ImmutableList.copyOf(zones);
}
/** Returns the ID of the service to expose through global routing, if present */
public Optional<String> globalServiceId() {
return globalServiceId;
}
/** Returns the upgrade policy of this, which is defaultPolicy if none is specified */
public UpgradePolicy upgradePolicy() { return upgradePolicy; }
/** Returns the zones this declares as a read-only list. */
public List<DeclaredZone> zones() { return zones; }
/** Returns whether this deployment spec specifies the given zone, either implicitly or explicitly */
public boolean includes(Environment environment, Optional<RegionName> region) {
for (DeclaredZone declaredZone : zones)
if (declaredZone.matches(environment, region)) return true;
return false;
}
/**
* Creates a deployment spec from XML.
*
* @throws IllegalArgumentException if the XML is invalid
*/
public static DeploymentSpec fromXml(Reader reader) {
List<DeclaredZone> zones = new ArrayList<>();
Element root = XML.getDocument(reader).getDocumentElement();
Optional<String> globalServiceId = Optional.empty();
for (Element environmentTag : XML.getChildren(root)) {
if ( ! isEnvironmentName(environmentTag.getTagName())) continue;
Environment environment = Environment.from(environmentTag.getTagName());
List<Element> regionTags = XML.getChildren(environmentTag, "region");
if (regionTags.isEmpty()) {
zones.add(new DeclaredZone(environment, Optional.empty(), false));
}
else {
for (Element regionTag : regionTags) {
RegionName region = RegionName.from(XML.getValue(regionTag).trim());
boolean active = environment == Environment.prod && readActive(regionTag);
zones.add(new DeclaredZone(environment, Optional.of(region), active));
}
}
if (Environment.prod.equals(environment)) {
globalServiceId = readGlobalServiceId(environmentTag);
} else if (readGlobalServiceId(environmentTag).isPresent()) {
throw new IllegalArgumentException("Attribute 'global-service-id' is only valid on 'prod' tag.");
}
}
return new DeploymentSpec(globalServiceId, readUpgradePolicy(root), zones);
}
private static boolean isEnvironmentName(String tagName) {
return tagName.equals("test") || tagName.equals("staging") || tagName.equals("prod");
}
private static Optional<String> readGlobalServiceId(Element environmentTag) {
String globalServiceId = environmentTag.getAttribute("global-service-id");
if (globalServiceId == null || globalServiceId.isEmpty()) {
return Optional.empty();
}
else {
return Optional.of(globalServiceId);
}
}
private static UpgradePolicy readUpgradePolicy(Element root) {
Element upgradeElement = XML.getChild(root, "upgrade");
if (upgradeElement == null) return UpgradePolicy.defaultPolicy;
String policy = upgradeElement.getAttribute("policy");
switch (policy) {
case "canary" : return UpgradePolicy.canary;
case "default" : return UpgradePolicy.defaultPolicy;
case "conservative" : return UpgradePolicy.conservative;
default : throw new IllegalArgumentException("Illegal upgrade policy '" + policy + "': " +
"Must be one of " + Arrays.toString(UpgradePolicy.values()));
}
}
private static boolean readActive(Element regionTag) {
String activeValue = regionTag.getAttribute("active");
if ("true".equals(activeValue)) return true;
if ("false".equals(activeValue)) return false;
throw new IllegalArgumentException("Region tags must have an 'active' attribute set to 'true' or 'false' " +
"to control whether the region should receive production traffic");
}
public static String toMessageString(Throwable t) {
StringBuilder b = new StringBuilder();
String lastMessage = null;
String message;
for (; t != null; t = t.getCause()) {
message = t.getMessage();
if (message == null) continue;
if (message.equals(lastMessage)) continue;
if (b.length() > 0) {
b.append(": ");
}
b.append(message);
lastMessage = message;
}
return b.toString();
}
/** This may be invoked by a continuous build */
public static void main (String[] args) {
if (args.length != 2 && args.length != 3) {
System.err.println("Usage: DeploymentSpec [file] [environment] [region]?" +
"Returns 0 if the specified zone matches the deployment spec, 1 otherwise");
System.exit(1);
}
try (BufferedReader reader = new BufferedReader(new FileReader(args[0]))) {
DeploymentSpec spec = DeploymentSpec.fromXml(reader);
Environment environment = Environment.from(args[1]);
Optional<RegionName> region = args.length == 3 ? Optional.of(RegionName.from(args[2])) : Optional.empty();
if (spec.includes(environment, region))
System.exit(0);
else
System.exit(1);
}
catch (Exception e) {
System.err.println("Exception checking deployment spec: " + toMessageString(e));
System.exit(1);
}
}
public static class DeclaredZone {
private final Environment environment;
private Optional<RegionName> region;
private final boolean active;
public DeclaredZone(Environment environment, Optional<RegionName> region, boolean active) {
this.environment = environment;
this.region = region;
this.active = active;
}
public Environment environment() { return environment; }
/** The region name, or empty if not declared */
public Optional<RegionName> region() { return region; }
/** Returns whether this zone should receive production traffic */
public boolean active() { return active; }
public boolean matches(Environment environment, Optional<RegionName> region) {
if (environment.equals(this.environment) && region.equals(this.region)) return true;
if ( ! region.isPresent() && prerequisite(environment)) return true;
return false;
}
/**
* Returns whether deployment in the given environment is a prerequisite of deployment in this environment
*
* The required progression leading to prerequisites is test, staging, prod.
*/
private boolean prerequisite(Environment environment) {
if (this.environment == Environment.prod)
return environment == Environment.staging || environment == Environment.test;
if (this.environment == Environment.staging)
return environment == Environment.test;
return false;
}
}
/** Controls when this application will be upgraded to new Vespa versions */
public enum UpgradePolicy {
/** Canary: Applications with this policy will upgrade before any other */
canary,
/** Default: Will upgrade after all canary applications upgraded successfully. The default. */
defaultPolicy,
/** Will upgrade after most default applications upgraded successfully */
conservative
}
}
|
