Administering a UIM Cloud Native Deployment

8 Administering a UIM Cloud Native Deployment

Perform UIM cloud native deployment administration tasks.

This chapter provides information about UIM cloud native deployment administration tasks.

Overview of UIM Cloud Native Deployment Administration Tasks

UIM cloud native deployment administration tasks include day-to-day tasks of maintaining and managing UIM cloud native instances and its users. The tasks also include managing UIM and other related components in your cloud native environment.

You perform the following tasks as an administrator:

Start, stop, and restart a UIM cloud native instance. See "Starting, Stopping, and Restarting a UIM Cloud Native Instance" for more information.
Upgrade a UIM cloud native instance. See "Upgrading Your UIM Cloud Native Instance" for more information.
Manage UIM cloud native security. See "Securing Your UIM Cloud Native Deployment" for more information.
Monitor and manage a UIM cloud native deployment. See "Monitoring and Managing a UIM Cloud Native Deployment" for more information.
Improve the performance of UIM. See "Improving the Performance of a UIM Cloud Native Deployment" for more details.

Starting, Stopping, and Restarting a UIM Cloud Native Instance

The UIM cloud native toolkit provides scripts for managing your UIM cloud native instances.

To create or start a UIM cloud native instance, run the following script:
```
$UIM_CNTK/scripts/create-instance.sh -i instance -p project -s $SPEC_PATH
```
Note:
Run this command only when an instance is completely down. For details about verifying if the instance started, see "Verifying the UIM Server Started".
To stop all the UIM instances, including the administrator instance, run the following command:
```
$UIM_CNTK/scripts/delete-instance.sh -i instance -p project -s $SPEC_PATH
```
To restart the UIM managed server, run the following command:
```
$UIM_CNTK/scripts/restart-instance.sh -i instance -p project -s $SPEC_PATH -r ms
```
Note:
For details about verifying if the instance started, see "Verifying the UIM Server Started".
To restart the UIM administration server, run the following command:
```
$UIM_CNTK/scripts/restart-instance.sh -i instance -p project -s $SPEC_PATH -r admin
```
To restart all the servers (UIM managed servers and the administration server), run the following command:
```
$UIM_CNTK/scripts/restart-instance.sh -i instance -p project -s $SPEC_PATH -r full
```

Upgrading Your UIM Cloud Native Instance

You upgrade your UIM cloud native instance in the following scenarios:

To scale down. The instances in the environment would be reduced according to the clusterSize value specified in the instance.yaml file.
To scale up. The instances in the environment would be increased according to the clusterSize value specified in the instance.yaml file.
To upgrade the UIM Docker image to a newer image.
To install updates to system configuration properties or log_level changes.
To use WDT extensions.

To upgrade a UIM cloud native instance, run the following command:

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

For details about upgrading your cloud native environment, see "Upgrading the UIM Cloud Native Environment" in UIM Cloud Native Deployment Guide.

Securing Your UIM Cloud Native Deployment

You manage most aspects of UIM security externally rather than in the application itself. For detailed information about how you perform application security tasks in external systems, see the corresponding product documentation for these systems. For information about UIM security, see "UIM Security Overview".

As part of authenticating users for access to a UIM cloud native deployment, you do the following configuration tasks:

Set the session timeout. See "Setting Session Timeout for UIM Cloud Native Instances".
Authenticate web services. See "Authenticating Web Services for a UIM Cloud Native Deployment".
Authorization. See "Authorization in UIM Cloud Native Deployment".

Setting Session Timeout for UIM Cloud Native Instances

To set session timeout for your cloud native instances, you add the following session timeout details in the inventory-clusterPlan.xml file.

// Add below in variable-definition block, change session time out value to desired number of seconds.
<variable>
   <name>SessionDescriptor_TimeoutSecs_16315175580860</name>
   <value>1800</value>
 </variable>
 
// Add below in inventory.ear module-override block
 <module-descriptor external="false">
   <root-element>weblogic-application</root-element>
   <uri>META-INF/weblogic-application.xml</uri>
   <variable-assignment>
     <name>SessionDescriptor_TimeoutSecs_16315175580860</name>
     <xpath>/weblogic-application/session-descriptor/timeout-secs</xpath>
   </variable-assignment>
 </module-descriptor>

