Creating Your Own UIM Cloud Native Instance

Customizing UIM Configuration Properties

You use files to control many aspects of UIM performance and configuration. These system configuration files are located in UIM_builder_toolkit/staging/cnsdk/uim-model/UIM/config. Each file includes properties for which you can set values. See UIM System Administrator's Guide for more information on property files and their contents.

In cloud native, these system configuration files are packaged into docker image while building the image and these files are available under /UIM/config folder within the pods.

Sample system configuration custom-config.properties.sample file is provided under $UIM_CNTK/charts/uim/config/system-config folder. If you are doing it for the first time, copy the sample property file to custom-config.properties and add key value to override the default value provided out-of-the-box for any specific system configuration property. The properties defined in custom-config.properties file are fed into the container using Kubernetes configuration maps. Any changes to these properties require the instance to be upgraded. Some properties can be updated dynamically and some may require rolling restart.

For properties with dynamic updates, run the following command after you change the property values:

$UIM_CNTK/scripts/upgrade-instance.sh -p project -i instance -s $SPEC_PATH

For properties with rolling restarts, run the following command after you change the property values:

$UIM_CNTK/scripts/restart-instance.sh -p project -i instance -s $SPEC_PATH -r ms

Sample custom-config.properties File

The sample custom-config.properties file is as follows:

#Add the overridden value for key in this custom-config.property file
ui.lastSavedSearch=true
 
# MapViewer Url, use this entry if mapviewer is running in a seperate domain
mapviewerUrl=http://hostname:port/mapviewer
 
#Timer properties
#Add new set of timers
#timer.MyTestingTimer.firstTime=120
#timer.MyTestingTimer.period=120
#timer.MyTestingTimer.listener=oracle.communications.customtimer.MyTestingTimer

Adding New Properties

You can add new properties in either of the following ways:

Define configuration files in solution cartridges. These configuration files are packaged into the customized docker image. See "Customizing Images" for more information. You need to build the image and restart the application in case of any changes to these properties.
Update custom-config.properties in $UIM_CNTK/charts/uim/config/system-config to include new properties. These properties are available after you start the application and can be read using SystemConfig API.

Deploying Cartridges

Existing UIM cartridges that run on a traditional UIM deployment can still be used with UIM cloud native, but you prepare and deploy those cartridges differently when the cartridges have configuration files and Java code.

The cartridges can be categorized as follows:

Simple cartridges that have entity specifications and Groovy or Drools code.
Custom Extension cartridges that have Java code, configuration files, images, custom applications, Java libraries, Aspects, and localization.

Simple cartridges can be deployed on UIM Cloud Native running instance using Cartridge Management Tool or Design Studio. See UIM Cartridge Guide for more information.

To deploy Custom Extension cartridges in UIM Cloud Native environment:

Package the custom extension content of the cartridge into UIM docker image while building the image. The customized image should be generated with these cartridges. See "Customizing Images" for more information.
Deploy the cartridge on a running instance of UIM Cloud Native with the customized docker image. This can be done using CMT or Design Studio.

Note:

You can follow the custom extension cartridge deployment by default in case you cannot identify the cartridge type.

Deploying Cartridges Using Design Studio

You can deploy cartridges directly from Design Studio using the Eclipse user interface or headless Design Studio. However, use Design Studio for deploying cartridges in scenarios where there is a lot of churn in the build, deploy and test cycle, but not for production environments.

In order to incorporate Design Studio into the larger UIM cloud native ecosystem, you need to have previously taken care of the mapping of the hostname to the Kubernetes cluster or the load balancer as described in "Planning and Validating Your Cloud Environment".

After confirming that this has been done, do the following in Design Studio:

Ensure that the connection URL of the Design Studio environment project matches your UIM cloud native environment. This is likely: http://instance.project.uim.org:30305/cartridge/wsapi. The suffix uim.org is configurable.
In the Design Studio workspace, depending on your network setup, you may need to set the Proxy bypass field in the Network Connection Preferences to: instance.project.uim.org

Deploying Cartridges Using Cartridge Management Tool

You can deploy cartridges using Cartridge Management Tool (CMT). Oracle recommends you to deploy cartridges using CMT in Continuous Deployment (CD).

Provide the following details into CMT:

