Document vz target (#677)

* JIRA WDT-434 - Document Verrazzano target; migrate to separate topic, link with discover tool

* JIRA WDT-434 - Adjusted title levels after reorganization

* JIRA WDT-434 - Match titles to links after reorganization

* JIRA WDT-434 - Updates from review

Author: rakillen

README.md

@@ -35,6 +35,7 @@ Many organizations are using WebLogic Server, with or without other Oracle Fusio
     - [Using WDT with Oracle WebLogic Server Kubernetes Operator](site/kubernetes.md)
 - Tool Configuration
     - [Model Filters](site/tool_filters.md)
+    - [Target Environments](site/config/target_env.md)
     - [Type Definitions](site/type_def.md)
     - [Variable Injection](site/variable_injection.md)
     - [Custom Configuration](site/config/custom_configuration.md)

site/config/target_env.md

@@ -0,0 +1,95 @@
+## Target Environments
+
+The [Discover Domain](../discover.md) and [Prepare Model](../prepare.md) Tools allow you to customize the model and other files produced to be compatible with a specific target environment. Options for a target environment may include:
+- Using model tokens for some attributes in the model (see [Model Tokens](../../README.md#model-tokens))
+- Using Kubernetes secrets for credentials in the model
+- Applying filters to the model (see [Model Filters](../tool_filters.md))
+- Creating additional configuration files for the target system
+
+### Specifying a Target Environment
+
+Each tool specifies a target environment using the command-line argument `-target <target-name>`, where `<target-name>` refers to a pre-configured target environment, or a user-defined environment. In addition, the `-output_dir <output-directory>` argument specifies where the files for the target environment will be stored.
+
+This command line shows how these arguments can be used with the Discover Domain Tool:
+```yaml
+ $WLSDEPLOY_HOME/bin/discoverDomain.sh ... -target k8s -output_dir /etc/files
+```
+This example would apply the `k8s` target type to the discovery result, and place those files in `/etc/files`.
+
+If a variable file is specified on the tool's command line using the `-variable_file` argument, any injected variables will be added to that file. If no variable file is specified, injected variables will be written to the file `<output-directory>/<target_name>_variable.properties`.
+
+### The Target Configuration File 
+
+A target environment is configured in a JSON file at this location:
+```
+$WLSDEPLOY_HOME/lib/target/<target-name>/target.json
+```
+The `<target-name>` value corresponds to the value of the `-target` argument on the tool's command line. The WLS installation includes two pre-defined targets:
+ - [Oracle Weblogic Server Kubernetes Operator](#the-oracle-weblogic-server-kubernetes-operator-target) (named `k8s`)
+ - [Verrazzano](#the-verrazzano-target) (named `vz`). 
+
+You can define a new or extended target environment with a new `target-name` in the above location, or using a [Custom Configuration](custom_configuration.md) directory, such as `$WDT_CUSTOM_CONFIG/target/<my-target-name>/target.json`. 
+
+Here is an example of a target environment file:
+```
+{
+  "model_filters" : {
+        "discover": [
+          { "name": "k8s_prep", "path": "@@TARGET_CONFIG_DIR@@/k8s_operator_filter.py" }
+        ]
+      },
+  "variable_injectors" : {"PORT": {},"HOST": {},"URL": {}},
+  "validation_method" : "lax",
+  "credentials_method" : "secrets",
+  "additional_output" : "vz"
+}
+```
+Each of the fields in this example is optional, and can be customized.
+
+#### `model_filters`
+
+This field specifies the filters to be applied to the resulting model. This follows the same format and rules as the [Model Filters](../tool_filters.md) configuration. The `discover` type should always be used here.
+
+The `@@TARGET_CONFIG_DIR@@` token can be used to indicate that the specified filter is in the same directory as the target configuration file.  
+
+#### `variable_injectors`
+
+This field specifies the variable injectors to be applied to the resulting model. This follows the same format and rules as the [Variable Injectors](../variable_injection.md) configuration.
+
+#### `validation_method`
+
+This field can be used to set the validation level for the resulting model. Only the value `lax`is currently supported. With `lax` validation, variables and Kubernetes secrets referenced in the resulting model do not need to be available when the model is created.
+
+#### `credentials_method`
+
+This field specifies how credentials in the model should be handled. There are two values available:
+- `secrets` - the credentials in the model are replaced with references to Kubernetes secrets, and a UNIX script to create those secrets is produced.
+- `config_override_secrets` - the credentials in the model are replaced with placeholder values, such as `password1`, and a UNIX script to create corresponding Kubernetes secrets is produced.
+
+In both these cases, the script to create the Kubernetes secrets is written to `<output-directory>/create_k8s_secrets.sh`. You will need to update this script with credential values before executing
+
+#### `additional_output`
+
+This field can be used to create additional output for use in the target environment. The key `vz` is currently the only valid value for this field. It indicates that the tool should create additional Kubernetes resource files for use with the Verrazzano product.
+
+### Pre-configured Target Environments
+
+These target environment configurations are included in the WebLogic Deploy Tooling installation.
+
+#### The Oracle Weblogic Server Kubernetes Operator Target
+
+This target environment can be applied by providing the command-line argument `-target k8s`. It will provide this additional processing:
+
+- The `k8s_operator_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
+- Variables will be injected into the model for port, host, and URL attributes
+- `lax` validation will be applied for the resulting model
+- Credentials in the model will be replaced with references to Kubernetes secrets, and a script to create those secrets will be produced
+
+#### The Verrazzano Target
+This target environment can be applied by providing the command-line argument `-target vz`. It will provide this additional processing:
+
+- The `vz_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
+- Variables will be injected into the model for port, host, and URL attributes
+- `lax` validation will be applied for the resulting model
+- Credentials in the model will be replaced with placeholder values, and a script to create corresponding secrets will be produced
+- Two additional Kubernetes resource files, `model.yaml` and `binding.yaml`, will be produced, with cluster and data source information derived from the model

site/discover.md

@@ -39,6 +39,8 @@ Before the model is persisted to the model file, any variable injectors or model
  - [Model Filters](tool_filters.md)
  - [Validate Model Tool](validate.md)
 
+The resulting model can also be modified for compatibility with specific target environments, such as Oracle Weblogic Server Kubernetes Operator. For more information, see [Target Environments](config/target_env.md).
+
 Any problems (or success) will be listed in the discover tool summary. The summary will print the version of the tool and Oracle home, and the WLST mode with which the tool was run (online or offline). A recap of all Warning and Severe messages will be listed, along with a total. 
 
 An example of a summary with a WARNING message:

site/prepare.md

@@ -1,17 +1,17 @@
 ## The Prepare Model Tool
 
-The prepare model tool prepares WDT model files for deploying to the WebLogic Kubernetes Operator environment. It removes sections 
-from the model that are not compatible with the WebLogic Kubernetes Operator, replaces credential, endpoints fields with WDT macros, and generates 
-
-1. A UNIX shell script that will creates the necessary kubernetes secrets. The script can then be updated to provide the actual credentials.
-2. A variable property file. The file can be updated to customize the different end points.
-3. Updated model files
+The Prepare Model Tool prepares WDT model files for deploying to specific target environments. These customizations include:
+- Removing sections from the model that are not compatible with the environment
+- Replacing credential and attribute values with WDT macros
+- Generating a UNIX shell script that will help with creating any required Kubernetes secrets
+- Generating a variable properties file to customize attribute values
+- Updating the model file(s)
 
 To use the Prepare Model Tool, simply run the `prepareModel` shell script with the correct arguments.  To see the list of valid arguments, simply run the shell script with the `-help` option (or with no arguments) for usage information.
 
-To prepare model files, run the tool as follows:
+For example, to prepare model files for use with Oracle Weblogic Server Kubernetes Operator, run the tool with `-target k8s` as follows:
 ```
-$WLSDEPLOY_HOME/bin/prepareModel.sh -oracle_home /u01/wls12213 -model_file [command separed list of models] -target k8s -output_dir $HOME/k8soutput
+$WLSDEPLOY_HOME/bin/prepareModel.sh -oracle_home /u01/wls12213 -model_file model1.yaml, model2.yaml -target k8s -output_dir $HOME/k8soutput
 ```
 
 In the output directory, you will find:
@@ -22,43 +22,7 @@ create_k8s_secrets.sh
 k8s_variable.properties
 ```
 
-You can then customize the `k8s_variable.properties` and `create_k8s_secrets.sh` to provide environment specific values.
-
-## Customizing target 
-
-The '-target' parameter is referring to a file on the file system '$WLSDEPLOY_HOME/lib/target/<target value>/target.json'
-
-You also can configure a target in a [Custom Configuration](config/custom_configuration.md) directory, in `$WDT_CUSTOM_CONFIG/target/<target name>/target.json`. 
-
-It has the format:
-```
-{
-  "model_filters" : {
-        "discover": [
-          { "name": "k8s_prep", "path": "@@TARGET_CONFIG_DIR@@/k8s_operator_filter.py" }
-        ]
-      },
-  "variable_injectors" : {"PORT": {},"HOST": {},"URL": {}},
-  "validation_method" : "lax",
-  "credentials_method" : "secrets"
-}
-```
-
-The JSON file has several attributes that can be customized
-
-| Name | Description |
-| --- | --- |
-| model_filters | Specify the filters JSON configuration for the target configuration.  This follows the same schema of [Model Filters](tool_filters.md). Note only discover is valid | 
-| variable_injectors | Specify the variable injector JSON configuration for the target configuration.  This follows the same schema of [Model Filters](tool_filters.md)|
-| validation method | lax only |
-| credentials_method | "secrets" or "config_override_secrets" |
-
-`"@@TARGET_CONFIG_DIR@@` resolves to the '$WDT_INSTALL/lib/target/<target value>' directory.  
-
-If there is a need to customize your own filters or injectors, you can
+You can then customize the `k8s_variable.properties` and `create_k8s_secrets.sh` to provide environment-specific values.
 
-1. ```mkdir $WDT_INSTALL/lib/target/mytarget```
-2. Create a file named `target.json` following the schema above in $WLSDEPLOY_HOME/lib/target/mytarget
-3. Run the prepareModel command using the parameter -target mytarget
+For more information about additional target environments and options, see [Target Environments](config/target_env.md).
 
-Another option is to configure a new target in a [Custom Configuration](config/custom_configuration.md) directory. Create the `target/<target name>/target.json` file in the `$WDT_CUSTOM_CONFIG` directory. 

site/samples/configured_cluster.md

@@ -1,4 +1,4 @@
-## Configured Cluster Sample
+## Modeling a Configured Cluster
 
 This WDT domain model sample section has a typical configuration for a configured cluster with a single managed server, including connection information, logging setup, and other details. 
 

site/samples/jdbc.md

@@ -1,4 +1,4 @@
-## JDBC Sample
+## Modeling a JDBC Data Source
 
 This WDT domain model sample section has a typical configuration for a JDBC data source, including targeting information, connection pool parameters, and other details. 
 

site/samples/work_manager.md

@@ -1,4 +1,4 @@
-## Work Manager Sample
+## Modeling a Work Manager
 
 This WDT domain model sample section has typical configurations for a Work Manager and its related request classes and constraints. These elements are configured in the `SelfTuning` folder in the `resources` section of the model.
 ```yaml

site/security_providers.md

@@ -1,4 +1,4 @@
-### Modeling Security Providers
+## Modeling Security Providers
 WebLogic Server security configuration requires special handling and causes the need for the model semantics to differ from other folders.  Because provider ordering is important, and to make sure that the ordering is correctly set in the newly created domain, the Create Domain Tool and Update Domain Tool require that all providers be specified in the model for any provider type that will be created or altered.  For example, if you want to change one of the providers in the provider type `AuthenticationProvider`, your model must specify all of the `AuthenticationProvider` providers and any non-default attributes for those providers.  In order to apply security providers, these tools will delete all providers from the target domain for those provider types specified in the model before adding the providers from the model to the target domain. Provider types that are omitted from the model will be unchanged.  Example provider types are `Adjudicator`, `AuthenticationProvider`, `Authorizer`, `CertPathProvider`, `CredentialMapper`, `PasswordValidator`, and `RoleMapper`.
 
 For example, if the model specified an `LDAPAuthenticator` and an `LDAPX509IdentityAsserter` similar to what is shown below, the `DefaultAuthenticator` and `DefaultIdentityAsserter` would be deleted.  In this example, other provider types like `RoleMapper` and `CredentialMapper` are not specified and would be left untouched by the tools.   
@@ -90,7 +90,7 @@ topology:
                         DefaultIdentityAsserter:
 
 ```
-#### Trust Service Identity Asserter
+### Trust Service Identity Asserter
 
 **NOTE:** The Trust Identity Asserter Security Provider is installed by JRF in 12c versions and newer.
 
@@ -107,7 +107,7 @@ ORACLE_HOME/oracle_common/common/bin/prepareCustomProvider.sh -mjf=ORACLE_HOME/o
 For FMW versions 12.1.2 and 12.1.3, replace `oracle.jps` in the example path above with:
 oracle.jps_12.1.2, or oracle.jps_12.1.3, respectively.
 
-#### Custom Security Providers
+### Custom Security Providers
 
 **NOTE:** Creating and updating domains with custom security providers is limited to WebLogic version 12.1.2 and newer.
 
@@ -123,7 +123,7 @@ The format for a custom security provider is slightly different from a built-in
                     CredentialMappingDeploymentEnabled: true:
 ```
 
-#### Known Limitations
+### Known Limitations
 
 - `Adjudicator` provider types cannot be added or modified due to a limitation in WLST.
 - `PasswordCredentials` provider types cannot be updated in WLST online.

site/security_users_groups_roles.md

@@ -1,7 +1,7 @@
-### Modeling WebLogic Users, Groups, and Roles
+## Modeling WebLogic Users, Groups, and Roles
 WebLogic Server has the ability to establish a set of users, groups, and global roles as part of the WebLogic domain creation. The WebLogic global roles become part of the WebLogic role mapper (i.e. `XACMLRoleMapper`) and are specified under `domainInfo` in the `WLSRoles` section. The users and groups become part of the Embedded LDAP server (i.e. `DefaultAuthenticator`) and are specified under `topology` in the `Security` section.
 
-#### WebLogic Global Roles
+### WebLogic Global Roles
 The model allows for the definition of WebLogic roles that can augment the well known WebLogic global roles (e.g. `Admin`, `Deployer`, `Monitor`, ...) in addition to defining new roles. When updating the well known WebLogic roles, an `UpdateMode` can be specified as `{ append | prepend | replace }` with the default being `replace` when not specified. Also, when updating the well known roles, the specified `Expression` will be a logical `OR` with the default expression. The `Expression` value for the role is the same as when using the WebLogic `RoleEditorMBean` for a WebLogic security role mapping provider.
 
 For example, the `WLSRoles` section below updates the well known `Admin`, `Deployer` and `Monitor` roles while adding a new global role with `Tester` as the role name:
@@ -26,7 +26,7 @@ The `Admin` role will have the expression appended to the default expression, th
 
 In addition, the `Expression` value can use the variable placeholder syntax specified when running the [Create Tool](create.md) as shown in the above example.
 
-#### WebLogic Users and Groups
+### WebLogic Users and Groups
 The model allows for the definition of a set of users and groups that will be loaded into the WebLogic Embedded LDAP Server (i.e. `DefaultAuthenticator`). New groups can be specified and users can be added as members of the new groups or existing groups such as the `Administrators` group which is defaulted to be in the WebLogic `Admin` global role. Please see [known limitations](#known-limitations) below for additional information on users and groups.
 
 The user password can be specified with a placeholder or encrypted with the [Encrypt Tool](encrypt.md). An example `Security` section that adds an additional group `AppMonitors`, adds two new users and places the users into groups is as follows:
@@ -46,7 +46,7 @@ topology:
          GroupMemberOf: [ AppMonitors ]
 ```
 
-#### Known Limitations
+### Known Limitations
 
 - The processing of users, groups, and roles will only take place when using the [Create Domain Tool](create.md)
 - WebLogic global roles are only supported with WebLogic Server version 12.2.1 or greater

site/server_groups.md

@@ -1,4 +1,4 @@
-### Targeting Server Groups
+## Targeting Server Groups
 
 To create more complex domains with clusters of different types, it is necessary to control the targeting of server groups to managed servers.  By default, all server groups in the domain type definition are targeted to all managed servers.  To create a SOA domain with SOA and OSB clusters, simply add the OSB template and server group to the SOA domain definition, as shown below.
 
@@ -100,7 +100,7 @@ topology:
         NodeManagerPasswordEncrypted: welcome1
 ```
 
-#### Targeting Dynamic Cluster Server Groups
+### Targeting Dynamic Cluster Server Groups
 Dynamic Cluster Server Groups are server groups that can be targeted to dynamic clusters. Dynamic clusters were added in WebLogic Server version 12.1.2. In WebLogic Server version 12.2.1.1, the ability to target a single dynamic server group to a dynamic cluster was added. In WebLogic Server Version 12.2.1.4, you now have the ability to target multiple dynamic server groups to a dynamic cluster. 
 
 To enable targeting of dynamic server groups to dynamic clusters, add the dynamicClusterServerGroupsToTarget entry with any dynamic server groups you wish to be targeted to the dynamic clusters in your model or domain. This list must only contain one dynamic server group if you are running a version of WebLogic Server earlier than 12.2.1.4.