8 Exploring Alternate Configuration Options
The UIM cloud native toolkit provides samples and documentation for setting up your UIM cloud native environment using standard configuration options. However, you can choose to explore alternate configuration options for setting up your environment, based on your requirements. This chapter describes alternate configurations you can explore, allowing you to decide how best to configure your UIM cloud native environment to suit your needs.
You can choose alternate configuration options for the following:
- Setting Up Authentication
- Working with Shapes
- Choosing Worker Nodes for Running UIM Cloud Native
- Working with Ingress, Ingress Controller, and External Load Balancer
- Using an Alternate Ingress Controller
- Reusing the Database State
- Setting Up Persistent Storage
- Managing Logs
- Managing UIM Cloud Native Metrics
The sections that follow provide instructions for working with these configuration options.
Setting Up Authentication
By default, UIM uses the WebLogic embedded LDAP as the authentication provider. The UIM cartridge deployment users and application administrative users are created in embedded LDAP during instance creation. For human users, you may set up an optional authentication for the users who access UIM through user interfaces. See "Planning and Validating Your Cloud Environment" for information on the components that are required for setting up your cloud environment. The UIM cloud native toolkit provides samples that you use to integrate components such as OpenLDAP, WebLogic Kubernetes Operator (WKO), and Traefik. This section describes the tasks you must do for configuring optional authentication for UIM cloud native human users.
Perform the following tasks using the samples provided with the UIM cloud native toolkit:
- Install and configure OpenLDAP. This is required to be done once for your organization.
- Install OpenLDAP clients. This is required to be performed on each host that installs and runs the toolkit scripts and when a Kubernetes cluster is shared by multiple hosts.
- In the OpenLDAP server, create the root node for each UIM instance
Installing and Configuring OpenLDAP
OpenLDAP enables your organization to handle authentication for all instances of UIM. You install and configure OpenLDAP once for your organization.
To install and configure OpenLDAP:
- Run the following command, which installs OpenLDAP:
$ sudo -s yum -y install "openldap" "migrationtools"
- Specify a password by running the following command:
$ sudo -s slappasswd New password: Re-enter new password:
- Configure OpenLDAP by running the following
commands:
$ sudo -s $ cd /etc/openldap/slapd.d/cn=config $ vi olcDatabase\=\{2\}hdb.ldif
- Update the values for the following parameters:
Note:
Ignore the warning about editing the file manually.olcSuffix: dc=uimcn-ldap,dc=com
olcRootDN: cn=Manager,dc=uimcn-ldap,dc=com
olcRootPW:
sshawhere ssha is the SSHA that is generated
- Update the dc values for the olcAccess parameter as
follows:
olcAccess: {0}to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external, cn=auth" read by dn.base="cn=Manager,dc=uimcn-ldap,dc=com" read by * none
- Test the configuration by running the following command:
sudo -s slaptest -u
Ignore the checksum warnings in the output and ensure that you get a success message at the end.
- Run the following commands, which restart and enable
LDAP:
sudo -s systemctl restart slapd sudo -s systemctl enable slapd sudo -s cp -rf /usr/share/openldap-servers/DB_CONFIG.example /var/lib/ldap/DB_CONFIG ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/cosine.ldif ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/nis.ldif ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/inetorgperson.ldif
- Create a root node named domain, which will be the top parent for all UIM instances.
- Run the following command to create a new file named
base.ldif:
sudo -s vi /root/base.ldif
- Add the following entries to the base.ldif
file:
dn: ou=Domains,dc=uimcn-ldap,dc=com objectClass: top objectClass: organizationalUnit ou: Domains
- Run the following commands to update the values in the base.ldif
file:
ldapadd -x -W -D "cn=Manager,dc=uimcn-ldap,dc=com" -f /root/base.ldif ldapsearch -x cn=Manager -b dc=uimcn-ldap,dc=com
- Open the LDAP port 389 on all Kubernetes nodes in the cluster.
Installing OpenLDAP Clients
In environments where the Kubernetes cluster is shared by multiple hosts, you must install the OpenLDAP clients on each host. You use the scripts in the toolkit to populate the LDAP server with users and groups.
sudo -s yum -y install openldap-clients
Creating the Root Node
You must create the root node for each UIM instance before additional UIM non-automation user and UIM group can be created.
The toolkit provides a sample script ($UIM_CNTK/samples/credentials/managed-uim-ldap-credentials.sh) that you can use to create the root node in the LDAP tree for the UIM instance.
Run the $UIM_CNTK/samples/credentials/managed-uim-ldap-credentials.sh script by passing in -o account.
Working with Shapes
The UIM cloud native toolkit provides the following pre-configured shapes:
- charts/uim/shapes/dev.yaml. This can be used for development, QA and user acceptance testing (UAT) instances.
- charts/uim/shapes/devsmall.yaml. This can be used to reduce CPU requirements for small development instances.
- charts/uim/shapes/prod.yaml. This can be used for production, pre-production, and disaster recovery (DR) instances.
- charts/uim/shapes/prodlarge.yaml. This can be used for production, pre-production and disaster recovery (DR) instances that require more memory for UIM cartridges and order caches.
- charts/uim/shapes/prodsmall.yaml. This can be used to reduce CPU requirements for production, pre-production and disaster recovery (DR) instances. For example, it can be used to deploy a small production cluster with two managed servers when the input request rate does not justify two managed servers configured with a prod or prodlarge shape. For production instances, Oracle recommends two or more managed servers. This provides increased resiliency to a single point of failure and can allow order processing to continue while failed managed servers are being recovered.
You can create custom shapes using the pre-configured shapes. See "Creating Custom Shapes" for details.
The pre-defined shapes come in standard sizes, which enable you to plan your Kubernetes cluster resource requirement.
Table 8-1 Sizing Requirements of Shapes for a Managed Server
Shape | Kube Request | Kube Limit | JVM Heap (GB) |
---|---|---|---|
prodlarge | 80 GB RAM, 15 CPU | 80 GB RAM, 15 CPU | 64 |
prod | 48 GB RAM, 15 CPU | 48 GB RAM, 15 CPU | 31 |
prodsmall | 48 GB RAM, 7.5 CPU | 48 GB RAM, 7.5 CPU | 31 |
dev | 8 GB RAM, 2 CPU | 8 GB RAM | 5 |
devsmall | 8 GB RAM, 0.5 CPU | 8 GB RAM | 5 |
The following table lists the sizing requirements of the shapes for an admin server:
Table 8-2 Sizing Requirements of Shapes for an Admin Server
Shape | Kube Request | Kube Limit | JVM Heap (GB) |
---|---|---|---|
prodlarge | 8 GB RAM, 2 CPU | 8 GB RAM | 4 |
prod | 8 GB RAM, 2 CPU | 8 GB RAM | 4 |
prodsmall | 8 GB RAM, 2 CPU | 8 GB RAM | 4 |
dev | 3 GB RAM, 1 CPU | 3 GB RAM | 1 |
devsmall | 3 GB RAM, 0.5 CPU | 4 GB RAM | 1 |
These values are encoded in the specifications and are automatically part of the individual pod configuration. The Kubernetes schedulers evaluate the Kube request settings to find space for each pod in the worker nodes of the Kubernetes cluster.
- Number of development instances required to be running in parallel: D
- Number of managed servers expected across all the development instances: Md (Md will be equal to D if all the development instances are 1 MS instances)
- Number of production (and production-like) instances required to be running in parallel: P
- Number of managed servers expected across all production instances: Mp
- Assume use of "dev" and "prod" shapes
- CPU requirement (CPUs) = D * 1 + Md * 2 + P * 2 + Mp * 15
- Memory requirement (GB) = D * 4 + Md * 8 + P * 8 + Mp * 48
Note:
The production managed servers take their memory and CPU in large chunks. Kube scheduler requires the capacity of each pod to be satisfied within a particular worker node and does not schedule the pod if that capacity is fragmented across the worker nodes.The shapes are pre-tuned for generic development and production environments. You can create a UIM instance with either of these shapes, by specifying the preferred one in the instance specification.
# Name of the shape. The UIM cloud native shapes are devsmall, dev, prodsmall, prod, and prodlarge.
# Alternatively, custom shape name can be specified (as the filename without the extension)
Creating Custom Shapes
You create custom shapes by copying the provided shapes and then specifying the desired tuning parameters. Do not edit the values in the shapes provided with the toolkit.
- The number of threads allocated to UIM work managers
- UIM connection pool parameters
To create a custom shape:
- Copy one of the pre-configured shapes and save it to your source repository.
- Rename the shape and update the tuning parameters as required.
- In the instance specification, specify the name of the shape you copied
and renamed:
shape: custom
- Create the domain, ensuring that the location of your custom shape is
included in the comma separated list of directories passed with
-s
.$UIM_CNTK/scripts/create-instance.sh -p project -i instance -s $SPEC_PATH
Note:
While copying a pre-configured shape or editing your custom shape, ensure that you preserve any configuration that has comments indicating that it must not be deleted.Choosing Worker Nodes for Running UIM Cloud Native
By default, UIM cloud native has its pods scheduled on all worker nodes in the Kubernetes cluster in which it is installed. However, in some situations, you may want to choose a subset of nodes where pods are scheduled.
- Limitation on the deployment of UIM on specific worker nodes per each team for reasons such as capacity management, chargeback, budgetary reasons, and so on.
# If UIM CN instances must be targeted to a subset of worker nodes in the
# Kubernetes cluster, tag those nodes with a label name and value, and choose
# that label+value here.
# keys:
# - key : any node label key
# - operator : Valid operators are In, NotIn,Exists, DoesNotExist. Gt, and Lt.
# - values : values is an array of string values.
# If the operator is In or NotIn, the values array must be non-empty.
# If the operator is Exists or DoesNotExist, the values array must be empty (values can be removed from below).
# If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer.
#
# This can be overriden in instance specification if required.
# Node Affinity can be achieved by operator "In" and Node Anti-Affinity by "NotIn"
# oracle.com/licensed-for-coherence is just an indicative example; any
# label and its values can be used for choosing nodes.
uimcnTargetNodes: {} # This empty declaration should be removed if adding items here.
#uimcnTargetNodes:
# nodeLabel:
# keys:
# - key: oracle.com/licensed-for-coherence
# operator: In
# values:
# - true
# - key: failure-domain.beta.kubernetes.io/zone
# operator: NotIn
# values:
# - PHX-AD-2
# - PHX-AD-3
- There is no restriction on node label key. Any valid node label can be used.
- There can be multiple valid values for a key.
- You can override this configuration in the instance specification yaml file, if required.
Examples
In the following example, pods are created on the nodes that have keys as failure-domain.beta.kubernetes.io/zone and the values as PHX-AD-2 or PHX-AD-3:
# Example1
#uimcnTargetNodes: {}
uimcnTargetNodes:
nodeLabel:
keys:
- key: failure-domain.beta.kubernetes.io/zone
operator: In
values:
- PHX-AD-2
- PHX-AD-3
In the following example, pods are created on the nodes that do not have keys as name and have keys as failure-domain.beta.kubernetes.io/zone and the values as neither PHX-AD-2 nor PHX-AD-3.
# Example2
# uimcnTargetNodes: {} # This empty declaration should be removed if adding items here.
uimcnTargetNodes:
nodeLabel:
keys:
- key: name
operator: DoesNotExist
- key: failure-domain.beta.kubernetes.io/zone
operator: NotIn
values:
- PHX-AD-2
- PHX-AD-3
Working with Ingress, Ingress Controller, and External Load Balancer
# valid values are TRAEFIK, GENERIC, OTHER
ingressController: "TRAEFIK"
$UIM_CNTK/scripts/create-ingress.sh -p project -i instance -s $SPEC_PATH
$UIM_CNTK/scripts/delete-ingress.sh -p project -i instance
The Traefik ingress controller works by creating an operator in its own
"traefik" namespace and exposing a NodePort service. However, all ingress controllers do
not behave the same way. In order to accommodate all types of ingress controllers, by
default, the instance.yaml file provides the loadBalancerPort
parameter.
If an external load balancer is used, it needs to be connected to the
NodePort service of the Ingress controller. Hence, externalLoadBalancerIP
also needs to be present in instance.yaml.
- If an external load balancer is not configured, fetch
loadBalancerPort
by running the following command:$kubectl -n $TRAEFIK_NS get service traefik-operator --output=jsonpath="{..spec.ports[?(@.name=='web')].nodePort}"
- If an external load balancer is used, fetch
loadBalancerPort
by running the following command:kubectl -n $TRAEFIK_NS get service traefik-operator --output=jsonpath="{..spec.ports[?(@.name=='web')].port}"
# If external hardware or software load balancer is used, set this value to that frontend host IP.
# If OCI load balancer is used, then set externalLoadBalancerIP from OCI LBaaS
#externalLoadBalancerIP: ""
# For Traefik Ingress Controller:
# If external load balancer is used, then this would be 80, else traefik pod's Nodeport (30305)
loadBalancerPort: 80
Note:
If you choose Traefik or any other ingress controller such as Traefik, you can move theloadBalancerPort
and externalLoadBalancerIP
parameters to project.yaml.
Using an Alternate Ingress Controller
By default, UIM cloud native supports Traefik and provides sample files for integration. However, you can use any Ingress controller that supports host-based routing and session stickiness with cookies. UIM cloud native uses the term "generic" ingress for scenarios where you want to leverage the Ingress capabilities that the Kubernetes platform may provide.
To use a generic ingress controller, you must create the ingress object and configure your UIM instance to use it. The toolkit uses an ingress Helm chart ($UIM_CNTK/samples/charts/ingress-per-domain/templates/traefik-ingress.yaml) and scripts for creating the ingress objects. If you want to use a generic ingress controller, these samples can be used as a reference and customized as necessary.
If your UIM cloud native instance needs to secure incoming communications, then look at the $UIM_CNTK/samples/charts/ingress-per-domain/templates/traefik-ingress.yaml file. This file demonstrates the configuration for a TLS-enabled Traefik ingress that can be used as a sample.
- domainUID: Combination of project-instance. For example, sr-quick.
- clusterName: The name of the cluster in lowercase. Replace any hyphens "-" with underscore "_". The default name of the cluster in values.yaml is uimcluster.
The following table lists the service name and service ports for Ingress rules:
Table 8-3 Service Name and Service Ports for Ingress Rules
Rule | Service Name | Service Port | Purpose |
---|---|---|---|
instance.project.loadBalancerDomainName | domainUID-cluster-clusterName | 8502 | For access to UIM through UI, Web Services, and so on. |
t3.instance.project.loadBalancerDomainName | t3.instance.project.loadBalancerDomainName | 30303 | UIM T3 Channel access for WLST, JMS, and SAF clients. |
admin.instance.project.loadBalancerDomainName | domainUID-admin | 8501 | For access to UIM WebLogic Admin Console UI. |
Ingresses need to be created for each of the above rules per the following guidelines:
- Before running create-instance.sh, ingress must be created.
- After running delete-instance.sh, ingress must be deleted.
You can develop your own code to handle your ingress controller or copy the
sample ingress-per-domain
chart and add additional
template files for your ingress controller with a new value for the type (NGINX for
example).
- The reference sample for creation is: $UIM_CNTK/scripts/create-ingress.sh
- The reference sample for deletion is: $UIM_CNTK/scripts/delete-ingress.sh
ingressController
parameter in the instance specification at
$SPEC_PATH/project-instance.yaml#valid values are TRAEFIK, GENERIC, OTHER
ingressController: "GENERIC"
If any of the supported Ingress controllers or even a generic ingress does not meet your requirements, you can choose "OTHER".
By choosing this option, UIM cloud native does not create or manage any ingress required for accessing the UIM cloud native services. However, you may choose to create your own ingress objects based on the service and port details mentioned in the above table.
Note:
Regardless of the choice of Ingress controller, it is mandatory to
provide the value of loadBalancerPort
in one of the
specification files. This is used for establishing front-end cluster.
Reusing the Database State
When a UIM instance is deleted, the state of the database remains unaffected, which makes it available for re-use. This is common in the following scenarios:
- When an instance is deleted and the same instance is re-created using the same project and the instance names, the database state is unaffected. For example, consider a performance instance that does not need to be up and running all the time, consuming resources. When it is no longer actively being used, its specification files and PDB can be saved and the instance can be deleted. When it is needed again, the instance can be rebuilt using the saved specifications and the saved PDB. Another common scenario is when developers delete and re-create the same instance multiple times while configuration is being developed and tested.
- When a new instance is created to point to the data of another instance with a new project and instance names, the database state is unaffected. A developer, who might want to create a development instance with the data from a test instance in order to investigate a reported issue, is likely to use their own instance specification and the UIM data from PDB of the test instance.
- The UIM DB (schema and data)
- The RCU DB (schema and data)
Recreating an Instance
You can re-create a UIM instance with the same project and instance names, pointing to the same database. In this case, both the UIM DB and the RCU DB are re-used, making the sequence of events for instance re-creation relatively straightforward.
- PDB
- The project and instance specification files
Reusing the UIM Schema
To reuse the UIM DB, the secret for the PDB must still exist:
project-instance-database-credentials
project-instance-database-credentials.
This is the uimdb
credential in the
manage-instance-credentials.sh script.
Reusing the RCU
- project-instance
-rcudb-credentials
. This is thercudb
credential. - project-instance
-opss-wallet-password-secret
. This is theopssWP
credential. - project-instance
-opss-walletfile-secret
. This is theopssWF
credential.
To import the wallet file from previous installation of UIM:
- Execute the WLST exportEncryptionKey command in the previous domain where the RCU is been referenced. This generates ewallet.p12 file.
- Export the wallet file for generating OPSS wallet on the existing
schema and use it to create UIM CN instance as follows:
- Connect to the previous UIM WebLogic domain that refers the
RCU schemas as
follows:
$cd<FWM_HOME>/oracle_common/common/bin>$./wlst.shwls:/offline> exportEncryptionKey(jpsConfigFile, keyFilePath, keyFilePassword) Export of Encryption key(s) is done. Remember the password chosen, it will be required while importing the key(s)
Where:
- keyFilePassword is same as the OPSS wallet file password that is used during the secrets creation.
- jpsConfigFile specifies the location of jps-config.xml file that corresponds to the location where the command is executed.
- keyFilePath specifies the directory where ewallet.p12 file is created. The content of this file is encrypted and secured by the value passed to keyFilePassword.
- keyFilePassword specifies the password to secure ewallet.p12 file. This password must be used while importing the file.
- Download the generated ewallet.p12 file from TEMP_LOCATION folder and copy it into the Kubernetes worker node in $SPEC_PATH.
- Connect to the previous UIM WebLogic domain that refers the
RCU schemas as
follows:
- Convert the generated ewallet file to Base64 encoded format as
follows:
$cd $SPEC_PATH $base64 ewallet.p12 > ewalletbase64.P12
- Create OPSSWF secret using the Base64 ewallet as
follows:
$UIM_CNTK/scripts/manage-instance-credentials.sh -p project -i instance create opssWF
- Enter the Base64 ewallet file location:
$SPEC_PATH/ewalletbase64.p12.
Note:
ForopssWP
andwlsRTE
, use the same password that you used while exporting the wallet file. - Create the instance as you would normally
do:
$UIM_CNTK/scripts/create-instance.sh -p project -i instance -s $SPEC_PATH
Note:
If theopssWP
and opssWF
secrets no longer
exist and cannot be re-created from offline data, then drop the RCU schema and
re-create it using the UIM DB Installer.
Creating a New Instance
If the original instance does not need to be retained, then the original PDB can be re-used directly by a new instance. If however, the instance needs to be retained, then you must create a clone of the PDB of the original instance. This section describes using a newly cloned PDB for the new instance.
If possible, ensure that the images specified in the project specification (project.yaml) match the images in the specification files of the original instance.
Reusing the UIM Schema
uimdb
credential in manage-instance-credentials.sh and points to your cloned
PDB:project-instance-database-credentials
If your new instance must reference a newer UIM DB installer image in its specification files than the original instance, it is recommended to invoke an in-place upgrade of UIM schema before creating the new instance.
# Upgrade the UIM schema to match new instance's specification files
# Do nothing if schema already matches
$UIM_CNTK/scripts/install-uimdb.sh -p project -i instance -s $SPEC_PATH -c 3
Note:
If the current instance details are different than the previous instance, to reuse the UIM schema, drop the table with suffix WL_LLR_.- Create a new RCU
- Reuse RCU
Creating a New RCU
If you only wish to retain the UIM schema data, then you can create a new RCU schema.
The following steps provide a consolidated view of RCU creation described in "Managing Configuration as Code".
- project-instance
-rcudb-credentials
. This is thercudb
credential and describes the new RCU schema you want in the clone. - project-instance
-opss-wallet-password-secret
. This is theopssWP
credential unique to your new instance
# Create a fresh RCU DB schema while preserving UIM schema data
$UIM_CNTK/scripts/install-uimdb.sh -p project -i instance -s $SPEC_PATH -c 2
With
this approach, the RCU schema from the original instance is still available in the
cloned PDB, but is not used by the new instance.Reusing the RCU
Using the manage-instance-credentials.sh script, create the following secret using your new project and instance names:
project-instance-rcudb-credentials
The secret should describe the old RCU schema, but with new PDB details.
-
Reusing RCU Schema Prefix
Over time, if PDBs are cloned multiple times, it may be desirable to avoid the proliferation of defunct RCU schemas by re-using the schema prefix and re-initializing the data. There is no UIM metadata stored in the RCU DB so the data can be safely re-initialized.
project-instance
-opss-wallet-password-secret
. This is theopssWP
credential unique to your new instance.To re-install the RCU, invoke DB Installer:$UIM_CNTK/scripts/install-uimdb.sh -p project -i instance -s $SPEC_PATH -c 2
-
Reusing RCU Schema and Data
In order to reuse the full RCU DB from another instance, the original
opssWF
andopssWP
must be copied to the new environment and renamed following the convention: project-instance-opss-wallet-password-secret and project-instance-opss-walletfile-secret.This directs Fusion MiddleWare OPSS to access the data using the secrets.
$UIM_CNTK/scripts/create-instance.sh -p
project -i instance -s $SPEC_PATH
Setting Up Persistent Storage
UIM cloud native can be configured to use a Kubernetes Persistent Volume to store data that needs to be retained even after a pod is terminated. This data includes application logs, JFR recordings and DB Installer logs, but does not include any sort of UIM state data. When an instance is re-created, the same persistent volume need not be available. When persistent storage is enabled in the instance specification, these data files, which are written inside a pod are re-directed to the persistent volume.
Data from all instances in a project may be persisted, but each instance does not need a unique location for logging. Data is written to a project-instance folder, so multiple instances can share the same end location without destroying data from other instances.
The final location for this data should be one that is directly visible to the users of UIM cloud native. The development instances may simply direct data to a shared file system for analysis and debugging by cartridge developers. Whereas, formal test and production instances may need the data to be scraped by a logging toolchain such as EFK, that can then process the data and make it available in various forms. The recommendation therefore is to create a PV-PVC pair for each class of destination within a project. In this example, one for developers to access and one that feeds into a toolchain.
A PV-PVC pair would be created for each of these "destinations", that multiple instances can then share. A single PVC can be used by multiple UIM domains. The management of the PV and PVC lifecycles is beyond the scope of UIM cloud native.
The UIM cloud native infrastructure administrator is responsible for creating and deleting PVs or for setting up dynamic volume provisioning.
The UIM cloud native project administrator is responsible for creating and deleting PVCs as per the standard documentation in a manner such that they consume the pre-created PVs or trigger the dynamic volume provisioning. The specific technology supporting the PV is also beyond the scope of UIM cloud native. However, samples for PV supported by NFS are provided.
Creating a PV-PVC Pair
The technology supporting the Kubernetes PV-PVC is not dictated by UIM cloud native. Samples have been provided for NFS and can either be used as is, or as a reference for other implementations.
To create a PV-PVC pair supported by NFS:
- Edit the sample PV and PVC yaml files and update entries with enclosing
brackets
Note:
PVCs need to be ReadWriteMany.
vi $UIM_CNTK/samples/nfs/pv.yaml vi $UIM_CNTK/samples/nfs/pvc.yaml
- Create the Kubernetes PV and
PVC.
kubectl create -f $UIM_CNTK/samples/nfs/pv.yaml kubectl create -f $UIM_CNTK/samples/nfs/pvc.yaml
- Set up the storage volume. The storage volume type is
emptydir
by default.storageVolume: type: emptydir # Acceptable values are pvc and emptydir volumeName: storage-volume # pvc: storage-pvc #Specify this only if case type is PVC
Deleting the pod that has storage volume type asemtpydir
deletes the corresponding logs. To retain the logs:- Set the storageVolume.type to pvc.
- Uncomment storageVolume.pvc.
- Specify the name of the pvc created.
# The storage volume must specify the PVC to be used for persistent storage. storageVolume: type: pvc # Acceptable values are pvc and emptydir volumeName: storage-volume pvc: storage-pvc #Specify this only if case type is PVC
[oracle@localhost project-instance]$ dir
server, UIM, uim-dbinstaller
Managing Logs
UIM cloud native generates traditional textual logs. By default, these log files are generated in the managed server pod, but can be re-directed to a Persistent Volume Claim (PVC) supported by the underlying technology that you choose. See "Setting Up Persistent Storage" for details.
emptydir
by
default.storageVolume:
type: emptydir # Acceptable values are pvc and emptydir
volumeName: storage-volume
# pvc: storage-pvc #Specify this only if case type is PVC
emtpydir
deletes the
corresponding logs. To retain the logs:
- Set the storageVolume.type to pvc.
- Uncomment storageVolume.pvc.
- Specify the name of the pvc created.
# The storage volume must specify the PVC to be used for persistent storage.
storageVolume:
type: pvc # Acceptable values are pvc and emptydir
volumeName: storage-volume
pvc: storage-pvc #Specify this only if case type is PVC
- The UIM application logs can be found at: pv-directory/project-instance/UIM/logs
- The UIM WebLogic server logs can be found at: pv-directory/project-instance/server
- The UIM DB Installer logs can be found at: pv_directory/project-instance/uim-dbinstaller/logs
Viewing Logs using Elastic Stack
You can view and analyze the UIM cloud native logs using Elastic Stack.
The logs are generated as follows:
-
Fluentd collects the text logs that are generated during UIM cloud native deployment and sends them to Elasticsearch.
-
Elasticsearch collects all types of logs and converts them into a common format so that Kibana can read and display the data.
-
Kibana reads the data and presents it in a simplified view.
Setting Up Elastic Stack
To set up Elastic Stack:
-
Install Elasticsearch and Kibana using the following commands:
#Install Elasticsearch and Kibana . It might take some time to download the images from Docker hub. kubectl apply -f $WLSKO_HOME/kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml #Check if services are running and append namespace if deployment is not the default:- kubectl get services --all-namespaces kubectl get services #forward port to access kibana on the browser. Note that this command does not return. If you exit from command line, the port would be closed. #other option is to add an ingress controller or a load balancer. kubectl port-forward <pod_name> 30600:5601
where,
<pod_name>
is the pod name where you install Elasticsearch and Kibana. -
In the Kubernetes pod, create an instance with sidecar injection using the following command:
$UIM_CNTK/scripts/create-instance.sh -p <project_name> -i <instance_name> -s <Path_to_specification_files> -m <Path_to_sidecar_template_files>
Note:
You can either create or upgrade a UIM instance to add the sidecar. See "UIM Application Upgrade" for more information on upgrading UIM.
Your latest UIM upgrade contains the sample files for Fluentd sidecar in the $UIM_CNTK/samples/customExtensions folder.
You can create an instance by using pvc or emptydir as a storage volume. The emptydir volume is created when a pod is assigned to a node and exists as long as that pod runs on that node.
-
Update the Elastic search details in fluentd template file in customExtensions folder.
-
Update the values for ELASTICSEARCH_HOST and ELASTICSEARCH_USER, ELASTICSEARCH_PASSWORD.
-
-
(Optional) To add any customizations for selecting or adding any required logs:
-
Update the Fluentd ConfigMap file in the customExtensions folder.
-
Upgrade UIM or create a new instance.
-
- Open Kibana using the URL: http://localhost:30600
For more information on installing the required Kubernetes resources for the Elastic Stack integration, see https://oracle.github.io/weblogic-kubernetes-operator/3.3/userguide/managing-operators/#optional-elastic-stack-elasticsearch-logstash-and-kibana-integration.
Managing UIM Cloud Native Metrics
All managed server pods running UIM cloud native carry annotations added by WebLogic Operator and an additional annotation by UIM cloud native.
uimcn.metricspath: /Inventory/metrics
uimcn.metricsport: 8502
Configuring Prometheus for UIM Cloud Native Metrics
The following job configuration has to be added to Prometheus configuration, replace the username & password for the UIM metric endpoint:
- job_name: 'uimcn'
kubernetes_sd_configs:
- role: pod
relabel_configs:
- source_labels: ['__meta_kubernetes_pod_annotationpresent_uimcn_metricspath']
action: 'keep'
regex: 'true'
- source_labels: [__meta_kubernetes_pod_annotation_uimcn_metricspath]
action: replace
target_label: __metrics_path__
regex: (.+)
- source_labels: ['__meta_kubernetes_pod_annotation_prometheus_io_scrape']
action: 'drop'
regex: 'false'
- source_labels: [__address__, __meta_kubernetes_pod_annotation_uimcn_metricsport]
action: replace
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
target_label: __address__
#- action: labelmap
# regex: __meta_kubernetes_pod_label_(.+)
- source_labels: ['__meta_kubernetes_pod_label_weblogic_serverName']
action: replace
target_lable: server_name
- source_labels: ['__meta_kubernetes_pod_label_weblogic_clusterName']
action: replace
target_label: cluster_name
- source_labels: [__meta_kubernetes_pod_name]
action: replace
target_label: pod_name
- source_labels: [__meta_kubernetes_namespace]
action: replace
target_label: namespace
basic_auth:
username: <METRICS_UESR_NAME>
password: <PASSWORD>
Note:
UIM cloud native has been tested with Prometheus and Grafana installed and configured using the Helm chart prometheus-community/kube-prometheus-stack available at: https://prometheus-community.github.io/helm-charts.Viewing UIM Cloud Native Metrics Without Using Prometheus
http://instance.project.domain_Name:LoadBalancer_Port/Inventory/metrics
By default, domain_Name
is set to
uim.org and can be modified in project.yaml. This only provides
metrics of the managed server that is serving the request. It does not provide
consolidated metrics for the entire cluster. Only Prometheus Query and Grafana
dashboards can provide consolidated metrics.
Viewing UIM Cloud Native Metrics in Grafana
UIM cloud native metrics scraped by Prometheus can be made available for further processing and visualization. The UIM cloud native toolkit comes with sample Grafana dashboards to get you started with visualizations.
Import the dashboard JSON files from $UIM_CNTK/samples/grafana into your Grafana environment.
- UIM by Services: Provides a view of UIM cloud native metrics for one or more instances in the selected managed server.
Exposed UIM Service Metrics
The following UIM metrics are exposed via Prometheus APIs.
Note:
- All metrics are per managed server. Prometheus Query Language can be used to combine or aggregate metrics across all managed servers.
- All metric values are short-lived and indicate the number of requests in a particular state since the managed server was last restarted.
- When a managed server restarts, all the metrics are reset to 0.
Interaction Metrics
The following table lists interaction metrics exposed via Prometheus APIs.
Table 8-4 Interaction Metrics Exposed via Prometheus APIs
Name | Type | Help Text | Notes |
---|---|---|---|
uim_sfws_capture_requests | Summary | Summary that tracks the duration of
sfws capture requests.
|
This metric is observed for the CaptureInteraction request. The action can be CREATE or CHANGE. |
uim_sfws_process_requests | Summary | Summary that tracks the duration of
sfws process requests.
|
This metric is observed for the ProcessInteraction request. The action can be PROCESS. |
uim_sfws_update_requests | Summary | Summary that tracks the duration of
sfws update requests.
|
This metric is observed for the UpdateInteraction request. The action can be APPROVE, ISSUE, CANCEL, COMPLETE or CHANGE. |
uim_sfws_requests | Summary | Summary that tracks the duration of
sfws requests.
|
This metric is observed for the capture, process, and update interaction requests. |
Labels For All Interaction Metrics
The following table lists labels for all interaction metrics.
Table 8-5 Labels for All Metrics
Label Name | Sample Value |
---|---|
action | The values can be CREATE, CHANGE, APPROVE, CANCEL, COMPLETE, and CANCEL. |
Service Metrics
The following metrics are captured for completion of a business interaction.
Table 8-6 Service Metrics Captured for Completion of a Business Interaction
Name | Type | Help Text | Summary |
---|---|---|---|
uim_services_processed | Counter | Counter that tracks the number of services processed. | This metric is observed for suspend, resume, complete, and cancel of a service. |
Labels for all Service Metrics
A task metric has all the labels that a service metric has.
Table 8-7 Labels for All Service Metrics
Label | Sample Value | Notes | Source of Label |
---|---|---|---|
spec | VoipServiceSpec | The service specification name. | UIM Metric Label Name/Value |
status | IN_SERVICE |
The service status. The values can be IN_SERVICE, SUSPEND, DISCONNECT, and CANCELLED. |
UIM Metric Label Name/Value |
Generic Labels for all Metrics
Following are the generic labels for all metrics:
Table 8-8 Generic Labels for all Metrics
Label Name | Sample Value | Source of the Label |
---|---|---|
server_name | ms1 | Prometheus Kubernetes SD |
job | cmcn | Prometheus Kubernetes SD |
namespace | sr | Prometheus Kubernetes SD |
pod_name | ms1 | WebLogic Operator Pod Label |
weblogic_cluseterName | uimcluster | WebLogic Operator Pod Label |
weblogic_clusterRestartVersion | v1 | WebLogic Operator Pod Label |
weblogic_createdByOperator | true | WebLogic Operator Pod Label |
weblogic_domainName | domain | WebLogic Operator Pod Label |
weblogic_domainRestartVersion | v1 | WebLogic Operator Pod Label |
weblogic_domainUID | quicksr | WebLogic Operator Pod Label |
Managing WebLogic Monitoring Exporter (WME) Metrics
UIM cloud native provides a sample Grafana dashboard that you can use to visualize WebLogic metrics available from a Prometheus data source.
You use the WebLogic Monitoring Exporter (WME) tool to expose WebLogic server metrics. WebLogic Monitoring Exporter is part of the WebLogic Kubernetes Toolkit. It is an open source project, based at: https://github.com/oracle/weblogic-monitoring-exporter. You can include WME in your UIM cloud native images. Once a UIM cloud native image with WME is generated, creating a UIM cloud native instance with that image automatically deploys a WME WAR file to the WebLogic server instances. While WME metrics are available through WME Restful Management API endpoints, UIM cloud native relies on Prometheus to scrape and expose these metrics. This version of UIM supports WME 1.3.0. See WME documentation for details on configuration and exposed metrics.
Generating the WME WAR File
mkdir -p ~/wme
cd ~/wme
curl -x $http_proxy -L https://github.com/oracle/weblogic-monitoring-exporter/releases/download/v1.3.0/wls-exporter.war -o wls-exporter.war
curl -x $http_proxy https://raw.githubusercontent.com/oracle/weblogic-monitoring-exporter/v1.3.0/samples/kubernetes/end2end/dashboard/exporter-config.yaml -o config.yml
jar -uvf wls-exporter.war config.yml
Deploying the WME WAR File
After the WME WAR file is generated and updated, you can deploy it as a custom application archive.
For details about deploying entities, see "Deploying Entities to a UIM WebLogic Domain".
appDeployments:
Application:
'wls-exporter':
SourcePath: 'wlsdeploy/applications/wls-exporter.war'
ModuleType: war
StagingMode: nostage
PlanStagingMode: nostage
Target: '@@PROP:ADMIN_NAME@@ , @@PROP:CLUSTER_NAME@@'
Configuring the Prometheus Scrape Job for WME Metrics
Note:
In thebasic_auth
section, specify the WebLogic username and
password.
- job_name: 'basewls'
kubernetes_sd_configs:
- role: pod
relabel_configs:
- source_labels: ['__meta_kubernetes_pod_annotation_prometheus_io_scrape']
action: 'keep'
regex: 'true'
- source_labels: [__meta_kubernetes_pod_label_weblogic_createdByOperator]
action: 'keep'
regex: 'true'
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
action: replace
target_label: __metrics_path__
regex: (.+)
- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
action: replace
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
target_label: __address__
- action: labelmap
regex: __meta_kubernetes_pod_label_(.+)
- source_labels: [__meta_kubernetes_pod_name]
action: replace
target_label: pod_name
- source_labels: [__meta_kubernetes_namespace]
action: replace
target_label: namespace
basic_auth:
username: weblogic_username
password: weblogic_password
Viewing WebLogic Monitoring Exporter Metrics in Grafana
WebLogic Monitoring Exporter metrics scraped by Prometheus can be made available for further processing and visualization. The UIM cloud native toolkit comes with sample Grafana dashboards to get you started with visualizations. The WebLogic server dashboard provides a view of WebLogic Monitoring Exporter metrics for one or more managed servers for a given instance in the selected project namespace.
Import the sample dashboard weblogic_dashboar.json file from https://github.com/oracle/weblogic-monitoring-exporter/blob/master/samples/kubernetes/end2end/dashboard into your Grafana environment by selecting Prometheus as the data source.