Connection URL that matches your UIM cloud native environment as follows:
```
http://instance.project.uim.org:30305/cartridge/wsapi
```
The suffix uim.org is configurable.
UIM cluster name
Cartridge file location of Super Jar or Simple Jar

The sample build.properties file is as follows:

url=http://quick.sr.uim.org:30305/cartridge/wsapi
username=<cartridge management web service user name>
password=<password>
fileLocation=<cartridge file location>
deploy.wl.target.name=uimcluster

To deploy the cartridge, run the following command:

ant -lib ../lib -f build.xml deploy-cartridge

Deploying Cartridges using SSL

You can deploy cartridges using SSL in either of the following ways:

Using CMT
Using Design Studio

Deploying Cartridges using SSL in CMT

To deploy cartridges using SSL in CMT:

Upload the external server UIM certificate in JVM. The keytool is found in the bin directory of your jdk installation.

In Unix:

./keytool -importcert -v -trustcacerts -alias <alias> -file /path_to_copied_uim_certificate/uim.crt -keystore /path_to_jdk/jre/lib/security/cacerts -storepass <password>

In Windows (using the command prompt):

keytool -import-alias <alias> -keystore "/path_to_jdk/jre/lib/security/cacerts" -file "/path_to_copied_uim_certificate/uim.crt"

Default password for Java keystore is changeit

In CMT build.properties under tag sslKeyStore, provide uim.crt file as follows:

url=https://instance.project.uim.org:30443/cartridge/wsapi
username=<cartridge management web service user name>
password=<password>
sslKeyStore="/path_to_copied_uim_certificate/uim.crt"

Deploying Cartridges using SSL in Design Studio

To deploy cartridges using SSL in Design Studio:

Upload the external server UIM certificate in /path_to_jdk/jre/lib/security/cacerts if not uploaded earlier:

keytool -import -alias <alias> -keystore "/path_to_jdk/jre/lib/security/cacerts" -file "/path_to_copied_uim_certificate/uim.crt"

Provide the following vmargs in eclipse.ini file as follows:

-vmargs
-Djavax.net.ssl.trustStore=\path_to_jdk\jre\lib\security\cacerts
-Djavax.net.ssl.trustStorePassword=<password> Default password for the Java store is "changeit"

Run Eclipse as Run As Administrator.
Generate jks file from uim.crt and provide it in Eclipse under SSL tab under Studio Environment configuration as follows:
```
keytool -importcert -v -alias <alias> -file /path-to/<certificate>.crt -keystore /path-to/<truststore>.jks -storepass <password>
```
Provide the HTTPS address for deploying the cartridge: https://instance.project.uim.org:30443/cartridge/wsapi

Adding New WDT Metadata

The UIM cloud native toolkit provides the base WDT metadata in $UIM_CNTK/charts/uim/templates. As the UIM application requires this WDT metadata for the proper functioning, this must not be edited. Instead, the toolkit provides a mechanism whereby new pieces of WDT metadata can be included in the final description of the domain.

See "Extending the WebLogic Server Deploy Tooling (WDT) Model" for complete details on the general process for providing custom WDT. The steps described must be repeated for a variety of WDT use cases.

To provide the required configuration for JMS queues:

Creating custom JMS Resources as described in "Adding a JMS System Resource".

Handling of sensitive data from within the WDT metadata fragment is supported as described in the "Accessing Kubernetes Secrets from WDT Metadata".

Working with Kubernetes Secrets

Secrets are Kubernetes objects that you must create in the cluster through a separate process that adheres to your corporate policies around managing secure data. Secrets are then made available to UIM cloud native by declaring them in your configuration.

When the UIM cloud native sample scripts are not used for creating secrets, the secrets you create must align to what is expected by UIM. The sample scripts contain guidelines for creating secrets.

The following diagram illustrates the role of Kubernetes Secrets in a UIM cloud environment:

Figure 6-1 Kubernetes Secrets in UIM Cloud Environment

Description of "Figure 6-1 Kubernetes Secrets in UIM Cloud Environment"

There are three classifications of secrets, as shown in the above illustration:

Mandatory (Pre-requisite) Secrets
Optional Secrets
Custom Secrets

About Mandatory Secret

Mandatory secrets must be created prior to running the cartridge management scripts or the instance creation script.

