You must assemble the specification files to use the Common cloud native toolkit. To assemble the specification files:

1. Extract the archive.
2. Set up the environment.
3. Prepare the configuration.

Run the following command to assemble specification:

#Extract common-cntk
cd workspace
tar -xvf common-cntk.tar.gz

#Create spec directory
mkdir spec_dir

#Export variables 
export COMMON_CNTK=(path_to_workspace)/common-cntk
export SPEC_PATH=(path_to_workspace)/spec_dir
export STRIMZI_NS=strimzi   #this is strimzi namespace for message bus, if not applicable to you can keep default value `strimzi`

#Run assemble specification 
$COMMON_CNTK/scripts/assemble-specifications.sh -p project -i instance -s $SPEC_PATH

After assembling the specifications successfully without any errors, verify if the configuration files are correctly assembled by checking the contents of the $SPEC_PATH directory.

UIM cloud native package does not provide scripts to install or remove the WebLogic Kubernetes operator. See WKO Documentation for Installing and uninstalling Weblogic Operator.

See "UIM Software Compatibility" in UIM Compatibility Matrix for WKO recommended version.

For example, to download and install the WKO version:

1. See https://github.com/oracle/weblogic-kubernetes-operator/releases/.
2. Choose a namespace for the operator and set the WLSKO_NS environment variable to the Kubernetes namespace in which WKO will be deployed.

   Note:

   Oracle recommends you use --version=<version> while installing. See "UIM Software Compatibility" UIM Compatibility Matrix for the corresponding WKO version.

   Oracle recommends you set the label to the same as namespace using --set "domainNamespaceLabelSelector=<namespace>=enabled" instead of the default label "weblogic-operator=enabled" as having multiple operators installed with the same label is not recommended.

3. After successful installation of WKO, validate that the operator is installed by running the following command:

   kubectl get pods -n $WLSKO_NS

If you are using a version older than 3.1.0, the operator is supported to specify the namespaces that can be managed only through a list. Currently, the operator supports a list of namespaces, a label selector, or a regular expression matching namespace names.

You can use any Ingress Controller that conforms to the standard Kubernetes ingress API and that supports annotations required for UIM. See "About Load Balancing and Ingress Controller" and "Working with Ingress, Ingress Controller, and External Load Balancer" for more information.

WebLogic Kubernetes Operator describes the installation and the usage of the Nginx Ingress controller. See https://github.com/oracle/weblogic-kubernetes-operator/blob/release/4.1/kubernetes/samples/charts/nginx/README.md for more information. To know the supported WebLogic version, see UIM Cloud Native Deployment Software Compatibility.

To set the environment variables:

1. Ensure that you have copied the corresponding files to the specification directory as mentioned in "Assembling the Specifications".

   Note:

   You must provide full path of specification directory for SPEC_PATH variable as follows:

   $ export SPEC_PATH=<path to workspec>/spec_dir

2. Set the COMMON_CNTK variable for common-cntk directory path as follows:

   $ export COMMON_CNTK=<path to workspace>/common-cntk

3. Set the WLSKO_NS variable for WebLogic operator namespace as follows:

   $ export WLSKO_NS = wlsko namespace

After you set the environment variables, register the namespace. If you are working with wlsko as the targetNamespace, then RegisterNamespace script offers an additional -l option that enables you to include the label selector used during the operator installation.

If a label selector is not added while installing the operator:

By default the weblogic-enabled=true label is added to your $WLSKO_NS namespace so that the operator can monitor it.

If a label selector is added while installing the operator:

Ensure that you include the same label using the -l option, as follows.

To register the namespace for wlsko, run the following command:

#if you have defined labelselector while installing operator Example: wlsko=enabled
$COMMON_CNTK/scripts/register-namespace.sh -p <project> -t targets -l <label- Selector>
#For example, $COMMON_CNTK/scripts/register-namespace.sh -p sr -t wlsko -l wlsko=enabled