For more details about updating the inventory-clusterPlan.xml file, see "Customizing Images" in UIM Cloud Native Deployment Guide.

Authenticating Web Services for a UIM Cloud Native Deployment

To secure custom web services, update your deployment plan with the required policies. You can use the security policy that is available with the Auth.xml UIM instance file, the security policy that is available with the SampleAuth.xml Reference Web Service ZIP file, or create your own security policy file. Custom policies are generally available in the custom webservice war/WEB-INF/policies folder. For more details about authentication, see "Authentication".

The following example shows an update to the inventory-clusterPlan.xml file with default Auth.xml policy:

<module-override>
  <module-name>ReferenceUim.war</module-name>
  <module-type>war</module-type>
  <module-descriptor external="false">
    <root-element>weblogic-web-app</root-element>
    <uri>WEB-INF/weblogic.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>web-app</root-element>
    <uri>WEB-INF/web.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>weblogic-webservices</root-element>
    <uri>WEB-INF/weblogic-webservices.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>webservices</root-element>
   <uri>WEB-INF/webservices.xml</uri>
  </module-descriptor>
  <module-descriptor external="false">
    <root-element>webservice-policy-ref</root-element>
    <uri>WEB-INF/weblogic-webservices-policy.xml</uri>
    <variable-assignment>
      <name>WsPolicy_policy:Auth.xml_Direction_13075993400140</name>
      <xpath>/webservice-policy-ref/port-policy/[port-name="UIMReferenceUimHTTPPort"]/ws-policy/[uri="policy:Auth.xml"]/direction</xpath>
    </variable-assignment>
    <variable-assignment>
      <name>WsPolicy_policy:Auth.xml_Direction_13075993400140</name>
      <xpath>/webservice-policy-ref/port-policy/[port-name="UIMReferenceUimJMSPort"]/ws-policy/[uri="policy:Auth.xml"]/direction</xpath>
    </variable-assignment>
  </module-descriptor>
</module-override>

Authorization in UIM Cloud Native Deployment

Authorization can be achieved using Application roles and Application polices. All the operations performed using Oracle Enterprise Manager Console for managing roles and policies are persisted in the database. A UIM cloud native deployment does not require specific actions to be performed for authorization. See "Authorization" for more details.

Monitoring and Managing a UIM Cloud Native Deployment

You perform monitoring and managing activities after deploying or upgrading your UIM cloud native instance.

The tasks you perform include the following:

For information about the following, see "Overview of the UIM Cloud Native Deployment" in UIM Cloud Native Deployment Guide:

Managing UIM cloud native metrics using Prometheus and Grafana
Managing WebLogic Monitoring Exporter metrics

Setting the Database Row Prefetch Size in a Cloud Native Deployment

You can specify the number of result set rows to prefetch.

To set the database row prefetch size:

Update the value for the rowPrefetchSize parameter in the respective shape.yaml file.
```
jdbc:
  rowPrefetchSize: 50
```

Run the following command:

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

Modifying the Default File Encoding for a Cloud Native Deployment

To modify the default file encoding:

Update the value for the java_options parameter in the project.yaml file.

managedServers:
  project:
    #JAVA_OPTIONS for all managed servers at project level
    java_options: "-Dfile.encoding=UTF-8"

Run the following command:

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

Modifying the Time Zone for a Cloud Native Deployment

To modify the time zone:

Update the value for the java_options parameter in the project.yaml file:

managedServers:
  project:
    #JAVA_OPTIONS for all managed servers at project level
    java_options: "-Duser.timezone=Asia/Shanghai"

Run the following command:

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

For more details about modifying the time zone, see "Modifying the Time Zone".

Configuring Timers in a Cloud Native Deployment

To configure timers:

Add the timer property to the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file.

Run the following command:

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

See "Configuring Your Server's Timers" for more details.

Controlling Application Metrics

You use the custom-config.properties file to control application metrics.

To control application metrics:

Add the property with the desired value in the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file.
Do the following:
- To update sfws and service metrics property values, run the following command:
```
$UIM_CNTK/scripts/upgrade-instance.sh -i instance -p project -s $SPEC_PATH
```
- To update jvm metrics property value, run the following command:
```
$UIM_CNTK/scripts/restart-instance.sh -i instance -p project -s $SPEC_PATH -r full
```

See "Setting System Properties" for details about the properties you can configure.