The toolkit provides the sample script: $UIM_CNTK/scripts/manage-instance-credentials.sh to create the secrets for you. Refer to the script code to see the naming and internal structure required for each of these secrets.

See the following topics for more details about Kubernetes Secrets:

About Optional Secrets

Optional secrets are dictated by enabling the out-of-the-box configuration. There is some functionality that is pre-configured in UIM cloud native and can be enabled or disabled in the specification files. When the functionality is enabled, these secrets must be created in the cluster before a UIM instance is created.

If you use OpenLDAP for authentication, UIM cloud native relies on the following secret to have been created:
```
project-instance-openldap-credentials
```
The toolkit provides a sample script to create these secrets for you ($UIM_CNTK/samples/credentials/manage-uim-ldap-credentials.sh by passing in "-o secret").
When SAF is configured, SAF secrets are used. SAF secrets are similar to custom secrets and are declared in a specialized area within the project specification that feeds into the SAF-specific WDT custom template.
```
safDestinationConfig:
  - name: <SAF Configuration Name>
    t3Url: <Remote Destination URL>
    secretName: <Secret Name of Remote Destination Credentials> 
```

About Custom Secrets

UIM cloud native provides a mechanism where WDT metadata can access sensitive data through a custom secret that is created in the cluster and then declared in the configuration. See "Accessing Kubernetes Secrets from WDT Metadata" to familiarize yourself with this process.

This class of secrets are required only if you need secrets for this mechanism.

To use custom secrets with WDT metadata:

Note:

As an example, this procedure uses a WDT snippet for authentication.

Add secret usage in the WDT metadata fragment:

Host: '@@SECRET:authentication-credentials:host@@'
Port: '@@SECRET:authentication-credentials:port@@'
ControlFlag: SUFFICIENT
Principal: '@@SECRET:authentication-credentials:principal@@'
CredentialEncrypted: '@@SECRET:authentication-credentials:credential@@'

Add the secret to the project specification.

project:
 customSecrets:
   secretNames: {} # This empty declaration should be removed if adding items here.
   #secretNames:
   # - mysecret1
   # - mysecret2

Create the secret in the cluster, by using any one of the following methods:
- Using UIM cloud native toolkit scripts
- Using a Template
- Using the Command-line Interface
In the example metadata shown in step 1, the secret must capture host, port, principal, and credential.

See "Mechanism for Creating Custom Secrets" for details about the methods.

Accommodating the Scope of Secrets

The WDT metadata fragments are defined at the project level as the project typically owns the solution definition. Accommodating this is a simple task. However, the scenario becomes complicated when you consider that there may be project level configuration that needs to allow for instance level control over the secret contents.

To walk through this, we will use authentication as an example and introduce a UIM project that includes three instances: development, test, and production. The production environment has a dedicated authentication system, but the development and test instances use a shared authentication server.

To accommodate this scenario, the following changes must be made to each of the basic steps:

Define a naming strategy for the secrets that introduce scoping. For instance, secrets that need instance level control could prepend the instance name. In the example, this results in the following secret names:
- UIM-dev-authentication-credentials
- UIM-test-authentication-credentials
- UIM-prod-authentication-credentials

Include the secret in the WDT fragment. In order for this scenario to work, a generic way is required to declare the "scope" or instance portion of the secret name. To do this, use the built-in Helm values:

.Values.name - references the full instance name (project-instance)
.Values.namespace - references the project name (project)

If the fragment needs to support instance-level control, derive the instance name portion of the secret name.

Host: '@@SECRET:{{ .Values.name }}-authentication-credentials:host@@'
Port: '@@SECRET:{{ .Values.name }}-authentication-credentials:port@@'
ControlFlag: SUFFICIENT
Principal: '@@SECRET:{{ .Values.name }}-authentication-credentials:principal@@'
CredentialEncrypted: '@@SECRET:{{ .Values.name }}-authentication-credentials:credential@@'

Add the secret to the instance specification. The secret name must be provided in the instance specification as opposed to the project specification.

## Dev Instance Spec
 
 #Custom secrets
# Multiple secret names can be providedinstance:
customSecrets:
   secretNames: {} # This empty declaration should be removed if adding items here.
   #secretNames:
   # - mysecret1
   # - mysecret2
 
 ## Test Instance spec
 
 #Custom secrets
# Multiple secret names can be provided
customSecrets:
  secretNames:
   - UIM-test-authentication-credentials
 
 ## Prod Instance Spec
 