The toolkit provides sample scripts for this purpose. However, they are not pipeline-friendly. The scripts should be used for creating an instance manually and quickly, but not for any automated process for creating instances. The scripts also illustrate both the naming of the secret and the layout of the data within the secret that UIM cloud native requires. You must create secrets prior to running the install-database.sh or create-applications.sh scripts.

Ensure that you have assembled the specification before you the following script.

Run the following script to create the required secrets:

$COMMON_CNTK/scripts/manage-app-credentials.sh -p sr -i quick -s $SPEC_PATH -a uim create wlsadmin,opssWP,wlsRTE,rcudb,uimdb

where:

• uimdb specifies the connectivity details and the credentials for connecting to the UIM PDB (UIM schema). This is consumed by the UIM DB installer and UIM runtime.

  Note:

  The uimdb secrets contain PDB sysdba user and uim main schema user. The names of these must be unique.
• rcudb specifies the connectivity details and the credentials for connecting to the UIM PDB (RCU schema). This is consumed by the UIM database installer and UIM and Fusion MiddleWare runtime.
• wlsadmin is the credential for the intended user that will be created with administrative access to the WebLogic domain.
• opssWP is the password for encrypting and decrypting the ewallet contents.
• wlsRTE is the password used to encrypt the operator artifacts for this instance. The merged domain model and the domain ZIP are available in the operator config map and are encoded using this password.

sr-quick-database-credentials
sr-quick-embedded-ldap-credentials
sr-quick-weblogic-credentials
sr-quick-rcudb-credentials
sr-quick-opss-wallet-password-secret
sr-quick-runtime-encryption-secret

This procedure configures an empty PDB. Depending on the database strategy for your team, you may have already performed this procedure as described in "Planning Your Cloud Native Environment". Before continuing, confirm whether the PDB being used for creating the UIM instance has been cloned from a Master PDB that includes the schema installation. If the PDB already has the schema installed, skip this procedure and proceed to the Creating UIM Users and Groups topic.

After the PDB is created, it is configured with the UIM schema, the RCU schema, and the cluster leasing table.

To generate encrypted WebLogic administrator's password:

1. Run the following command to start the UIM DB installer, which initiates a Kubernetes Pod resource. The pod resource is available until the DB installation completes.

   $COMMON_CNTK/scripts/install-database.sh -p project -i instance -s $SPEC_PATH -a uim -c 8

   Note:

   To see further options available, use -h command.
2. Check the WebLogic console for successful DB installation. If the installation failed, run the following command to view the error message from the log:

   kubectl logs -n sr sr-quick-dbinstaller

3. Clean up the failed pod using the following command:

   helm uninstall sr-quick-dbinstaller -n sr

4. Verify the new secret that is created as follows:

   kubectl get secrets -n sr | grep encrypted
   sr-quick-weblogic-encrypted-credentials Opaque 1 5m32s

Ensure that you have assembled the specification, and you have to edit and provide the values for the files in $SPEC_PATH location.

To configure the base specification, edit $SPEC_PATH/project/instance/applications-base.yaml:

1. Provide the ingressController details as follows for Nginx ingress controller, if you are using any other ingress controller, provide the corresponding details:

   ingressController: "GENERIC"
   ingress:
     #provide appropriate ingressClass for controller, “nginx” is default for Nginx ingressController.
     className: "nginx"  
     annotations:
       nginx.ingress.kubernetes.io/affinity: "cookie"
       nginx.ingress.kubernetes.io/affinity-mode: "persistent"
       nginx.ingress.kubernetes.io/session-cookie-name: "nginxingresscookie"
       nginx.ingress.kubernetes.io/proxy-body-size: "50m"
       nginx.ingress.kubernetes.io/proxy-buffer-size: 64k
   

2. If your environment requires a password to download the container images from your repository, create a Kubernetes secret with the Docker pull credentials. For more information, see Kubernetes documentation. Check the secret name in the project specification.

   # The image pull access credentials for the "docker login" into Docker repository, as a Kubernetes secret.
   # uncomment and set if required.
   #imagePullSecret:
   # imagePullSecrets:
   # -name: <image-pull-secret>
   

