6 Creating Your Own UIM Cloud Native Instance
This chapter provides information on creating your own UIM instance. This chapter provides information on how you can create a UIM instance that is tailored to the business requirements of your organization. However, if you want to first understand details on infrastructure setup and structuring of UIM instances for your organization, then see "Planning Infrastructure".
Before proceeding with creating your own UIM instance, you can look at the alternate and optional configuration options described in "Exploring Alternate Configuration Options".
When you created a basic instance, you used the operational scripts and the base configuration provided with the toolkit.
Creating your own instance involves various activities spanning both instance management and instance configuration and includes some of the following tasks:
- Customizing UIM Configuration Properties
- Deploying Cartridges
- Extending the WDT Model
- Working with Kubernetes Secrets
- Creating Inventory Users
- Assigning Application Roles to Inventory Users
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".
- 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 suffixuim.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 when OAM Authentication is NOT Enabled on UIM CN 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/commoncert.pem -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/commoncert.pem"
Default password for Java keystore is
changeit
- In
Unix:
- In CMT build.properties under tag sslKeyStore,
provide commoncert.pem 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/commoncert.pem"
Deploying Cartridges using SSL when OAM Authentication is NOT Enabled on UIM CN in Design Studio
To deploy cartridges using SSL when OAM authentication is not enabled on UIM CN 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/commoncert.pem"
- 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 commoncert.pem 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
Deploying Cartridge using SSL when OAM Authentication is Enabled on UIM CN in CMT
To deploy cartridges using SSL when OAM authentication is enabled on UIM CN in CMT:
- Upload the external server OAM 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_oam_certificate/commoncert.pem -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_oam_certificate/commoncert.pem"
Default password for Java keystore is
changeit
- In
Unix:
- Generate jks file from oamcert.pem and provide path to the
jks file in CMT
build.properties.
keytool -importcert -v -alias <alias> -file /path_to_copied_oam_certificate/commoncert.pem -keystore /path-to/<truststore>.jks -storepass <password>
- In CMT build.properties under tag sslKeyStore,
provide truststore.jks file as
follows:
url=https://<oam-instance>.<oam-project>.ohs.<oam-host-suffix>:30443/cartridge/wsapi username=<cartridge management web service user name> password=<password> sslKeyStore="/path_to_generated_keystore/<truststore>.jks"
Deploying Cartridges using SSL when OAM Authentication is Enabled on UIM CN in Design Studio
To deploy cartridges using SSL when OAM authentication is enabled on UIM CN in Design Studio:
- Upload the external server OAM 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_oam_certificate/commoncert.pem"
- 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 oamcert.pem and provide it in
Eclipse under SSL tab under Studio Environment configuration as
follows:
keytool -importcert -v -alias <alias> -file /path-to/commoncert.pem - keystore /path-to/<truststore>.jks -storepass <password>
- Provide the HTTPS address for deploying the cartridge: https://<oam-instance>.<oam-project>.ohs.<oam-host-suffix>: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.
- Creating custom JMS Resources as described in "Adding a JMS System Resource".
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
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:
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").project-instance-openldap-credentials
- 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
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:
If the fragment needs to support instance-level control, derive the instance name portion of the secret name..Values.name - references the full instance name (project-instance) .Values.namespace - references the project name (project)
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:
Mechanism for Creating Custom Secrets
- 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.
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
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
Run 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 processed.
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.
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
Run 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