#Custom secrets
# Multiple secret names can be provided
customSecrets:
 secretNames:
   - UIM-prod-authentication-credentials

Create the secret in the cluster by following any one of the methods described in "Mechanism for Creating Custom Secrets". In our example, the secret would need to capture host, port, principal and credential. Each instance would need a secret created, but the values provided depend on which authentication system is being used.

# Dev secret creation
 
 kubectl create secret generic UIM-dev-authentication-credentials \
-n UIM \
--from-literal=principal=<value1> \
--from-literal=credential=<value2> \
--from-literal=host=<value3> \
--from-literal=port=<value4>
 
 # Test secret creation
 
kubectl create secret generic UIM-test-authentication-credentials \
-n UIM \
--from-literal=principal=<value1> \
--from-literal=credential=<value2> \
--from-literal=host=<value3> \
--from-literal=port=<value4>
 
  ##Production secret creation
 
 kubectl create secret generic UIM-prod-authentication-credentials \
-n UIM \
--from-literal=principal=<prodvalue1> \
--from-literal=credential=<prodvalue2> \
--from-literal=host=<prodvalue3> \
--from-literal=port=<prodvalue4>

The following diagram illustrates the secret landscape in this example:

Figure 6-2 Landscape of Secrets

Description of "Figure 6-2 Landscape of Secrets"

Mechanism for Creating Custom Secrets

You can create custom secrets in any of the following ways:

Using Scripts
Using a Template
Using the Command-line Interface

Using Scripts to Create Secrets

Functionality such as OpenLDAP and Embedded LDAP Store that can be enabled or disabled in UIM cloud native relies on pre-requisite secrets to be created. In such cases, the toolkit provides sample scripts that can create the secrets for you. While these scripts are useful for configuring instances quickly in development situations, it is important to remember that they are sample scripts, and not pipeline friendly. These scripts are also essential because when the secret is mandated by UIM cloud native, both the secret name and the secret data are available in the sample script that populates it.

As an example, the secrets used by the Credential Store mechanism must follow a specific naming convention:

projectName-instanceName-uimcn-cred-mapName

Using a Template

To create custom secrets using a template:

Save the secret details into a template file.

apiVersion: v2
kind: Secret
metadata:
 labels:
 weblogic.resourceVersion: domain-v2
 weblogic.domainUID: project-instance
 weblogic.domainName: project-instance
 namespace: project
 name: secretName
type: Opaque
stringData:
password_key: value1
user_key: value2

Run the following command to create the secret:
```
kubectl apply -f templateFile
```

Using the Command-line Interface

You can also specify the secret name and the details directly on the command-line interface:

kubectl create secret generic secretName \
-n project \
--from-literal=password_key=value1 \
--from-literal=user_key=value2

Creating Inventory Users

This section describes how to use the sample scripts to create Inventory UI and Cartridge Deployment users and provide required project configuration in the UIM cloud native.

The sample scripts also provide the ability to populate the OpenLDAP server so that UIM can authenticate any inventory UI and cartridge deployment users.

Creating Users in Embedded LDAP

A fixed set of users can be created in Embedded LDAP. Sample scripts to create LDAP user secrets are placed in $UIM_CNTK/samples/credentials/manage-uim-credentials.sh. Create a user information file with the list of users and WebLogic sever groups as follows:

uim:uimdev:secret:uim-users,uim-metrics-users
uim:uimqa:secret:uim-users,,uim-metrics-users
uim:cmwsdev:secret:Administrators,Cartridge_Management_WebService
uim:cmwsqa:secret:Administrators,Cartridge_Management_WebService

To create users in embedded LDAP, run the following command:

./manage-uim-credentials.sh  -p project  -i instance -c  create -f <text file>

Verify the Secret Creation

To verify the secret, run the following command:

kubectl get secrets -n project  
#
NAME                                   TYPE  
project-instance-uimcn-cred-uim          Opaque

Add all the inventory users to the inventory users in embedded LDAP under the inventoryUsers section in project.yaml file. During the creation of the UIM server instance, for all the inventory users listed, an account is created in embedded LDAP with the same username and password and groups as the Kubernetes secret.