Configuring Exception-Type-To-Error-Code Mappings in a Cloud Native Deployment

You can map error codes to exception types to help the persistence framework manage validation exceptions. For example, you can map error codes to DuplicateEntityException or to AttributeRequiredException.

To configure exception-type-to-error-code mappings:

Map the error codes to exception types by using the ora_uim_localization_reference cartridge in the model\content\product_home\config\resources\logging\exception.properties file. For more information, see the comments in the exception.properties file.
Build the UIM Docker image. See the section about "Customizing Images" in UIM Cloud Native Deployment Guide for more details.

Run the following command:

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

Localizing UIM Error Messages

You can localize UIM error messages and items by modifying the properties files in the ora_uim_localization_reference cartridge located in the model\content\product_home\config\resources\logging directory. See the table in "Localizing UIM Error Messages" for details about each property's file name, error ID range, and the error messages or items it localizes.

After modifying the properties files, build the UIM Docker image and run the following command:

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

Localizing the UIM Server and the Application Server

By default, the UIM server and the application server software display information in English. You can set the software to display information in another language by localizing text strings in the UIM properties files. For more information, see "Overview" in UIM Developer's Guide.

Configuring SSL Policy for a UIM Cloud Native Deployment

This section describes how to configure SSL in a UIM cloud native deployment. In a UIM cloud native deployment, you enable SSL in Ingress Controller. The following procedures provide information about configuring SSL in Traefik.

Enabling SSL

To enable SSL in Traefik:

Generate the key pairs for each hostname corresponding to an endpoint that UIM cloud native exposes to the outside world.

# Create a directory to save your keys and certificates. This is for sample only. Proper management policies should be used to store private keys.
mkdir $SPEC_PATH/ssl
 
# Generate key and certificates
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout $SPEC_PATH/ssl/uim.key -out $SPEC_PATH/ssl/uim.crt -subj "/ CN=instance.project.uim.org"
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout $SPEC_PATH/ssl/admin.key -out $SPEC_PATH/ssl/admin.crt -subj "/ CN=admin.instance.project.uim.org"
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout $SPEC_PATH/ssl/t3.key -out $SPEC_PATH/ssl/t3.crt -subj "/ CN=t3.instance.project.uim.org"
 
# Create secrets to hold each of the certificates. The secret name must be in the following format. Do not change the secret names.
kubectl create secret -n project tls project-instance-uim-tls-cert --key $SPEC_PATH/ssl/uim.key --cert $SPEC_PATH/ssl/uim.crt
kubectl create secret -n project tls project-instance-admin-tlscert --key $SPEC_PATH/ssl/admin.key --cert $SPEC_PATH/ssl/admin.crt
kubectl create secret -n project tls project-instance-t3-tls-cert --key $SPEC_PATH/ssl/t3.key --cert $SPEC_PATH/ssl/t3.crt

In the instance specification, for ssl, set incoming to true:
```
ssl:
  incoming: true
```

Create Ingress by running the following command:

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

Validate the configuration by describing the ingress controller for your instance. You should see each of the certificates you generated, terminating one of the hostnames:

kubectl get ingressroute -n project
 
NAME                                 AGE
project-instance-traefik             13d
project-instance-traefik-admin-tls   13d
project-instance-traefik-t3-tls      13d
project-instance-traefik-uim-tls     13d

Create your instance by running the following command:

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

Configuring TLS Versions

The sample Ingress charts ($UIM_CNTK/samples/charts/ingress-per-domain/templates/traefik-ingress.yaml) do not restrict the TLS version. Update the charts to configure the minimum and maximum TLS versions using TLSOptions.

For more details, see the Routing Configuration section in the Traefik Labs web site: https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/#kind-tlsoption

Configuring Incoming HTTPS Requests: Configure the external web clients that connect to UIM cloud native to accept the certificates from UIM cloud native. The clients then connect using the HTTPS endpoint and port 30443.

Configuring Incoming JMS Requests: For external servers that are connected to UIM cloud native through SAF, copy the certificate for the t3 endpoint to the host where the external domain is running.

If your external WebLogic configuration uses Custom Identity and Java Standard Trust, to upload the certificate to the Java Standard Trust, run the following command:

/keytool -importcert -v -trustcacerts -alias alias -file
                    /path_to_copied_t3_certificate/t3.crt -keystore
                /path_to_jdk/jre/lib/security/cacerts -storepass default_password

If, however, you are using a CustomTrust, then upload the certificate into the custom trust keystore. The keytool is found in the bin directory of your jdk installation. The alias should uniquely describe the environment where this certificate is from.

Configuring Custom Trust Store

You should load the UIM cloud native domain with the required certificates into the trust store to communicate to an SSL configured external system. You should also configure custom trust store.

To configure custom trust store for the UIM cloud native domain:

Load the certificate from your remote server (external system) into a trust store and make it available to the UIM cloud native instance. Use the Java keytool to create a jks file (truststore) that holds the certificate from your SSL server:
```
keytool -importcert -v -alias alias -file /path-to/certificate.cer -keystore /path-to/truststore.jks -storepass password
```
Note:
Repeat this step to add as many trusted certificates as required.

Create a Kubernetes secret to hold the truststore file and the passphrase by running the following command. The secret name should match the truststore name.

# manually
kubectl create secret generic trust_secret_name -n project --from-file=trust_secret_name.jks=path_to_truststore.jks --from-literal=passphrase=password

# verify
kubectl get secret -n project trust_secret_name -o yaml

Set the trust name in the instance specification YAML file:

    # SSL trust and identity
    ssl:
      trust:
        name: trust_secret_name    # The name of the secret holding the remote server truststore contents and passphrase
      identity:
        useDemoIdentity: true

Create the UIM cloud native instance by running the following command:
```
$UIM_CNTK/scripts/create-instance.sh -i instance -p project -s $SPEC_PATH
```

Resetting the WebLogic Server's Database Connections

You may need to reset the WebLogic server's database connections in the following situations:

The database goes down while UIM is active
UIM is started when the database is down

You reset the database connections by running the manage-instance-credentials.sh script with the update option.

#Run the following script to update the database schema details in Kubernetes secretes
$UIM_CNTK/scripts/manage-instance-credentials.sh -i instance -p project update uimdb,rcudb

When you reset the database connections, the following are updated:

InventoryDataSource
InventoryTxDataSource
CMDSInventoryPersistentDS
InventoryMapDataSource
InvJMSPersistentDS
mds-commsRepository
opss-audit-DBDS
opss-auditviewDS
opss-data-source
LocalSvcTblDataSource
UIMAdapterDS
JDBC data sources

To pick the latest secrets, run the following command:

#Run the following script to upgrade the UIM instance to pick the latest secrets
$UIM_CNTK/scripts/upgrade-instance.sh -i instance -p project -s $SPEC_PATH

Setting the Default Telephone Number Edit Mask in a UIM Cloud Native Deployment

To modify the default telephone number edit mask:

Update the number.properties file in the ora_uim_localization_reference cartridge in the model/content/product_home/config/resources/logging directory. See "Setting the Default Telephone Number Edit Mask" for more details about the default telephone number edit mask.
Build custom UIM Docker image and run the following command:
```
$UIM_CNTK/scripts/upgrade-instance.sh -i instance -p project -s $SPEC_PATH
```
See "Overview of the UIM Cloud Native Deployment" in UIM Cloud Native Deployment Guide for information about building custom images.

Setting the Default Place Type in a Cloud Native Deployment

To set the default place type in a cloud native deployment:

Add or update the property in the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file. See "Setting the Default Place Type" for details about the default place type property.

Run the following command:

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

Configuring Topology Updates in a Cloud Native Deployment

To configure topology updates in a cloud native deployment:

Add the property in the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file. See "Configuring Topology Updates" for more details about topology updates.

Run the following command:

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

Configuring a Geocode Service in a Cloud Native Deployment

To configure a Geocode service in a cloud native deployment:

Add the property in the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file. See "Configuring a Geocode Service" for more details about Geocoding service.

Run the following command:

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

Purging UIM Entities in a Cloud Native Deployment

For UIM cloud native deployments, the purge tool is part of the DB image. The purge tool supports various operations. See "Purging UIM Entities" for more details about purging.

Note:

To view the purge reports and logs, ensure that Persistent Volume Mounts is enabled.

To install or update the purge utility, run the following command:

$UIM_CNTK/scripts/install-uimdb.sh -i instance -p project -s $SPEC_PATH -c 9

