Merge pull request #1018 from oracle/cfg-over-doc-update

rjeberhard · web-flow · commit fc550386876c · 2019-04-10T19:08:56.000-04:00
Cfg override doc update
diff --git a/docs-source/content/userguide/managing-domains/configoverrides/_index.md b/docs-source/content/userguide/managing-domains/configoverrides/_index.md
@@ -87,13 +87,15 @@ Typical attributes for overrides include:
 * Server and domain log locations
 * Node Manager related configuration
 * Changing any existing MBean name
+* Adding or removing a module (for example, a JDBC module)
 
 **Specifically, do not use custom overrides for:**
 
 * Adding or removing:
   * Servers
   * Clusters
   * Network Access Points (custom channels)
+  * Modules
 * Changing any of the following:
   * Dynamic cluster size
   * Default, SSL, and Admin channel `Enabled`, listen address, and port
@@ -122,7 +124,7 @@ The operator requires a different file name format for override templates than W
 | 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.
+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.
 
 #### Override template schemas
 
@@ -184,24 +186,28 @@ The secret macro `SECRETNAME` field must reference the name of a Kubernetes secr
 
 #### Override template syntax special requirements
 
-**Check each item below to ensure custom situational configuration takes effect:**
+**Check each item below for best practices and to ensure custom situational configuration takes effect:**
 
 * Reference the name of the current bean and each parent bean in any hierarchy you override.
   * Note that the `combine-mode` verbs (`add` and `replace`) should be omitted for beans that are already defined in your original domain home configuration.
-     * See [Override template samples](#override-template-samples) for examples.
+       * See [Override template samples](#override-template-samples) for examples.
 * Use situational config `replace` and `add` verbs as follows:
   * If you are adding a new bean that doesn't already exist in your original domain home `config.xml`, then specify `add` on the MBean itself and on each attribute within the bean.
        * See the `server-debug` stanza in [Override template samples](#override-template-samples) for an example.
   * If you are adding a new attribute to an existing bean in the domain home `config.xml`, then the attribute needs an `add` verb.
        * See the `max-message-size` stanza in [Override template samples](#override-template-samples) for an example.
   * If you are changing the value of an existing attribute within a domain home `config.xml`, then the attribute needs a `replace` verb.
-    * See the `public-address` stanza in  [Override template samples](#override-template-samples) for an example.
+       * See the `public-address` stanza in  [Override template samples](#override-template-samples) for an example.
 * When overriding `config.xml`:
   * The XML namespace (`xmlns:` in the XML) must be exactly as specified in [Override template schemas](#override-template-schemas).
        * For example, use `d:` to reference `config.xml` beans and attributes, `f:` for `add` and `replace` `domain-fragment` verbs, and `s:` to reference the situational configuration schema.
   * Avoid specifying the domain name stanza, as this may cause some overrides to be ignored (for example, server-template scoped overrides).
 * When overriding modules:
   * It is a best practice to use XML namespace abbreviations `jms:`, `jdbc:`, and `wldf:` respectively for JMS, JDBC, and WLDF (diagnostics) module override files.
+  * A module must already exist in your original configuration if you want to override it; 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.
+  * See [Overriding a data source module](#overriding-a-data-source-module) for best practice advice. Note that similar advice applies generally to other module types.
+* Consider having your original configuration reference invalid user names, passwords, and URLs:
+  * If your original (non-overridden) configuration references non-working user names, passwords, and URLS, then this helps guard against accidentally deploying a working configuration that's invalid for the intended environment. For example, if your base configuration references a working QA database, and there is some mistake in setting up overrides, then it's possible the running servers will connect to the QA database when you deploy to your production environment.
 
 #### Override template samples
 
@@ -238,8 +244,13 @@ The following `config.xml` override file demonstrates:
 
 #### Overriding a data source module
 
-The following `jdbc-testDS.xml` override template demonstrates setting the URL, user name, and password-encrypted fields of a JDBC module named `testDS` via `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`.
+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:
+
+* A data source module must already exist in your original configuration if you want to override it; 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. See the next two bulleted items for the typical contents of a skeleton data source module.
+* Set your original (non-overridden) URL, username, and password to invalid values. This helps prevent accidentally starting a server without overrides, and then having the data source successfully connect to a database that's wrong for the current environment. For example, if these attributes are set to reference a QA database in your original configuration, then a mistake configuring overrides in your production Kubernetes deployment could cause your production applications to use your QA database.
+* Set your original (non-overridden) `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'?>
@@ -282,7 +293,7 @@ The following `jdbc-testDS.xml` override template demonstrates setting the URL,
     kubectl -n MYNAMESPACE label cm MYCMNAME weblogic.domainUID=DOMAIN_UID
     ```
 * Create any Kubernetes secrets referenced by a template 'secret macro'.
-  * Secrets can have multiple keys (files) that can hold either cleartext or base64 values. We recommend that you use base64 values for passwords via `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 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:
@@ -382,7 +393,7 @@ Incorrectly formatted override files may be accepted without warnings or errors
 
 * When a domain is first deployed, or is restarted, the operator runtime creates an introspector Kubernetes job named `DOMAIN_UID-introspect-domain-job`.
 * The introspector job's pod:
-  * Mounts the Kubernetes configuration map and secrets specified via the operator domain resource `configOverrides`, `webLogicCredentialsSecret`, and `configOverrideSecrets` fields.
+  * Mounts the Kubernetes configuration map and secrets specified by using the operator domain resource `configOverrides`, `webLogicCredentialsSecret`, and `configOverrideSecrets` fields.
   * Reads the mounted situational configuration templates from the configuration map and expands them to create the actual situational configuration files for the domain:
       * It expands some fixed replaceable values (for example, `${env:DOMAIN_UID}`).
       * It expands referenced secrets by reading the value from the corresponding mounted secret file (for example, `${secret:mysecret.mykey}`).
