Skip to content

Commit 81e4f69

Browse files
rakillenrakillen
authored
Target environment doc changes (#1070)
* Re-organize and add secret credentials information * Revisions from doc review * Updated to clarify examples specific to model-in-image * Updated with link to Model in Image doc
1 parent d9aaf2b commit 81e4f69

File tree

1 file changed

+86
-43
lines changed

1 file changed

+86
-43
lines changed

‎documentation/2.0/content/userguide/target_env.md

Lines changed: 86 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -5,26 +5,101 @@ draft: false
55
weight: 2
66
---
77

8+
### Contents
9+
10+
- [Overview](#overview)
11+
- [Specifying a target environment](#specifying-a-target-environment)
12+
- [Pre-configured target environments](#pre-configured-target-environments)
13+
- [Using secret credentials in the model](#using-secret-credentials-in-the-model)
14+
- [Target configuration files](#target-environment-configuration-files)
15+
16+
### Overview
817

918
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:
10-
- Using model tokens for some attributes in the model. See [Model tokens]({{< relref "/concepts/model#model-tokens" >}}).
11-
- Using Kubernetes secrets for credentials in the model.
12-
- Applying filters to the model. See [Model filters]({{< relref "/userguide/tools-config/model_filters.md" >}}).
19+
- Using model tokens for some attributes in the model. For more details, see [Model tokens]({{< relref "/concepts/model#model-tokens" >}}).
20+
- Using Kubernetes secrets for credentials in the model. For more details, see [Using secret credentials in the model](#using-secret-credentials-in-the-model).
21+
- Applying filters to the model. For more details, see [Model filters]({{< relref "/userguide/tools-config/model_filters.md" >}}).
1322
- Creating additional configuration files for the target system.
1423

1524
### Specifying a target environment
1625

1726
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.
1827

19-
This command line shows how these arguments can be used with the Discover Domain Tool:
28+
This command line shows how you can use these arguments with the Discover Domain Tool:
2029
```yaml
2130
$ $WLSDEPLOY_HOME/bin/discoverDomain.sh ... -target k8s -output_dir /etc/files
2231
```
2332
This example would apply the `k8s` target type to the discovery result, and place those files in `/etc/files`.
2433

2534
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`.
2635

27-
### The target configuration file
36+
### Pre-configured target environments
37+
38+
These target environment configurations are included in the WebLogic Deploy Tooling installation.
39+
40+
#### The WebLogic Kubernetes Operator target
41+
42+
You can apply this target environment by providing the command-line argument `-target wko`. It will provide this additional processing:
43+
44+
- The `wko_operator_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
45+
- Variables will be injected into the model for port, host, and URL attributes
46+
- `lax` validation will be applied for the resulting model
47+
- Credentials in the model will be replaced with references to Kubernetes secrets, and a script to create those secrets will be produced
48+
- An additional Kubernetes resource file, `wko-domain.yaml`, will be produced, with cluster and naming information derived from the model
49+
50+
#### The Verrazzano target
51+
52+
You can apply this target environment by providing the command-line argument `-target vz`. It will provide this additional processing:
53+
54+
- The `vz_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
55+
- Variables will be injected into the model for port, host, and URL attributes
56+
- `lax` validation will be applied for the resulting model
57+
- Credentials in the model will be replaced with references to Kubernetes secrets, and a script to create those secrets will be produced
58+
- One additional Kubernetes resource file, `vz-application.yaml`, will be produced, with cluster and data source information derived from the model
59+
60+
#### Generic Kubernetes target
61+
62+
You can apply this target environment by providing the command-line argument `-target k8s`. It will provide this additional processing:
63+
64+
- The `k8s_operator_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
65+
- Variables will be injected into the model for port, host, and URL attributes
66+
- `lax` validation will be applied for the resulting model
67+
- Credentials in the model will be replaced with references to Kubernetes secrets, and a script to create those secrets will be produced
68+
69+
### Using secret credentials in the model
70+
71+
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:
72+
```yaml
73+
PasswordEncrypted: '@@SECRET:@@ENV:DOMAIN_UID@@-jdbc-generic1:password@@'
74+
```
75+
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" >}}).
76+
77+
For some target environments, the WebLogic admin credentials use a variation of this token format. For example:
78+
```yaml
79+
domainInfo:
80+
AdminUserName: '@@SECRET:__weblogic-credentials__:username@@'
81+
AdminPassword: '@@SECRET:__weblogic-credentials__:password@@'
82+
```
83+
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:
84+
```shell
85+
WDT_MODEL_SECRETS_NAME_DIR_PAIRS=__weblogic-credentials__=/etc/my-secrets
86+
```
87+
For more details about using the `WDT_MODEL_SECRETS_NAME_DIR_PAIRS` environment variable, see [Model Tokens]({{< relref "/concepts/model#model-tokens" >}}) .
88+
89+
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.
90+
91+
#### The create secrets script
92+
93+
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:
94+
```shell
95+
# Update <user> and <password> for weblogic-credentials
96+
create_paired_k8s_secret weblogic-credentials <user> <password>
97+
```
98+
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.
99+
100+
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.
101+
102+
### Target environment configuration files
28103

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

38113
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`.
39114

115+
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.
116+
40117
Here is an example of a target environment file:
41118
```
42119
{
@@ -56,21 +133,21 @@ Here is an example of a target environment file:
56133
"additional_output" : "vz-application.yaml"
57134
}
58135
```
59-
Each of the fields in this example is optional, and can be customized.
136+
Each of the fields in this example is optional, and you can customize them.
60137

61138
#### `model_filters`
62139

63140
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.
64141

65-
The `@@TARGET_CONFIG_DIR@@` token can be used to indicate that the specified filter is in the same directory as the target configuration file.
142+
You can use the `@@TARGET_CONFIG_DIR@@` token to indicate that the specified filter is in the same directory as the target configuration file.
66143

67144
#### `variable_injectors`
68145

69146
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.
70147

71148
#### `validation_method`
72149

73-
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.
150+
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.
74151

75152
#### `credentials_method`
76153

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

91168
#### `additional_output`
92169

93-
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.
94-
95-
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.
96-
97-
### Pre-configured target environments
98-
99-
These target environment configurations are included in the WebLogic Deploy Tooling installation.
100-
101-
#### The WebLogic Kubernetes Operator target
102-
103-
This target environment can be applied by providing the command-line argument `-target wko`. It will provide this additional processing:
104-
105-
- The `wko_operator_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
106-
- Variables will be injected into the model for port, host, and URL attributes
107-
- `lax` validation will be applied for the resulting model
108-
- Credentials in the model will be replaced with references to Kubernetes secrets, and a script to create those secrets will be produced
109-
- An additional Kubernetes resource file, `wko-domain.yaml`, will be produced, with cluster and naming information derived from the model
110-
111-
#### The Verrazzano target
112-
This target environment can be applied by providing the command-line argument `-target vz`. It will provide this additional processing:
113-
114-
- The `vz_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
115-
- Variables will be injected into the model for port, host, and URL attributes
116-
- `lax` validation will be applied for the resulting model
117-
- Credentials in the model will be replaced with placeholder values, and a script to create corresponding secrets will be produced
118-
- One additional Kubernetes resource file, `vz-application.yaml`, will be produced, with cluster and data source information derived from the model
119-
120-
#### Generic Kubernetes target
121-
122-
This target environment can be applied by providing the command-line argument `-target k8s`. It will provide this additional processing:
123-
124-
- The `k8s_operator_filter.py` filter will be applied to remove model elements that are not compatible with the Kubernetes environment
125-
- Variables will be injected into the model for port, host, and URL attributes
126-
- `lax` validation will be applied for the resulting model
127-
- Credentials in the model will be replaced with references to Kubernetes secrets, and a script to create those secrets will be produced
170+
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.

0 commit comments

Comments
 (0)