To purge UIM schema in a UIM cloud native environment:

In the instance.yaml file, set the value for purge to true. The following example shows the purge command for purging logical devices:
```
purge:
  enabled: true
  purgeCommand: ./ldPurge.sh report -spec LDSpec -ed 01/01/2021
```
See "Operations" for information about purge operations.
Run the following command:

Note:
The purge operation deletes the database records permanently. You must back up the database before performing any purge operation.
```
$UIM_CNTK/scripts/install-uimdb.sh -i instance -p project -s $SPEC_PATH -c 4
```

Note:

The purge execute command needs to be run with the -force option for purge to be run successfully.

You can also run the install-uimdb.sh script without changing the instance.yaml file. You can use this option for scheduling using the cron job:

$UIM_CNTK/scripts/install-uimdb.sh -i instance -p project -s $SPEC_PATH -c 4 -u "./ldPurge.sh report -spec LDSpec -ed mm/dd/yyyy"

Preventing a ZIP Bomb When Uploading Ruleset Files in a Cloud Native Deployment

In some scenarios, you may be required to upload ruleset files in a ZIP file.

To prevent a ZIP bomb when uploading ruleset files in a cloud native deployment:

Add the property in the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file. See "Preventing a ZIP Bomb When Uploading Ruleset Files" for the list of properties.

Run the following command:

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

Customizing UIM Functionality

You can customize UIM functionality by extending the following:

CLASSPATH
EXT_PRE_CLASSPATH

To extend CLASSPATH:

Update the value for classpath in the project.yaml file.

managedServers:
  project:
    #CLASSPATH for all managed servers at project level, separate the jars with colon(:)
    classpath: "/UIM/lib/MetasolvPersistent.jar"

Run the following command:

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

To extend EXT_PRE_CLASSPTH:

Update the value for extPreClasspath in the project.yaml file.

managedServers:
  project:
    #EXT_PRE_CLASSPATH for all managed servers at project level, separate the jars with colon(:)
    extPreClasspath: "/UIM/lib/MetasolvPersistent.jar"

Run the following command:

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

Improving the Performance of a UIM Cloud Native Deployment

This section describes ways to improve the performance of a UIM cloud native deployment.

You perform the following tasks to improve UIM performance:

Improving Performance of Searches That Include Characteristics in a Cloud Native Deployment

To improve the performance of searches that include characteristics:

Add the properties to the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file.

Run the following command:

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

See "Improving Performance of Searches That Include Characteristics" for more details.

Changing the Logging Level in a Cloud Native Deployment

UIM uses log4j for logging the services. For more details about log4j, see: https://logging.apache.org/log4j/2.x/manual/.

The logging level is defined in the $UIM_CNTK/charts/uim/config/logging/loggingconfig.xml file.

See the Appender Configuration, Logger Configuration, and Connecting debugger to UIM sub-sections in "Changing the Logging Level" for more details.

Enabling SQL and Other EclipseLink Logging in a Cloud Native Deployment

To enable SQL and Other EclipseLink logging:

Log in to Oracle Enterprise Manager Console.
Navigate to the oracle.communication.inventory application deployment and choose the managed server for which you want to enable logging.
Edit Current Log Level to choose FINEST.

Updating the System Configuration Files in a Cloud Native Deployment

You use files to control many aspects of UIM performance and configuration. These system configuration files are packaged in the UIM docker image and are available in the UIM/config folder in the runtime container. Each file includes properties for which you can set values. See "Updating the System Configuration Files" for the list of files and available properties in each of the files.

To override the value for any property in the configuration files:

Add the property with the new value in the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file.
Do any one of the following:
- If the added property is dynamic in nature, then run the following command:
```
$UIM_CNTK/scripts/upgrade-instance.sh -i instance -p project -s $SPEC_PATH
```
- If the added property is static in nature and if restarting the server is required, then run the following command:
```
$UIM_CNTK/scripts/restart-instance.sh -i instance -p project -s $SPEC_PATH -r full
```

Changing the Query Behavior and Row Limit Parameters in a Cloud Native Deployment

To change the query behavior and row limit parameters:

Update the $UIM_CNTK/charts/uim/config/system-config/custom-config.properties file.

Run the following command:

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

See "Changing the Query Behavior and Row Limit Parameters" for more details about the parameters you can change.