3. For your DNS resolution mechanism, change the default load balancer sub domain name as per your requirement:

   hostSuffix: "uim.org"

4. Select the shape to be used. shape is the file that contains the resources for UIM service and must present at location $SPEC_PATH/project/instance/shape directory:

   shape: dev

5. If external load balancer is used, provide the loadbalancerport of load balancer. Else, provide the Nginx Ingress Controller NodePort as loadBalancerPort. 30505 is the default value of non-ssl NodePort of Nginx in the sample files:

   loadbalancerport: 30505

To configure the app specification, edit $SPEC_PATH/project/instance/app-uim.yaml:

1. Provide the image in your repository (name and tag):

   ** edit the image to reflect the UIM image name and location in your docker repository
   uim:
      image: 
        name: "uim-cn-base"
        tag: "latest"
   

2. Provide the list of inventory users. All these users should be present in project-instance-uimcn-cred-uim secret:

   inventoryUsers:
     - uimdev
     - cmwsdev
   

3. Specify the database details to enable MultiDataSource and ServerAffinity:

   db:
   datasourcesPrimary: 
     port: 1521
     rcuPort: 1521
     # Below boolean is to enable server affinity, by default it is false. 
     serverAffinityEnabled: false
     # Below boolean is to enable RAC DB Setup, by default it is false. 
     multiDataSourceEnabled: false
     # If using RAC,enable multiDataSourceEnabled and provide list of SCAN hostname/IP addresses
     # If not using RAC, comment it out "#uimScans:" 
     #uimScans:
     # - scan1-ip 
     # - scan2-ip  
     #
     # If using RAC, provide either a list of VIP hostname/IP addresses 
     # or a list of INSTANCE_NAMES
     # If not using RAC, comment these out "#uimVips:" and "#uimInstances:" 
     #
     #uimVips:
     # - vip1-ip 
     # - vip2-ip 
     # --- OR ---
     #uimInstances:
     # - instance-1 
     # - instance-2
     # By default rcu and uim schema are colocated, if we have different rcu schema and different uim then below RAC details are to be provided.
     # If not provided it will not be considered as RAC. rcuUimSchemaCoLocated: true
     # RCU db information
     # If using RAC, provide list of SCAN hostname/IP addresses 
     # If not using RAC, comment it out "#rcuScans:"
     #rcuScans:
     # - scan1-ip 
     # - scan2-ip 
     #
     # If using RAC, provide either a list of VIP hostname/IP addresses 
     # or a list of INSTANCE_NAMES
     # If not using RAC, comment these out "#rcuVips:" and "#rcuInstances:" 
     #
     #rcuVips:
     # - vip1-ip 
     # - vip2-ip 
     # --- OR ---
     #rcuInstances:
     # - instance-1 
     # - instance-2
   

An ingress establishes connectivity to the UIM instances.

$COMMON_CNTK/scripts/create-ingress.sh -p sr -i quick -s $SPEC_PATH -a uim
Project Namespace : sr
Instance Fullname : sr-quick
LB_HOST           : quick.sr.uim.org
Ingress Controller: GENERIC
External LB IP    : 192.0.0.8
 
NAME: sr-quick-ingress
LAST DEPLOYED: Wed Jul  1 10:20:27 2020
NAMESPACE: sr
STATUS: deployed
REVISION: 1
TEST SUITE: None
 
Ingress created successfully...

This procedure describes how to create a UIM instance in your environment using the scripts that are provided with the toolkit.

The base hostname required to access this instance using HTTP is quick.sr.uim.org. See "Planning Your Cloud Native Environment" for details about hostname resolution.

The create-applications script prints out the following valuable information that you can use while working with your UIM domain:

• The T3 URL: http://t3.quick.sr.uim.org:30505 This is required for external client applications such as JMS and WLST.