List all cartridge users and execute
# $UIM_CNTK/samples/credentials/manage-uim-credentials.sh to create
# the cartridge user secret before creating the UIM CN instance.
#inventoryUsers: {} # This empty declaration should be removed if adding items here.
inventoryUsers:
  - uimdev
  - uimqa
  - cmwsdev
  - cmwsqa

Note:

Cartridge deployment can be performed by users cmwsdev and cmwsqa, where as users uimdev and uimqa can access Inventory UI.

Creating Users in OpenLDAP

UIM cloud native recommends to use external LDAP for maintaining user accounts. UIM_CNTK includes sample scripts for OpenLDAP user creation. See "Setting Up Authentication" to configure OpenLDAP server.

UIM groups need to be created in the OpenLDAP server and assign them to a Human user before the user can access UIM functioning. The secrets giving access to OpenLDAP server for authentication purposes need to be set up and then enable the OpenLDAP integration by setting true to authentication.openldap.enabled in <projectName>.yaml file.

The sample <projectName>.yaml is as follows:

# External authentication
# When enabled, kubernetes secret "<project>-<instance>-openldap-credentials"
# must exist
authentication:
  openldap:
    enabled: true

Creating Group and User

To create Human user and assign the user to a group in OpenLDAP, edit the $UIM_CNTK/samples/credentials/uim_users.txt file.

For example:

uim:uimldapuser1:ldap:uim-users
uim:uimldapuser2:ldap:uim-users

Install OpenLDAP client on the host where you are running the scripts. Run the following command that installs the OpenLDAP clients:

sudo -s yum -y install openldap-clients

Execute the sample script to populate the OpenLDAP server and create the secret as follows:

$UIM_CNTK/samples/credentials/manage-uim-ldap-credentials.sh -p project -i instance \
 -c create \
 -o account,secret \
 -H <Hostname> \
 -A <Admin dn> \
 -G <Domain dn> \
 -U <User dn>

Verify the secret creation as follows:

kubectl get secrets -n project
  
#
NAME                                   TYPE  
project-instance-openldap-credentials          Opaque

Creating OpenLDAP Users

Create the OpenLDAP users as follows:

$UIM_CNTK/samples/credentials/manage-uim-credentials.sh -p project -i instance -c create -f ./uim_users.txt \
 -H <Hostname> \
 -A <Admin dn> \
 -G <Domain dn>

Verify the secret creation as follows:

kubectl get secrets -n project
  
#
NAME                                   TYPE  
project-instance-uimcn-cred-uim          Opaque

The sample for creating OpenLDAP users is as follows:

$UIM_CNTK/samples/credentials/manage-uim-credentials.sh -p project -i instance -c create -f ./uim_users.txt \
 -H uimopenldap.snphxprshared1.gbucdsint02phx.oraclevcn.com \
 -A cn=Manager,dc=uimcn-ldap,dc=com \
 -G ou=Domains,dc=uimcn-ldap,dc=com

Note:

The above sample prompts for OpenLDAP administrator's password and passwords for all the users you are creating. After the users are created successfully you can see a message similar to LDAP User uimldapuser1 created.

Configuring Other LDAP Systems

The manage-uim-credentials.sh script supports the OpenLDAP system. To provide support for a different LDAP provider, you must modify the script. Also, the corresponding LDAP client or the API must be installed on the system where the script is executed.

You must modify the following functions within this script:

create_ldap_account. This function creates the user account in the LDAP system and associates the user to the specified groups.
update_ldap_account. This function updates the user password.
delete_ldap_account. This function deletes the user from the LDAP system and disassociates this user from the specified group.
verify_ldap_account. This function verifies that the specified user exists in the LDAP server.

For details on developing the functions, see the developer's guide of the target LDAP server that you want to use.

Assigning Application Roles to Inventory Users

Once inventory users are created, applications roles are to be assigned to perform operations in Inventory UI. See UIM System Administrator's Guide for available application roles. Sample script is provided to assign roles to the inventory users. EM Console can also be used for role assignments.

To assign role, edit the $UIM_CNTK/samples/credentials/uim-user-roles.txt file as follows:

uimldapuser1:uimuser,ProductAdministrator
uimldapuser2:uimuser

Execute the sample script to assign roles to the users:

$UIM_CNTK/samples/credentials/assign-role.sh -p project  -i instance  -f <pathToTheFile>/uim-user-roles.txt