Skip to content

Commit 66cddd5

Browse files
Tom Barnesmarkxnelson
Tom Barnes
authored and
markxnelson
committed
Config overrides site doc (#642)
* Initial revision of config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc. * Revise config-overrides doc.
1 parent 0e9080d commit 66cddd5

File tree

1 file changed

+314
-0
lines changed

1 file changed

+314
-0
lines changed

‎site/config-overrides.md

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
# Configuration Overrides
2+
3+
**PLEASE NOTE**: This page is a work in progress.
4+
5+
---
6+
# Overview
7+
8+
Use configuration overrides to customize a WebLogic domain home configuration. For example, you may want to override a JDBC Datasource xml module Username, Password, and URL so that it references a local database.
9+
10+
How do you specify overrides?
11+
* Create a Kubernetes config map that contains
12+
* Situational config templates.
13+
* A file named 'version.txt' that contains the string '2.0'.
14+
* Set your Domain resource `configOverride` to the name of this config map.
15+
* Create Kubernetes secrets that contain template macro values.
16+
* Set your Domain `configOverrideSecrets` to reference the aforementioned secrets.
17+
* Start or restart your domain.
18+
19+
How do overrides work during runtime?
20+
* When a Domain is first deployed, or is restarted, the Operator will:
21+
* Resolve any macros in your override templates.
22+
* Place expanded override templates in the `optconfig` directory located in each WebLogic Domain Home directory.
23+
* When the WebLogic Servers start, they will:
24+
* Automatically load the override files from the `optconfig` directory.
25+
* Use the override values in the override files instead of the values specified in their config.xml or system resource xml.
26+
27+
Overrides can be used to customize domains as they are moved from QA to production, are deployed to different sites, or are even deployed multiple times at the same site.
28+
29+
---
30+
# Prerequisites
31+
32+
* A WebLogic Domain Home must not already contain situational config xml in its existing `optconfig` directory. Any existing situational config xml in this directory will be deleted and replaced by your Operator override templates (if any).
33+
34+
* If you want to override a JDBC, JMS, or WLDF module, the original module must be located in your Domain Home `config/jdbc`, `config/jms`, and `config/wldf` directory respectively. These are the default locations for these types of modules.
35+
36+
---
37+
# Typical Overrides
38+
39+
Typical attributes for overrides include:
40+
41+
* Usernames, Passwords, and URLs for
42+
* JDBC Datasources
43+
* JMS Bridges, Foreign Servers, and SAF
44+
* Network Channel Public Addresses
45+
* For remote RMI clients (T3, JMS, EJB, JTA)
46+
* For remote WLST clients
47+
* Debugging
48+
* Tuning (MaxMessageSize, etc.)
49+
50+
---
51+
# Unsupported Overrides
52+
53+
**IMPORTANT: The Operator does not support custom overrides in the following areas.**
54+
55+
* Domain topology (cluster members)
56+
* Network Channel Listen Address, Port, and Enabled configuration
57+
* Server and Domain log locations
58+
* Node manager related configuration.
59+
60+
**Specifically, do not use custom overrides for:**
61+
62+
* Adding/removing
63+
* Servers
64+
* Clusters
65+
* Network Access Points (Custom Channels)
66+
* Changing any of the following
67+
* Dynamic Cluster Size
68+
* Default, SSL, and Admin Channel 'Enabled', Listen Address, and Port
69+
* Network Access Point (Custom Channel) Listen Address or Port
70+
* Server and domain log locations -- use the logHome Domain setting instead
71+
* Node manager access credentials
72+
73+
In addition, it is not possible to use overrides to change the name of any bean.
74+
75+
Note that it's OK, even expected, to override Network Access Point 'public' or 'external' addresses and ports.
76+
77+
The behavior when using an unsupported override is undefined.
78+
79+
---
80+
# Override Template Names and Syntax
81+
82+
Overrides leverage a built-in WebLogic feature called 'Situational Config' (See [References](#References)). Situational config consists of XML formated files that closely resemble the structure of WebLogic config.xml and system resource module xml files. In addition, the attribute fields in these files can embed 'add', 'replace', and 'delete' verbs to specify the desired override action for the field.
83+
84+
## Override Template Names
85+
86+
The Operator requires a different file name format for override templates than WebLogic's built-in Situational Config feature. It converts the names to the format required by situational config when it moves the templates to the domain home `optconfig` directory. The following table describes the format:
87+
88+
| Original Config | Required Override Name |
89+
| --------------- | --------------------- |
90+
| `config.xml` | `config.xml` |
91+
| JMS module | `jms-MODULENAME.xml` |
92+
| JDBC module | `jdbc-MODULENAME.xml` |
93+
| WLDF module | `wldf-MODULENAME.xml` |
94+
95+
A `MODULENAME` must correspond to the mbean name of a system resource defined in your original config.xml.
96+
97+
## Override Template Schemas
98+
99+
An override template must define the exact schemas required by the Situational Config feature. The schemas vary based on the file type you wish to override.
100+
101+
_`config.xml`_
102+
```
103+
<?xml version='1.0' encoding='UTF-8'?>
104+
<domain xmlns="http://xmlns.oracle.com/weblogic/domain"
105+
xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
106+
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
107+
...
108+
<domain>
109+
```
110+
111+
_`jdbc-MODULENAME.xml`_
112+
```
113+
<?xml version='1.0' encoding='UTF-8'?>
114+
<jdbc-data-source xmlns="http://xmlns.oracle.com/weblogic/jdbc-data-source"
115+
xmlns:f="http://xmlns.oracle.com/weblogic/jdbc-data-source-fragment"
116+
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
117+
...
118+
<jdbc-data-source>
119+
```
120+
121+
_`jms-MODULENAME.xml`_
122+
```
123+
<weblogic-jms xmlns="http://xmlns.oracle.com/weblogic/weblogic-jms"
124+
xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-jms-fragment"
125+
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
126+
...
127+
<weblogic-jms>
128+
```
129+
130+
_`wldf-MODULENAME.xml`_
131+
```
132+
<?xml version='1.0' encoding='UTF-8'?>
133+
<wldf-resource
134+
xmlns:"http://xmlns.oracle.com/weblogic/weblogic-diagnostics"
135+
xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-diagnostics-fragment"
136+
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
137+
...
138+
<wldf-resource>
139+
```
140+
141+
## Override Template Macros
142+
143+
The Operator supports embedding macros within override templates. This helps make your templates flexibly handle multiple use cases, such as specifying a different URL, username, and password for a different deployment.
144+
145+
Two types of macros are supported 'environment variable macros' and 'secret macros':
146+
147+
* Environment variable macros have the syntax `${env:ENV-VAR-NAME}`, where the supported env vars include `DOMAIN_HOME`, `LOG_HOME`, and `DOMAIN_UID`.
148+
149+
* Secret macros have the syntax `${secret:SECRETNAME.SECRETKEY}` and `${secret:SECRETNAME.SECRETKEY:encrypt}`.
150+
151+
The secret macro SECRETNAME field must reference the name of a Kubernetes Secret, and the SECRETKEY field must reference a key within that secret. For example, if you have create a secret named `dbuser` with a key named `username` that contains the value `scott`, then the macro `${secret:dbuser.username}` will be replaced with the word `scott` before the template is copied into its WebLogic server pod.
152+
153+
**SECURITY NOTE:** Use the `:encrypt` suffix in a secret macro to encrypt its replacement value with the WebLogic WLST encrypt command (instead of leaving it at its plain text value). This is useful for overriding mbean attributes that expect encrypted values, such as the `password-encrypted` field of a data source, and is also useful for ensuring that a custom override situational config file the Operator places in the domain home does not expose passwords in plain-text.
154+
155+
## Override Template Samples
156+
157+
Here are some sample template override files. Use 'combine-mode="add"' to specify the values for mbean attributes that have not been set in the original configuration, and use the 'combine-mode="replace"' to specify the values for mbean fields that are already set in the original configuration.
158+
159+
**IMPORTANT: Your overrides may not take effect if you use 'add' for an mbean attribute that already has a value specified in your original configuration, or use 'replace' for an attribute that does not already exist.**
160+
161+
### Overriding 'config.xml'
162+
163+
The following `config.xml` override file demonstrates setting the 'max-message-size' field on a WebLogic Server named 'admin-server', and replacing the `public-address` and `public-port` fields with values obtained from a secret named `test-host` with keys `hostname` and `port`.
164+
165+
```
166+
<?xml version='1.0' encoding='UTF-8'?>
167+
<domain xmlns="http://xmlns.oracle.com/weblogic/domain"
168+
xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
169+
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
170+
<server>
171+
<name>admin-server</name>
172+
<max-message-size f:combine-mode="add">78787878</max-message-size>
173+
<network-access-point>
174+
<name>T3Channel</name>
175+
<public-address f:combine-mode="replace">${secret:test-host.hostname}</public-address>
176+
<public-port f:combine-mode="replace">${secret:test-host.port}</public-port>
177+
</network-access-point>
178+
</server>
179+
</domain>
180+
```
181+
182+
### Overriding a DataSource Module
183+
184+
The following `jdbc-testDS.xml` override file demonstrates setting the URL of a JDBC driver via secret. It overrides a datasource module named "testDS".
185+
186+
TBD expand this sample to include username and password.
187+
188+
```
189+
<?xml version='1.0' encoding='UTF-8'?>
190+
<jdbc-data-source xmlns="http://xmlns.oracle.com/weblogic/jdbc-data-source"
191+
xmlns:f="http://xmlns.oracle.com/weblogic/jdbc-data-source-fragment"
192+
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
193+
<name>testDS</name>
194+
<jdbc-driver-params>
195+
<url f:combine-mode="replace">${secret:dbsecret.url}</url>
196+
</jdbc-driver-params>
197+
</jdbc-data-source>
198+
```
199+
200+
---
201+
# Step-by-Step Guide
202+
203+
* Create a directory containing (A) a set of situational configuration templates for overriding the mbean properties you want to replace and (B) a version.txt file.
204+
* This directory must not contain any other files.
205+
* The version.txt file must contain only the string `2.0`.
206+
* Templates must not override the settings listed in [Unsupported Overrides](#unsupported-overrides).
207+
* Templates must be formatted and named as per [Override Template Names and Syntax](#override-template-names-and-syntax) and [References](#references).
208+
* Templates can embed macros that reference environement variables or Kubernetes secrets. See [Override Template Macros](#override-template-macros).
209+
* Create a kubernetes config map from the directory of templates.
210+
* The config map must be in the same kubernetes namespace as the domain.
211+
* If the config map is going to be used by a single DOMAIN_UID, it is recommended to add the 'weblogic.domainUID=<mydomainuid>' label to help track the resource.
212+
* For example, assuming './mydir' contains your version.txt and situation config template files:
213+
```
214+
kubectl -n MYNAMESPACE create cm MYCMNAME --from-file ./mydir
215+
kubectl -n MYNAMESPACE label cm MYCMNAME weblogic.domainUID=DOMAIN_UID
216+
```
217+
* Create any kubernetes secrets referenced by a template macro.
218+
* Secrets can have multiple keys (files) that can hold either cleartext or base64 values
219+
* Secrets must be in the same kubernetes namespace as the domain
220+
* If a secret is going to be used by a single DOMAIN_UID, it is recommended to add the 'weblogic.domainUID=<mydomainuid>' label to help track the resource.
221+
* For example:
222+
```
223+
kubectl -n MYNAMESPACE create secret generic my-secret --from-literal=key1=supersecret --from-literal=key2=topsecret
224+
kubectl -n MYNAMESPACE label secret my-secret weblogic.domainUID=DOMAIN_UID
225+
```
226+
* Configure the name of the config map in the Domain CR `configOverrides` field.
227+
* Configure the names of each secret in Domain CR.
228+
* If the secret contains the WebLogic admin `username` and `password` keys, set the Domain CR `webLogicCredentialsSecret` field.
229+
* For all other secrets, add them to Domain CR `configOverrideSecrets` field.
230+
* See [Debugging](#debugging) for ways to check if sit cfg is taking effect or if there are errors.
231+
232+
---
233+
# Debugging
234+
235+
* If WL pods do not come up at all, then:
236+
* In the domain's namespace, see if you can find a job named 'DOMAIN_UID-introspect-domain-job' and a corresponding pod named something like 'DOMAIN_UID-introspect-domain-job-xxxx'. If so, examine:
237+
* `kubectl -n MYDOMAINNAMESPACE describe job INTROSPECTJOBNAME`
238+
* `kubectl -n MYDOMAINNAMESPACE logs INTROSPECTPODNAME`
239+
* Check your operator log for Warning/Error/Severe messages.
240+
* `kubectl -n MYOPERATORNAMESPACE logs OPERATORPODNAME`
241+
242+
* If WL pods do start, then:
243+
* Search your admin server pod's `kubectl log` for the keyword `situational`, for example `kubectl logs MYADMINPOD | grep -i situational`.
244+
* The only WebLogic Server log lines that match should look something like like
245+
* `<Dec 14, 2018 12:20:47 PM UTC> <Info> <Management> <BEA-141330> <Loading situational config file: /shared/domains/domain1/optconfig/custom-situational-config.xml>`
246+
* This line indicates a situational config file has been loaded.
247+
* If the search yields Warning or Error lines, then the format of the custom situational config template is incorrect, and the Warning or Error text should describe the problem.
248+
* Look in your 'DOMAIN_HOME/optconfig' directory.
249+
* This directory, or a subdirectory within this directory, should contain each of your custom situational files.
250+
* If it doesn't, this likely indicates your Domain Resource configOverrides was not set to match your custom override config map name, or that your custom override config map does not contain your override files.
251+
252+
* If you'd like to verify that situational config is taking effect in the WebLogic bean tree, one way to do this is to compare the 'server config' and 'domain config' bean tree values.
253+
* The 'domain config' value should reflect the original value in your domain home configuration.
254+
* The 'server config' value should reflect the overridden value.
255+
* For example, assuming your DOMAIN_UID is `domain1`, and your domain contains a WebLogic Server named 'admin-server', then:
256+
257+
```
258+
kubectl exec -it domain1-admin-server /bin/bash
259+
$ wlst.sh
260+
> connect(MYADMINUSERNAME, MYADMINPASSWORD, 't3://domain1-admin-server:7001')
261+
> domainConfig()
262+
> get('/Servers/admin-server/MaxMessageSize')
263+
> serverConfig()
264+
> get('/Servers/admin-server/MaxMessageSize')
265+
> exit()
266+
```
267+
268+
**IMPORTANT: Custom override changes, such as updating an override config map, a secret, or a Domain resource, will not take effect until your Domain is restarted.**
269+
270+
**IMPORTANT: Incorrectly formatted override files are 'somewhat' silently ignored. WebLogic Servers log errors or warnings, but will still boot, and will skip overriding, when they detect an incorrectly formatted config override template file. So it is important to make sure template files are correct in a QA environment by checking your WebLogic Pod logs for situational config errors and warnings, before attempting to use them in production.**
271+
272+
---
273+
# Internal Design Flow
274+
275+
* When a Domain is first deployed, or is restarted, the operator runtime creates an introspector Kubernetes job named `DOMAIN_UID-introspect-domain-job`.
276+
* The introspector job's pod:
277+
* Mounts the Kubernetes config map and secrets specified via the operator Domain resource `configOverride`, `webLogicCredentialsSecret`, and `configOverrideSecrets` fields.
278+
* Reads the mounted situational config templates from the config map and expands them to create the actual situational config files for the domain:
279+
* It expands some fixed replaceable values (e.g. ${env:DOMAIN_UID}).
280+
* It expands referenced secrets by reading value from the corresponding mounted secret file (e.g. ${secret:mysecret.mykey}).
281+
* It optionally encrypts secrets using offline WLST to encrypt the value - useful for passwords (e.g. ${secret:mysecret.mykey:encrypt}).
282+
* It returns expanded situational config files to the operator.
283+
* It reports any errors when attempting expansion to the operator.
284+
* The operator runtime:
285+
* Reads the expanded situational config files and/or errors from the introspector.
286+
* And if the introspector reported no errors, it:
287+
* Puts situational config files in a config map named `DOMAIN_UID-weblogic-domain-introspect-cm`.
288+
* Mounts this config map into the WebLogic Server pods.
289+
* Starts the WebLogic Server pods.
290+
* Otherwise, if the introspector reported errors, it:
291+
* Logs warning, error, or severe messages.
292+
* Will not start WebLogic Server pods.
293+
* The startServer.sh script in the WebLogic Server pods
294+
* Copies the expanded situational config files to a special location where the WebLogic runtime can find them:
295+
* `config.xml` overrides are copied to the `optconfig` directory in its domain home.
296+
* Module overrides are copied to the `optconfig/jdbc`, `optconfig/jms`, or `optconfig/wldf` directory.
297+
* Deletes any situational config files in the `optconfig` directory that do not have corresponding template files in the config map.
298+
* WebLogic Servers read their overrides from their domain home's 'optconfig' directory.
299+
300+
---
301+
# Advanced Situational Config
302+
303+
WebLogic Situational Config feature provides advanced options and capabilities that are supported, but aren't covered in this document. For example, you can use a wildcard character in place of an mbean name. See [References](#references).
304+
305+
---
306+
# References
307+
308+
See the 'Managing Configuration Changes' chapter in 'Oracle Fusion Middleware Understanding Domain Configuration for Oracle WebLogic Sever' version TBD.
309+
310+
---
311+
# Release Notes
312+
313+
TBD These are to be moved to a central release notes section?
314+

0 commit comments

Comments
 (0)