• Log in to the WebLogic Remote Console by:

  1. Open WebLogic Remote Console Application application.
  2. Choose startup task as Add Admin Server Connection Provider.
  3. Enter URL as follows:

     http://ServerName:Port

  4. Enter the WebLogic server administration user name and password.
• The URL for access to the UIM UIs, which is provided through the ingress controller that requires the host to be specified as: http://quick.sr.uim.org:30505/Inventory/Login.jsp.

To access UIM Home page, you need to assign roles. You can use EM console for role assignments.

To assign roles:

1. Create uim-user-roles.txt as follows:

   uimdev:uimuser
   cmwsdev:uimuser

2. Run the following command to assign the roles:

   $COMMON_CNTK/samples/credentials/assign-role.sh -p sr -i quick -f uim-user-roles.txt

After creating an instance, you can validate it by checking the domain configuration and the client UIs.

kubectl describe domain sr-quick -n sr

The command displays the domain configuration information.

Now that your UIM shape is up and running, you can explore the ability to dynamically scale the application cluster. Update the shape directory name that you have provided.

To scale the UIM application cluster, edit the configuration:

1. In the shape specification directory mentioned in applications-base.yaml, change the value for clusterSize in uim.yaml file manually. This change would ultimately be performed by an automated CI/CD pipeline.

   vi $SPEC_PATH/sr/quick/shapes/dev/uim.yaml
   
   # Change the cluster size to a value not larger than 18
   
   #cluster size
   clusterSize: 2

   Note:

   You can watch the Kubernetes pods in your namespace shrink or grow in real-time. To watch the pods shrink or grow, in a separate terminal window, run the following command:

   kubectl get pods -n sr --watch

2. Upgrade the deployed Helm release:

   $COMMON_CNTK/scripts/upgrade-applications.sh -p sr -i quick -s $SPEC_PATH -a uim

   This pushes the new configuration to the deployed Helm release so the operator can take the necessary steps.

The WebLogic operator monitors changes to clusterSize and results in the operator spinning up or tearing down managed servers to align with the requested cluster size.

Deleting Your UIM Instance

$COMMON_CNTK/scripts/delete-applications.sh -p sr -i quick -s $SPEC_PATH -a uim

Re-creating Your UIM Instance

When you delete a UIM instance, the database state for that instance still remains unaffected. You can re-create a UIM instance with the same project and the instance names, pointing to the same database.

$COMMON_CNTK/scripts/create-applications.sh -p sr -i quick -s $SPEC_PATH -a uim

This section provides information about troubleshooting some issues that you may come across when running the scripts.

If you experience issues when running the scripts, do the following:

• Check the operator logs to find out the details about the issue:

  kubectl get pods -n $WLSKO_NS
  # get the operator pod name to be used in the next command
  kubectl logs -n $WLSKO_NS operator_pod

• Check the "Status" section of the domain to see if there is useful information:

  kubectl describe domain -n sr sr-quick 

"Timeout" Issue

In the logs, you may sometimes see the word "timeout" when the create-applications script fails. When you run the create-applications script, it may take a long time to pull the image, if you are doing it for the first time. In such a scenario, the script may fail and display the text "timeout" in the log.

# Modify the timeout value to start introspector pod. Mainly
# when using against slow DB or pulling image first time.
podStartupDeadlineSeconds: 800

After adjusting the parameter, clean up the failed instance and re-create the instance.

Cleanup Failed Instance

When a create-applications script fails, you must clean up the instance before making another attempt at instance creation.

To clean up the failed instance:

1. Delete the instance:

   $COMMON_CNTK/scripts/delete-applications.sh -p sr -i quick -s $SPEC_PATH -a uim

2. Delete and recreate the RCU schema:

   $COMMON_CNTK/scripts/install-database.sh -p project -i instance -s $SPEC_PATH -a uim -c 5
   $COMMON_CNTK/scripts/install-database.sh -p project -i instance -s $SPEC_PATH -a uim -c 2

Recreating an Instance

$COMMON_CNTK/scripts/create-applications.sh -p sr -i quick -s $SPEC_PATH -a uim