Use configuration overrides (also called situational configuration) to customize a WebLogic domain home configuration without modifying the domain’s actual config.xml or system resource files. For example, you may want to override a JDBC data source XML module user name, password, and URL so that it references a local database.
You can use overrides 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.
version.txt that contains the exact string 2.0.configOverrides to the name of this configuration map.secret macros:
configOverrideSecrets to reference the aforementioned secrets.For a detailed walk-through of these steps, see the Step-by-step guide.
optconfig directory located in each WebLogic domain home directory.optconfig directory.config.xml or system resource XML files.For a detailed walk-through of the runtime flow, see the Internal design flow.
A WebLogic domain home must not contain any situational configuration XML file in its optconfig directory that was not placed there by the operator. Any existing situational configuration XML files in this directory will be deleted and replaced by your operator override templates (if any).
If you want to override a JDBC, JMS, or WLDF (diagnostics) module, then the original module must be located in your domain home config/jdbc, config/jms, and config/diagnostics directory, respectively. These are the default locations for these types of modules.
Typical attributes for overrides include:
MaxMessageSize, and such)IMPORTANT: The operator does not support custom overrides in the following areas.
Specifically, do not use custom overrides for:
Enabled, listen address, and portlogHome domain setting insteadNote that it’s OK, even expected, to override Network Access Point public or external addresses and ports. Also note that external access to JMX (MBean) or online WLST requires that the Network Access Point internal port and external port match (external T3 or HTTP tunneling access to JMS, RMI, or EJBs don’t require port matching).
The behavior when using an unsupported override is undefined.
Overrides leverage a built-in WebLogic feature called “Configuration Overriding” which is often informally called “Situational Configuration.” Situational configuration consists of XML formatted 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.
The operator requires a different file name format for override templates than WebLogic’s built-in situational configuration feature. It converts the names to the format required by situational configuration when it moves the templates to the domain home optconfig directory. The following table describes the format:
| Original Configuration | Required Override Name |
|---|---|
config.xml |
config.xml |
| JMS module | jms-MODULENAME.xml |
| JDBC module | jdbc-MODULENAME.xml |
| Diagnostics module | diagnostics-MODULENAME.xml |
A MODULENAME must correspond to the MBean name of a system resource defined in your original config.xml file. It’s not possible to add a new module by using overrides. If you need your overrides to set up a new module, then have your original configuration specify ‘skeleton’ modules that can be overridden.
An override template must define the exact schemas required by the situational configuration feature. The schemas vary based on the file type you wish to override.
config.xml
<?xml version='1.0' encoding='UTF-8'?>
<d:domain xmlns:d="http://xmlns.oracle.com/weblogic/domain"
xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
...
</d:domain>
jdbc-MODULENAME.xml
<?xml version='1.0' encoding='UTF-8'?>
<jdbc:jdbc-data-source xmlns:jdbc="http://xmlns.oracle.com/weblogic/jdbc-data-source"
xmlns:f="http://xmlns.oracle.com/weblogic/jdbc-data-source-fragment"
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
...
</jdbc:jdbc-data-source>
jms-MODULENAME.xml
<?xml version='1.0' encoding='UTF-8'?>
<jms:weblogic-jms xmlns:jms="http://xmlns.oracle.com/weblogic/weblogic-jms"
xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-jms-fragment"
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
...
</jms:weblogic-jms>
diagnostics-MODULENAME.xml
<?xml version='1.0' encoding='UTF-8'?>
<wldf:wldf-resource xmlns:wldf="http://xmlns.oracle.com/weblogic/weblogic-diagnostics"
xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-diagnostics-fragment"
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
...
</wldf:wldf-resource>
The operator supports embedding macros within override templates. This helps make your templates flexibly handle multiple use cases, such as specifying a different URL, user name, and password for a different deployment.
Two types of macros are supported, environment variable macros and secret macros:
Environment variable macros have the syntax ${env:ENV-VAR-NAME}, where the supported environment variables include DOMAIN_UID, DOMAIN_NAME, DOMAIN_HOME, and LOG_HOME.
Secret macros have the syntax ${secret:SECRETNAME.SECRETKEY} and ${secret:SECRETNAME.SECRETKEY:encrypt}.
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 created 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.
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 configuration file the operator places in the domain home does not expose passwords in plain-text.
Check each item below for best practices and to ensure custom situational configuration takes effect:
combine-mode verbs (add and replace) should be omitted for beans that are already defined in your original domain home configuration.
replace and add verbs as follows:
config.xml, then specify add on the MBean itself and on each attribute within the bean.
server-debug stanza in Override template samples for an example.config.xml, then the attribute needs an add verb.
max-message-size stanza in Override template samples for an example.config.xml, then the attribute needs a replace verb.
public-address stanza in Override template samples for an example.config.xml:
xmlns: in the XML) must be exactly as specified in Override template schemas.
d: to reference config.xml beans and attributes, f: for add and replace domain-fragment verbs, and s: to reference the situational configuration schema.jms:, jdbc:, and wldf: respectively for JMS, JDBC, and WLDF (diagnostics) module override files.Here are some sample template override files.
config.xmlThe following config.xml override file demonstrates:
max-message-size field on a WebLogic Server named admin-server. It assumes the original config.xml does not define this value, and so uses add instead of replace.public-address and public-port fields with values obtained from a secret named test-host with keys hostname and port. It assumes the original config.xml already sets these fields, and so uses replace instead of add.server-debug stanza, so it uses add throughout the entire stanza.<?xml version='1.0' encoding='UTF-8'?>
<d:domain xmlns:d="http://xmlns.oracle.com/weblogic/domain"
xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
<d:server>
<d:name>admin-server</d:name>
<d:max-message-size f:combine-mode="add">78787878</d:max-message-size>
<d:server-debug f:combine-mode="add">
<d:debug-server-life-cycle f:combine-mode="add">true</d:debug-server-life-cycle>
<d:debug-jmx-core f:combine-mode="add">true</d:debug-jmx-core>
</d:server-debug>
<d:network-access-point>
<d:name>T3Channel</d:name>
<d:public-address f:combine-mode="replace">${secret:test-host.hostname}</d:public-address>
<d:public-port f:combine-mode="replace">${secret:test-host.port}</d:public-port>
</d:network-access-point>
</d:server>
</d:domain>
The following jdbc-testDS.xml override template demonstrates setting the URL, user name, and password-encrypted fields of a JDBC module named testDS by using secret macros. The generated situational configuration that replaces the macros with secret values will be located in the DOMAIN_HOME/optconfig/jdbc directory. The password-encrypted field will be populated with an encrypted value because it uses a secret macro with an :encrypt suffix. The secret is named dbsecret and contains three keys: url, username, and password.
Best practices for data source modules and their overrides:
JDBCConnectionPoolParams MinCapacity and InitialCapacity to 0, and set your original DriverName to a reference an existing JDBC Driver. This ensures that you can still successfully boot a server even when you have configured invalid URL/username/password values, your database isn’t running, and/or you haven’t specified your overrides yet.<?xml version='1.0' encoding='UTF-8'?>
<jdbc:jdbc-data-source xmlns:jdbc="http://xmlns.oracle.com/weblogic/jdbc-data-source"
xmlns:f="http://xmlns.oracle.com/weblogic/jdbc-data-source-fragment"
xmlns:s="http://xmlns.oracle.com/weblogic/situational-config">
<jdbc:name>testDS</jdbc:name>
<jdbc:jdbc-driver-params>
<jdbc:url f:combine-mode="replace">${secret:dbsecret.url}</jdbc:url>
<jdbc:properties>
<jdbc:property>
<jdbc:name>user</jdbc:name>
<jdbc:value f:combine-mode="replace">${secret:dbsecret.username}</jdbc:value>
</jdbc:property>
</jdbc:properties>
<jdbc:password-encrypted f:combine-mode="replace">${secret:dbsecret.password:encrypt}</jdbc:password-encrypted>
</jdbc:jdbc-driver-params>
</jdbc:jdbc-data-source>
version.txt file.
version.txt file must contain exactly the string 2.0.
2.0 even when you are updating your templates from a previous deployment.The configuration map must be in the same Kubernetes namespace as the domain.
If the configuration map is going to be used by a single DOMAIN_UID, then we recommend adding the weblogic.domainUID=<mydomainuid> label to help track the resource.
For example, assuming ./mydir contains your version.txt and situation configuration template files:
kubectl -n MYNAMESPACE create cm MYCMNAME --from-file ./mydir
kubectl -n MYNAMESPACE label cm MYCMNAME weblogic.domainUID=DOMAIN_UID
Secrets can have multiple keys (files) that can hold either cleartext or base64 values. We recommend that you use base64 values for passwords by using Opaque type secrets in their data field, so that they can’t be easily read at a casual glance. For more information, see https://kubernetes.io/docs/concepts/configuration/secret/.
Secrets must be in the same Kubernetes namespace as the domain.
If a secret is going to be used by a single DOMAIN_UID, then we recommend adding the weblogic.domainUID=<mydomainuid> label to help track the resource.
For example:
kubectl -n MYNAMESPACE create secret generic my-secret --from-literal=key1=supersecret --from-literal=key2=topsecret
kubectl -n MYNAMESPACE label secret my-secret weblogic.domainUID=DOMAIN_UID
configOverrides field.username and password keys, then set the domain CR webLogicCredentialsSecret field.configOverrideSecrets field. Note: This must be in an array format even if you only add one secret (see the sample domain resource YAML below).serverStartPolicy to NEVER, wait, and apply your latest domain resource with the serverStartPolicy restored back to ALWAYS or IF_NEEDED (See Starting and stopping servers.)Example domain resource YAML:
apiVersion: "weblogic.oracle/v2"
kind: Domain
metadata:
name: domain1
namespace: default
labels:
weblogic.resourceVersion: domain-v2
weblogic.domainUID: domain1
spec:
[ ... ]
webLogicCredentialsSecret:
name: domain1-wl-credentials-secret
configOverrides: domain1-overrides-config-map
configOverrideSecrets: [my-secret, my-other-secret]
[ ... ]
Incorrectly formatted override files may be accepted without warnings or errors and may not prevent WebLogic pods from booting. So, it is important to make sure that the template files are correct in a QA environment, otherwise your WebLogic Servers may start even though critically required overrides are failing to take effect.
On WebLogic Servers that support the weblogic.SituationalConfig.failBootOnError system property ( Note: It is not supported in WebLogic Server 12.2.1.3.0 ),
by default the WebLogic server will fail to boot if any situational configuration files are invalid,
or if it encounters an error while loading situational configuration files.
By setting the FAIL_BOOT_ON_SITUATIONAL_CONFIG_ERROR environment variable in the Kubernetes containers for the WebLogic Servers to false, you can start up the WebLogic Servers even with incorrectly formatted override files.
Make sure you’ve followed each step in the Step-by-step guide.
If WebLogic pods do not come up at all, then:
DOMAIN_UID-introspect-domain-job and a corresponding pod named something like DOMAIN_UID-introspect-domain-job-xxxx. If so, examine:
kubectl -n MYDOMAINNAMESPACE describe job INTROSPECTJOBNAMEkubectl -n MYDOMAINNAMESPACE logs INTROSPECTPODNAMEkubectl -n MYOPERATORNAMESPACE logs OPERATORPODNAMEIf WebLogic pods do start, then:
kubectl log for the keyword situational, for example kubectl logs MYADMINPOD | grep -i situational.
<Dec 14, 2018 12:20:47 PM UTC> <Info> <Management> <BEA-141330> <Loading situational configuration file: /shared/domains/domain1/optconfig/custom-situational-config.xml>java.lang.NullPointerException
at weblogic.management.provider.internal.situationalconfig.SituationalConfigManagerImpl.registerListener(SituationalConfigManagerImpl.java:227)
at weblogic.management.provider.internal.situationalconfig.SituationalConfigManagerImpl.start(SituationalConfigManagerImpl.java:319)
...
at weblogic.management.configuration.DomainMBeanImpl.setJDBCSystemResources(DomainMBeanImpl.java:11444)
...
DOMAIN_HOME/optconfig directory.
configOverrides was not set to match your custom override configuration map name, or that your custom override configuration map does not contain your override files.If the Administration Server pod does start but fails to reach ready state or tries to restart:
WebLogic server failed to start due to missing or invalid situational configuration files in the Administration Server pod’s kubectl log
situational may be found in the Administration Server pod log to provide more hints.<Jun 20, 2019 3:48:45 AM GMT> <Warning> <Management> <BEA-141323> <The situational config file has an invalid format, it is being ignored: XMLSituationalConfigFile[/shared/domains/domain1/optconfig/jdbc/testDS-0527-jdbc-situational-config.xml] because org.xml.sax.SAXParseException; lineNumber: 8; columnNumber: 3; The element type "jdbc:jdbc-driver-params" must be terminated by the matching end-tag "</jdbc:jdbc-driver-params>".If you’d like to verify that the situational configuration is taking effect in the WebLogic MBean tree, then one way to do this is to compare the server config and domain config MBean tree values.
domain config value should reflect the original value in your domain home configuration.server config value should reflect the overridden value.DOMAIN_UID is domain1, and your domain contains a WebLogic Server named admin-server, then:kubectl exec -it domain1-admin-server /bin/bash
$ wlst.sh
> connect(MYADMINUSERNAME, MYADMINPASSWORD, 't3://domain1-admin-server:7001')
> domainConfig()
> get('/Servers/admin-server/MaxMessageSize')
> serverConfig()
> get('/Servers/admin-server/MaxMessageSize')
> exit()
To cause the WebLogic situational configuration feature to produce additional debugging information in the WebLogic Server logs, configure the JAVA_OPTIONS environment variable in your domain resource with:
-Dweblogic.debug.DebugSituationalConfig=true
-Dweblogic.debug.DebugSituationalConfigDumpXml=true
DOMAIN_UID-introspect-domain-job.configOverrides, webLogicCredentialsSecret, and configOverrideSecrets fields.${env:DOMAIN_UID}).${secret:mysecret.mykey}).${secret:mysecret.mykey:encrypt}).DOMAIN_UID-weblogic-domain-introspect-cm.startServer.sh script in the WebLogic Server pods:
config.xml overrides are copied to the optconfig directory in its domain home.optconfig/jdbc, optconfig/jms, or optconfig/diagnostics directory.optconfig directory that do not have corresponding template files in the configuration map.optconfig directory.