Skip to content

Commit 7b34370

Browse files
rjeberhardrjeberhard
authored
Merge pull request #675 from oracle/feature-server-lifecycle-site-doc
WIP - Feature server lifecycle site doc
2 parents 239a20a + 551bad9 commit 7b34370

File tree

2 files changed

+235
-1
lines changed

2 files changed

+235
-1
lines changed

‎site/domains.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Configuration overrides allow changing a configuration without modifying its ori
107107
### Managing lifecycle operations
108108

109109
In Operator 2.0 you can perform lifecycle operations on WebLogic servers, clusters, or domains.
110-
* Point to the documentation on how to manage lifecycle operations.
110+
See [Starting, stopping and restarting servers](server-lifecycle.md).
111111

112112
### Patching WebLogic and performing application updates
113113

‎site/server-lifecycle.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Starting, Stopping and Restarting Servers
2+
3+
This document describes how the user can start, stop and restart the domain's servers.
4+
5+
## Overview
6+
7+
There are properties on the domain resource that specify which servers should be running
8+
and which servers should be restarted.
9+
10+
To start, stop or restart servers, the should user modify these properties on the domain resource
11+
(e.g. using kubectl or the Kubernetes REST api). The operator will notice the changes
12+
and apply them.
13+
14+
## Starting and Stopping Servers
15+
16+
The "serverStartPolicy" property on domain resource controls which servers should be running.
17+
The operator runtime monitors this property and creates or deletes the corresponding server pods.
18+
19+
### "serverStartPolicy" Rules
20+
21+
"serverStartPolicy" can be specified at the domain, cluster and server levels. Each level supports a different set of values:
22+
23+
#### Available serverStartPolicy Values
24+
| Level | Default Value | Supported Values |
25+
| --- | --- | --- |
26+
| Domain | IF_NEEDED | IF_NEEDED, ADMIN_ONLY, NEVER |
27+
| Cluster | IF_NEEDED | IF_NEEDED, NEVER |
28+
| Server | IF_NEEDED | IF_NEEDED, ALWAYS, NEVER |
29+
30+
#### Admin Server Start/Stop Rules
31+
| Domain | Admin Server | Started / Stopped |
32+
| --- | --- | --- |
33+
| NEVER | any value | Stopped |
34+
| ADMIN_ONLY, IF_NEEDED | NEVER | Stopped |
35+
| ADMIN_ONLY, IF_NEEDED | IF_NEEDED, ALWAYS | Started |
36+
37+
#### Standalone Managed Server Start/Stop Rules
38+
| Domain | Standalone Server | Started / Stopped |
39+
| --- | --- | --- |
40+
| ADMIN_ONLY, NEVER | any value | Stopped |
41+
| IF_NEEDED | NEVER | Stopped |
42+
| IF_NEEDED | IF_NEEDED, ALWAYS | Started |
43+
44+
#### Clustered Managed Server Start/Stop Rules
45+
| Domain | Cluster | Clustered Server | Started / Stopped |
46+
| --- | --- | --- | --- |
47+
| ADMIN_ONLY, NEVER | any value | any value | Stopped |
48+
| IF_NEEDED | NEVER | any value | Stopped |
49+
| IF_NEEDED | IF_NEEDED | NEVER | Stopped |
50+
| IF_NEEDED | IF_NEEDED | ALWAYS | Started |
51+
| IF_NEEDED | IF_NEEDED | IF_NEEDED | Started if needed to get to the cluster's "replicas" count |
52+
53+
Note: servers configured as ALWAYS count towards the cluster's "replicas" count.
54+
55+
Note: if more servers are configured as ALWAYS than the cluster's "replicas" count, they will all be started and the "replicas" count will be ignored.
56+
57+
### Common Scenarios
58+
59+
#### Normal Running State
60+
Normally, the admin server, all of the stand alone managed servers, and enough managed servers in each cluster to satisfy its "replicas" count should be started.
61+
In this case, the domain resource does not need to specify "serverStartPolicy", or list any "clusters" or "servers", but it does need to specify a "replicas" count.
62+
63+
For example:
64+
```
65+
domain:
66+
spec:
67+
image: ...
68+
replicas: 10
69+
```
70+
71+
#### Shut Down All the Servers
72+
Sometimes the user needs to completely shut down the domain (i.e. take it out of service).
73+
```
74+
domain:
75+
spec:
76+
serverStartPolicy: "NEVER"
77+
...
78+
```
79+
80+
#### Only Start the Admin Server
81+
Sometimes the user wants to only start the admin server, that is, take the domain out of service but leave the admin server running so that the user can administer the domain.
82+
```
83+
domain:
84+
spec:
85+
serverStartPolicy: "ADMIN_ONLY"
86+
...
87+
```
88+
89+
#### Shut Down A Cluster
90+
To shut down a cluster (i.e. take it out of service), add it to the domain resource and set its "serverStartPolicy" to "NEVER".
91+
```
92+
domain:
93+
spec:
94+
clusters:
95+
- clusterName: "cluster1"
96+
serverStartPolicy: "NEVER"
97+
...
98+
```
99+
100+
#### Shut Down a Specific Stand Alone Server
101+
To shut down a specific stand alone server, add it to the domain resource and set its "serverStartPolicy" to "NEVER"
102+
```
103+
domain:
104+
spec:
105+
managedServers:
106+
- serverName: "server1"
107+
serverStartPolicy: "NEVER"
108+
...
109+
```
110+
111+
#### Force a Specific Clustered Managed Server To Start
112+
Normally, all of the managed servers in a cluster are identical and it doesn't matter which ones are running as long as the operator starts enough to get to the cluster's "replicas" count.
113+
However, sometimes some of the managed servers are different (e.g support some extra services that the other servers in the cluster use) and need to always to started.
114+
115+
This is done by adding the server to the domain resource and settings its "serverStartPolicy" to "ALWAYS".
116+
```
117+
domain:
118+
spec:
119+
managedServers:
120+
- serverName: "cluster1_server1"
121+
serverStartPolicy: "ALWAYS"
122+
...
123+
```
124+
125+
Note: the server will count towards the cluster's "replicas" count. Also, if the user configures more than "replicas" servers to "ALWAYS", they will all be started, even though "replicas" will be exceeded.
126+
127+
## Restarting Servers
128+
129+
The operator runtime automatically recreates (restarts) server pods when properties on the domain resource that affect server pods change (such as "image", "volumes" and "env").
130+
The "restartVersion" property on the domain resource lets the user force the operator to restart a set of server pods.
131+
132+
The operator runtime does rolling restarts of clustered servers so that service is maintained.
133+
134+
### Properties that Cause Servers To Be Restarted
135+
The operator will restart servers when any of the follow properties on the domain resource that affect the server are changed:
136+
* annotations
137+
* containerSecurityContext
138+
* domainHome
139+
* domainHomeInImage
140+
* env
141+
* image
142+
* imagePullPolicy
143+
* imagePullSecrets
144+
* includeServerOutInPodLog
145+
* labels
146+
* logHomeEnabled
147+
* logHome
148+
* livenessProbe
149+
* nodeSelector
150+
* podSecurityContext
151+
* readinessProbe
152+
* resources
153+
* restartVersion
154+
* serverStartState
155+
* volumes
156+
* volumeMounts
157+
158+
TBD - do we need to include this table? Also, Russ is still working on implementing this feature for 2.0.
159+
160+
### Rolling Restarts
161+
162+
Clustered servers that need to be restarted are gradually restarted (i.e. 'rolling restarted') so that the cluster is not taken out of service and in-flight work can be migrated to other servers in the cluster.
163+
164+
The "maxUnavailable" property on the domain resource determines how many of the cluster's servers may be taken out of service at a time when doing a rolling restart.
165+
It can be specified at the domain and cluster levels and defaults to 1 (that is, by default, clustered servers are restarted one at a time).
166+
167+
### Using restartVersion to Force the Operator to Restart Servers
168+
169+
The "restartVersion" property lets users force the operator to restart servers.
170+
171+
It's basically a user-specified string that gets added to new server pods (as a label) so that the operator can tell which servers need to be restarted.
172+
If the value is different, then the server pod is old and needs to be restarted. If the value matches, then the server pod has already been restarted.
173+
174+
Each time the user wants to restart some servers, the user needs to set "restartVersion" to a different string (the particular value doesn't matter).
175+
176+
The operator will notice the new value and restart the affected servers (using the same mechanisms as when other properties that affect the server pods are changed, including doing rolling restarts of clustered servers).
177+
178+
"restartVersion" can be specified at the domain, cluster and server levels. A server will be restarted if any of these three values change.
179+
180+
Note: the servers will also be restarted if restartVersion is removed from the domain resource (for example, if the user had previously specified a value to cause a restart then the user removes that value after the previous restart has completed).
181+
182+
### Common Scenarios
183+
184+
#### Restart All the Servers in the Domain
185+
186+
Set "restartVersion" at the domain level to a new value.
187+
188+
```
189+
domain:
190+
spec:
191+
restartVersion: "domainV1"
192+
...
193+
```
194+
195+
#### Restart All the Servers in the Cluster
196+
197+
Set "restartVersion" at the cluster level to a new value.
198+
199+
```
200+
domain:
201+
spec:
202+
clusters:
203+
- clusterName : "cluster1"
204+
restartVersion: "cluster1V1"
205+
maxUnavailable: 2
206+
...
207+
```
208+
209+
#### Restart the Admin Server
210+
211+
Set "restartVersion" at the adminServer level to a new value.
212+
213+
```
214+
domain:
215+
spec:
216+
adminServer:
217+
restartVersion: "adminV1"
218+
...
219+
```
220+
221+
#### Restart a Standalone or Clustered Manged Server
222+
223+
Set "restartVersion" at the managedServer level to a new value.
224+
225+
```
226+
domain:
227+
spec:
228+
managedServers:
229+
- serverName: "standalone_server1"
230+
restartVersion: "v1"
231+
- serverName: "cluster1_server1"
232+
restartVersion: "v1"
233+
...
234+
```

0 commit comments

Comments
 (0)