Skip to content

Target environment doc changes #1070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 4, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 86 additions & 43 deletions documentation/2.0/content/userguide/target_env.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,101 @@ draft: false
weight: 2
---

### Contents

- [Overview](#overview)
- [Specifying a target environment](#specifying-a-target-environment)
- [Pre-configured target environments](#pre-configured-target-environments)
- [Using secret credentials in the model](#using-secret-credentials-in-the-model)
- [Target configuration files](#target-environment-configuration-files)

### Overview

The [Discover Domain]({{< relref "/userguide/tools/discover.md" >}}) and [Prepare Model]({{< relref "/userguide/tools/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]({{< relref "/concepts/model#model-tokens" >}}).
- Using Kubernetes secrets for credentials in the model.
- Applying filters to the model. See [Model filters]({{< relref "/userguide/tools-config/model_filters.md" >}}).
- Using model tokens for some attributes in the model. For more details, see [Model tokens]({{< relref "/concepts/model#model-tokens" >}}).
- Using Kubernetes secrets for credentials in the model. For more details, see [Using secret credentials in the model](#using-secret-credentials-in-the-model).
- Applying filters to the model. For more details, see [Model filters]({{< relref "/userguide/tools-config/model_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:
This command line shows how you can use these arguments 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
### Pre-configured target environments

These target environment configurations are included in the WebLogic Deploy Tooling installation.

#### The WebLogic Kubernetes Operator target

You can apply this target environment by providing the command-line argument `-target wko`. It will provide this additional processing:

- The `wko_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
- An additional Kubernetes resource file, `wko-domain.yaml`, will be produced, with cluster and naming information derived from the model

#### The Verrazzano target

You can apply this target environment 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 references to Kubernetes secrets, and a script to create those secrets will be produced
- One additional Kubernetes resource file, `vz-application.yaml`, will be produced, with cluster and data source information derived from the model

#### Generic Kubernetes target

You can apply this target environment 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

### Using secret credentials in the model

If a target environment is configured to use Kubernetes secrets for credential attribute values, each of those values is replaced with a token using the format `@@SECRET:@@ENV:DOMAIN_UID@@<secret-suffix>:<key>`. For example:
```yaml
PasswordEncrypted: '@@SECRET:@@ENV:DOMAIN_UID@@-jdbc-generic1:password@@'
```
When a domain is created or updated using a model with these tokens, the environment variable `DOMAIN_UID` should be set to the domain's UID, and secrets with corresponding names should have been created. For more details about using secret tokens, see [Model Tokens]({{< relref "/concepts/model#model-tokens" >}}).

For some target environments, the WebLogic admin credentials use a variation of this token format. For example:
```yaml
domainInfo:
AdminUserName: '@@SECRET:__weblogic-credentials__:username@@'
AdminPassword: '@@SECRET:__weblogic-credentials__:password@@'
```
In this case, the token `__weblogic-credentials__` allows these attributes to reference secrets in a specific location. The `WDT_MODEL_SECRETS_NAME_DIR_PAIRS` environment variable should be set to associate `__weblogic-credentials__` to this location. For example:
```shell
WDT_MODEL_SECRETS_NAME_DIR_PAIRS=__weblogic-credentials__=/etc/my-secrets
```
For more details about using the `WDT_MODEL_SECRETS_NAME_DIR_PAIRS` environment variable, see [Model Tokens]({{< relref "/concepts/model#model-tokens" >}}) .

In WebLogic Kubernetes Operator [Model in Image](https://oracle.github.io/weblogic-kubernetes-operator/userguide/managing-domains/model-in-image/) environments, the environment variable `DOMAIN_UID` is automatically set from the value in the domain resource file. The variable `WDT_MODEL_SECRETS_NAME_DIR_PAIRS` is automatically set to the directory containing WebLogic admin credentials.

#### The create secrets script

For target environments that use Kubernetes secret tokens, a shell script is created to generate the required secrets. The script is named `create_k8s_secrets.sh`, and is created in the target output directory. The script has commands to create each secret, for example:
```shell
# Update <user> and <password> for weblogic-credentials
create_paired_k8s_secret weblogic-credentials <user> <password>
```
The script should be updated with correct `<user>` and `<password>` values as required. It may be necessary to change the `NAMESPACE` and `DOMAIN_UID` variables at the top of the script if they are different in the target environment.

The script performs a check to determine if any generated secret names are more than 63 characters in length, because that will prevent them from being mounted correctly in the Kubernetes environment. If any secret names exceed this limit, they will need to be shortened in this script, in the model files, and in the domain resource file. Each shortened name should be distinct from other secret names.

### Target environment configuration files

A target environment is configured in a JSON file at this location:
```
Expand All @@ -37,6 +112,8 @@ The `<target-name>` value corresponds to the value of the `-target` argument on

You can define a new or extended target environment with a new `target-name` in the above location, or using a [Custom configuration]({{< relref "/userguide/tools-config/custom_config.md" >}}) directory, such as `$WDT_CUSTOM_CONFIG/target/<my-target-name>/target.json`.

You can customize existing template files for specific environments. The recommended method is to copy the original template to a custom configuration directory as described above, such as `$WDT_CUSTOM_CONFIG/target/<target-name>/model.yaml`. The copied file can then be edited as needed, while maintaining the original for reference.

Here is an example of a target environment file:
```
{
Expand All @@ -56,21 +133,21 @@ Here is an example of a target environment file:
"additional_output" : "vz-application.yaml"
}
```
Each of the fields in this example is optional, and can be customized.
Each of the fields in this example is optional, and you can customize them.

#### `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]({{< relref "/userguide/tools-config/model_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.
You can use the `@@TARGET_CONFIG_DIR@@` token 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]({{< relref "/userguide/tools/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.
You can use this field 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`

Expand All @@ -90,38 +167,4 @@ This field specifies a name for use with the WDT_MODEL_SECRETS_NAME_DIR_PAIRS en

#### `additional_output`

This field can be used to create additional output for use in the target environment. The value is a comma-separated list of template files in the `$WLSDEPLOY_HOME/lib/target/<target-name>` directory. These templates are populated with information derived from the model, and written to a file with the same name in the specified output directory.

Template files can be customized for specific environments. The recommended method is to copy the original template to a custom configuration directory as described above, such as `$WDT_CUSTOM_CONFIG/target/<target-name>/model.yaml`. The copied file can then be edited as needed, while maintaining the original for reference.

### Pre-configured target environments

These target environment configurations are included in the WebLogic Deploy Tooling installation.

#### The WebLogic Kubernetes Operator target

This target environment can be applied by providing the command-line argument `-target wko`. It will provide this additional processing:

- The `wko_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
- An additional Kubernetes resource file, `wko-domain.yaml`, will be produced, with cluster and naming information derived from the model

#### 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
- One additional Kubernetes resource file, `vz-application.yaml`, will be produced, with cluster and data source information derived from the model

#### Generic Kubernetes 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
You can use this field to create additional output for use in the target environment. The value is a comma-separated list of template files in the `$WLSDEPLOY_HOME/lib/target/<target-name>` directory. These templates are populated with information derived from the model, and written to a file with the same name in the specified output directory.