Creating a Basic OSM Cloud Native Instance

4 Creating a Basic OSM Cloud Native Instance

This chapter describes how to create a basic OSM cloud native instance in your cloud environment using the operational scripts and the base OSM configuration provided in the OSM cloud native toolkit. You can create an OSM instance quickly in order to become familiar with the process, explore the configuration, and structure your own project. This procedure is intended to validate that you are able to create a basic OSM instance in your environment. For information on creating your own project with custom configuration, see "Creating Your Own OSM Cloud Native Instance".

Before you can create an OSM instance, you must do the following:

Download and extract the OSM cloud native toolkit archive file
Install the WKO and Ingress-Nginx container images. These tasks are required to be performed for each cluster that has shared resources.

Installing the OSM Cloud Native Artifacts and the Toolkit

Build container images for the following using the OSM cloud native Image Builder:

OSM core application
OSM database installer

You must create a private image repository for these images, ensuring that all nodes in the cluster have access to the repository. See "About Container Image Management" for more details.

Download the OSM cloud native toolkit archive and do the following:

On Oracle Linux: Where Kubernetes is hosted on Oracle Linux, download and extract the tar archive to each host that has connectivity to the Kubernetes cluster.
On OKE: For an environment where Kubernetes is running in OKE, extract the contents of the tar archive on each OKE client host. The OKE client host is the bastion host/s that is set up to communicate with the OKE cluster.

Set the variable for the installation directory by running the following command, where osm_cntk_path is the installation directory of the OSM cloud native toolkit:

$ export OSM_CNTK=osm_cntk_path

Using Oracle Autonomous Database Serverless

OSM cloud native provides experimental capability to use Oracle Autonomous Database Serverless (the transaction-based variant of ADB-S) on a shared infrastructure.

However, this functionality has the following limitations:

This capability is made available only for exploration and investigation purposes. It must not be used for production or similar environments.
Online order-based purging is not supported.
Order purge (online and partition-based) is not supported.
Performance under high order volume is not quantified.

Both OSM schema and RCU schema can be installed on Autonomous Database.

Note:

If you choose to use Autonomous Database, instead of Standard DB (PDB), then both RCU and OSM schemas will be created on the same Autonomous Database.

For more information about Autonomous Database, see the documentation at: https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/index.html.

Using Wallet-based Connection

OSM uses wallet-based connection associated with Database Resident Connection Pooling (DRCP), which is a connection pooling mechanism in Oracle Database that allows you to manage database connections efficiently.

For information about using wallet-based connection in Oracle Autonomous Database, see ADB-S documentation at: https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/getting-started.html.

While downloading the wallet, provide a password that needs to be provided while creating secrets as well. Ensure that you remember the password used at the time of downloading the wallet.

Note:

Do not change the contents of the wallet.

Unzip the wallet and copy it to your local filesystem, which will be used while creating secrets.

Creating Secrets

You must store sensitive data and credential information in the form of Kubernetes Secrets that the scripts and Helm charts in the toolkit consume. Managing secrets is out of the scope of the toolkit and must be implemented while adhering to your organization's corporate policies. Additionally, OSM cloud native does not establish password policies although Autonomous Database Serverless does.

Note:

As a pre-requisite to using the toolkit for either installing the OSM database or creating an OSM instance, you must create OSM database secrets and RCU DB secrets.

The toolkit provides sample scripts for this purpose. However, they are not pipeline-friendly. Use the scripts for creating an instance manually and quickly, but not for any automated process for creating instances. See Reference of Secrets Created by the Scripts for the full list of secrets that OSM cloud native can process, including naming and content requirements as well as when each secret is required. You must create secrets prior to running the install-osmdb.sh or create-instance.sh scripts. The manage-instance-credentials.sh script is the main tool for manual secrets management. This script uses the configuration settings defined in your spec files to reduce the number of prompts for user input.

At the time of creating secrets, you are prompted to answer a question related to OSM schema followed by questions related to wallet. The following is a sample:

Are you using Autonomous Database Serverless (Experimental OSM feature)? (select number from menu)
1) Yes
2) No

After you select 1, questions related to the ADB-S wallet are prompted.

Updating the Instance Specification

In the instance specification, modify the database parameters as follows:

Set db.type to "ADB".
For defaultTablespace, specify the default tablespace name. For Oracle ADB-S, the default is "temp".

Note:

Refer to ADB-S documentation and ensure the passwords used conform to the specified requirements.

db:
  type: "ADB" # Acceptable values are STANDARD and ADB
  #serviceName: dbserver-servicename
  # This DB protocol is all applicable for all database connections.
  # Default value is TCP, Uncomment and change it to TCPS when required.
  # If TCPS is selected, the dbwallet "<project>-<instance>-db-ssl-wallet" secret must exist
  #protocol: TCP
  # datasourcesPrimary section is applicable only for STANDARD DB. For ADB, values will be used from Autonomous Database Serverless  secrets+configMap.
  datasourcesPrimary:
    port: 1521
    # Provide the DB server hostname/IP address
    #host: dbserver-ip
    #
    # If using RAC, provide list of SCAN hostname/IP addresses
    # If not using RAC, comment out "#scans:"
    #scans:
    #  - 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 "#vips:" and "#instances:"
    #
    #vips:
    #  - vip1-ip
    #  - vip2-ip
    # --- OR ---
    #instances:
    #  - instance-1
    #  - instance-2
  
  # Default log level. Valid value
  #
  ## The levels in descending order are:
  ##   SEVERE (highest value)
  ##   WARNING
  ##   INFO
  ##   CONFIG
  ##   FINE
  ##   FINER
  ##   FINEST  (lowest value)
  ##
  logLevel: "WARNING"
  #
  # The remaining parameters must match the values used when the PDB was
  # created.  Failure to match will result in dbInstaller errors
  #
  # The default tablespace name of OSM schema
  defaultTablespace: "temp"
  # The temporary tablespace name of OSM schema
  tempTablespace: "TEMP"
  # The time zone offset in seconds
  timezoneOffsetSeconds: "-28800"
  # The model data tablespace name of OSM schema
  modelDataTablespace: "temp"
  # The model index tablespace name of OSM schema
  modelIndexTablespace: "temp"
  # The order data tablespace name of OSM schema
  orderDataTablespace: "temp"
  # The order index tablespace name of OSM schema
  orderIndexTablespace: "temp"

Run the following command:

$OSM_CNTK/scripts/manage-instance-credentials.sh -p project -i instance -s specPath create osmdb,rcudb

You will be prompted with questions related to OSM schema followed by questions related to the wallet:

Do you have pre-existing ADB-S wallet secrets conforming to OSM CNTK ? (select number from menu)
1) No
2) Yes
#? 1
 
Provide Autonomous Database Serverless credentials for 'dev-quick' ...
Supplied values must align with rules dictated by component that owns the password policy
ADB-S Admin Username: ADB-S admin_username
ADB-S Admin Password: ADB-s password
ADB-S unzipped wallet location: /file/location/to/unzipped/wallet
ADB-S wallet password: Wallet_password
ADB-S tns_alias: alias_in_wallet

TNS_Alias refers to the aliases mentioned in the tnsnames.ora wallet.

After creating secrets, you will be able to see the following secrets and configMap:

secret/project-instance-db-wallet created
secret/project-instance-db-secret created
configmap/project-instance-db-config created

Using RDS or RDS Custom for Oracle

OSM cloud native provides the capability to use Relational Database Service (RDS) for Oracle. RDS is a managed database service that helps you set up, operate, and scale relational databases in the Amazon Web Services (AWS) cloud.

Both OSM schema and RCU schema can be installed on an RDS Database for Oracle.

Updating the Instance Specification

In the instance specification, modify the database parameters as follows:

Set db.rcuDb.honorOMF to true.
Provide default and temp tablespace names.

Note:

While creating the tablespace with RDS, you cannot specify the filenames for tablespaces as it only supports Oracle Managed Files (OMF).

Run the following SQL as the <pdbadmin> user set up for OSM to create a tablespace named 'OSM' with 100MB space, as an example.

create tablespace OSM datafile size 100m autoextend on;

instance.yaml

db:
  type: "STANDARD" # Acceptable values are STANDARD and ADB
  ...
  ...
  rcuDb:
    honorOMF: true # Enable this if using AWS RDB; for others, enable if DB server is setup to use Oracle Managed Files.

Installing WebLogic Kubernetes Operator (WKO) and Ingress Controller

In a shared environment, multiple developers may create OSM instances in the same Kubernetes cluster, using a shared WebLogic Kubernetes Operator.

For each Kubernetes cluster in your environment, you download and install the following:

WebLogic Kubernetes Operator (WKO) container
Ingress Controller

Note:

These installations must be coordinated on large teams so that they occur in a controlled manner.

Before installing the WKO and the Ingress Controller, do the following tasks:

Remove the instances of the WKO and Ingress Controller that you installed to validate your cloud environment.
Ensure that you have cleaned up the environment. See "Validating Your Cloud Environment" for instructions on cleaning up.
Ensure that there are no WebLogic Server Operator artifacts in the environment.

Installing the WebLogic Kubernetes Operator

For information about installation packages and installation instructions, visit the WebLogic Kubernetes Operator (WKO) documentation at: https://oracle.github.io/weblogic-kubernetes-operator/managing-operators/installation/#install-the-operator.

For information about the recommended WKO version, see the OSM Compatibility Matrix.

For example, if the recommended WKO version is 4.1.2:

For details about WKO 4.1.2, see the WKO documentation at: https://github.com/oracle/weblogic-kubernetes-operator/releases/tag/v4.1.2.
Choose a namespace for the operator and set the WLSKO_NS environment variable to the Kubernetes namespace in which WKO will be deployed.
Use --version=4.1.2 during the installation.
Set the label to the same as namespace using --set "domainNamespaceLabelSelector=namespace=enabled". Do not use the default label "weblogic-enabled" because it is not advised to have multiple operators installed with the same label.

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

kubectl get pods -n $WLSKO_NS

Note:

Prior to version 3.1.0, the operator supported specifying the namespaces that it manages only through a list. From release 4.0.0 onwards, WKO supports a list of namespaces, a label selector, or a regular expression matching the namespace names. OSM cloud native supports the label selector method.

If you are upgrading from OSM Cloud Native release 7.4.1 and an older version of the WebLogic Kubernetes Operator, see "Maintaining the OSM Cloud Native Environment" for special considerations.

Installing the Ingress Controller

You can use any Ingress Controller that conforms to the standard Kubernetes ingress API and that supports annotations needed by OSM. Oracle does not certify individual Ingress controllers to confirm this generic compatibility. Refer to "Working with Ingress, Ingress Controller, and External Load Balancer" for more details on annotations and generic Ingress configurations.

You can find examples in GtitHub at: "https://github.com/kubernetes/ingress-nginx".

Weblogic Kubernetes Operator describes the installation and the usage of the NGINX Ingress controller. Refer to "Install and Configure NGINX" for more information.

Creating a Basic OSM Instance

This section describes how to create a basic OSM instance.

Setting Environment Variables

OSM cloud native relies on access to certain environment variables to run seamlessly. Ensure that you set the path to your private specification repository in your environment.

To set the environment variables, create a directory that serves as your specification repository, by running the following command, where spec_repo_path is the path to your private specification repository:

Note:

The scripts in the toolkit support multiple directories being supplied to the -s parameter in a colon separated list (path/one:path/two:path/three). For simplicity, the toolkit works with a single directory.

$ export SPEC_PATH=spec_repo_path/quickstart

Registering the Namespace

To register your namespace, complete the following steps:

Set the environment variables that you will use throughout the installation and registration steps.
```
export WKO_NS=wkoversion                # Operator namespace
export WLSKO_NS=wlsko               # Logical name for the WebLogic operator target
export PROJECT=sr                   # Your domain (project) namespace
```
where version is the version of the WebLogic Kubernetes Operator that you are using.
Add the Operator Helm Chart Repository. Ensure that you are using the latest operator chart information.
```
helm repo add weblogic-operator https://oracle.github.io/weblogic-kubernetes-operator/charts --force-update
```
Install the WebLogic Kubernetes Operator into its dedicated namespace. This installation will configure the operator to monitor all namespaces that have the label you specify.
```
helm install $WKO_NS \
  weblogic-operator/weblogic-operator \
  --namespace $WKO_NS \
  --version compatible-version \
  --set "domainNamespaceLabelSelector=$WKO_NS=enabled"
```
where compatible-version is the version of the WKO that is compatible with your OSM instance.

Note:
Refer to the Order and Service Management Compatibility Matrix to determine the correct version for your OSM instance. For more information about installing WebLogic Kubernetes Operator, refer to the WebLogic Kubernetes Operator documentation.
Validate the Operator Installation by checking that the operator and webhook pods are deployed and running.
```
kubectl get pods -n $WKO_NS
```
Create and Label the Domain Namespace. If the domain namespace (project) does not already exist, create it and add the necessary label so that the operator can manage it.
```
kubectl create namespace $PROJECT
kubectl label namespace $PROJECT $WKO_NS=enabled
```
. Confirm Namespace Label. Ensure the label $WKO_NS=enabled is present on your domain namespace.
```
kubectl get namespace $PROJECT --show-labels
```

Assembling the Specifications

To assemble the specifications:

Copy the instance specification to your $SPEC_PATH and rename:
```
cp $OSM_CNTK/samples/instance.yaml $SPEC_PATH/sr-quick.yaml
```
Copy the project specification to your $SPEC_PATH and rename:
```
cp $OSM_CNTK/samples/project.yaml $SPEC_PATH/sr.yaml
```
You edit these files as per the instructions described in the sections that follow.

Configuring OpenID Connect for OSM Microservices

This section provides information about configuring OpenID Connect (OIDC) for OSM microservices.

Prerequisites

Create a unified authentication service that supports the standard OIDC protocol such as Keycloak.

Securing REST APIs

OSM microservices such as OSM Gateway are integrated with OIDC. OIDC is an authentication protocol that enhances security and simplifies user identity management in applications. It is an extension of OAuth 2.0, which is primarily focused on authorization.

Note:

IDP Identity Provider (IDP): An Identity Provider (IDP) is a system or service that authenticates and provides identity information about users to other applications, services, or systems. It plays a crucial role in identity and access management (IAM). The primary function of an IDP is to verify a user's identity and provide authentication to various relying parties (applications or services) without the need for the user to authenticate separately with each of them. Examples of IDPs: Keycloak and IDCS (Oracle Identity Cloud Service).

OIDC OpenID Connect (OIDC): OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol. It is designed to enable secure and standardized authentication and user information sharing between clients (OSM cloud native) and IDPs. OIDC provides a framework for identity verification, user authentication, and obtaining user profile information.

OSM Gateway authenticates external requests to OSM REST APIs (for TMF and for Fallout Exception Management) to ensure service security. To do this, it is configured as the relying party for an external OpenID provider, which has to be set up as an authentication provider implementing OpenID Connect. It connects to the authentication system based on the OIDC protocol and provides unified authentication for connecting to internal services. To configure OSM Gateway microservice as the relying party for a third-party OpenID provider, set up an authentication provider that implements OpenID Connect. With this configuration, OSM Gateway REST APIs are accessible from the OpenID provider and authorize users to access protected data.

Creating OSM Secret for OIDC

OSM cloud native uses a secret for the administrator to provide the required OIDC information to secure its REST APIs. This secret can be created using the manage-instance-credentials.sh script from the OSM cloud native toolkit, with the gwOidc or ocaOidc option. Make sure you have the required credentials available before running this script.

 $OSM_CNTK/scripts/manage-instance-credentials.sh -p project -i instance -s spec_path create gwOidc,ocaOidc

where gwOidc and ocaOidc specify the details of the OIDC IdP that will be used to authenticate access to the Gateway and OCA APIs.

Note:

The oidc secret option is now deprecated. You can use gwOidc in place of oidc. If provided, it behaves the same as gwOidc for backward compatibility. The script will ask for OIDC details for both TMF and Fallout API with the gwOidc option. You can use the same details for both the APIs. For the ocaOidc option, the script will additionally ask if want to configure OIDC details for Solution Designer. If you affirm that you do, it will then ask for OIDC details for Solution Designer.

This command creates the secrets project-instance-gateway-credentials and project-instance-oca-credentials.

Here are the parameters that the script requests in order to create the secret:

Table 4-1 OIDC Parameters

OIDC Parameters	Description
`Auth URL`	This is the URL where the client initiates the authentication process. You are redirected to this URL to log in and grant permissions to the client application.
`client_id`	Identifier for the client application.
`client_secret`	Secret key shared between the client and OIDC server.
`Token URL`	This is the URL where the client exchanges the authorization code for an access token and ID token. This step typically occurs after you have successfully authenticated and granted permissions.

The OCA Microservice is disabled by default. The OIDC secret for OCA is needed only when you enable the microservice. To enable, set the OSM cartridge assembler property to true in the project specification file

osm-cartridge-assembler.enabled: true

An OIDC secret is needed to use the OSM Gateway microservice. The exception to this requirement is if you have the runtime type property set to WLS in the project specification file.

omsConfig.project.osm_runtime_type: WLS

Note:

Refer to your OpenID Connect authentication provider's documentation for details on these parameters.

You need to configure the audience and scope values as specified below in IdP to access the OSM Microservice APIs. You will not be able to use the authentication token generated for one API (using api specific scope) to access any other API.

Table 4-2 Audience and Scope Configuration for OSM Microservices

API	Scope	Audience
TMF (GW m-s)	`tmf`	`tmf`
Fallout (GW m-s)	`fallout`	`fallout`
OCA (OCA m-s)	`catalog`	`catalog`

To verify the above OIDC parameters, run the following cURL command:

curl --noproxy '*' -i -H 'Authorization: Basic base64Encoded client_id:client_secret' -H 'Content-Type: application/x-www-form-urlencoded' -XPOST token_url -d 'grant_type=client_credentials&scope=scope'

Fundamentally, OpenId Connect defines two tokens:

IDToken: The ID Token carries information about the authenticated user. This information is often used for user authentication and identity verification.
AccessToken: This is a short-lived token generated by OIDC provider which is sent to OSM Gateway to gain access to resources defined in the token.

Note:

In case of troubleshooting authentication issues using the OIDC token, make sure that the 'aud' listed in the OIDC token has the desired client_id added.

Note:

OIDC details are required for accessing OSM TMF REST endpoints, Fallout Exception REST endpoints and OCA REST endpoints. Human users accessing OSM UIs like Task Web client, Order Management UI, Order Operations and Fallout Order Management UI would still be users from External LDAP or SAML.

Keycloak as an example IDP

Keycloak is a widely used open-source identity and access management (IAM) system that can act as an IDP, supporting OIDC among other authentication and authorization protocols. It provides a complete solution for user authentication and user management. For more information on Keycloak, see Keycloak documentation at: https://www.keycloak.org/.

IDP Certificate Management

If the OSM Gateway or RTUX microservice cannot establish an SSL connection to the IDP due to the certificate being unknown, you can introduce the IDP's certificate into the OSM Gateway and RTUX microservies while building microservice images.

To introduce the IDP's certificate:

Identify the JDK version used in the osmCnInfrastructureImage.jdk section from the manifest file used for building OSM cloud native images. You would have obtained this JDK file as part of creating images.
Add the certificate to this JDK's truststore and rebuild the OSM Gateway image, and the RTUX image. Refer to the example below for more details.

Note:

The example below assumes JDK 21.0.7, but use the JDK as per your manifest file: cd $CN_BUILDER_STAGING/java

cd $CN_BUILDER_STAGING/java
 
#untar the java tar file
tar –xvzf jdk-21.0.7_linux-x64_bin.tar.gz
 
# navigate to the bin folder
cd jdk-21.0.7/bin
 
#import the certificate to java keystore
keytool -import -trustcacerts -keystore jdk-21.0.7/lib/security/cacerts -alias ALIAS_NAME -file /path/to/idpcert.pem
#Run this command to add multiple certificates if any (Ex: OIDC )
#Example: keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts -alias foo -file idpcert.pem
 
#tar the java folder again
tar czf jdk-21.0.7_linux-x64_bin.tar.gz jdk-21.0.7
 
#build the image again using OSM image builder tool
#To create OSM Gateway image, use "-c gateway" as shown:
./workspace/osm-image-builder/bin/build-osm-images.sh -f $DMANIFEST -s $STAGING -c gateway
   
#To create rtux m-s image, use "-c rtuxms" as shown:
./workspace/osm-image-builder/bin/build-osm-images.sh -f $DMANIFEST -s $STAGING -c rtuxms

(Optional) Verify the Certificate in the Keystore:

cd $CN_BUILDER_STAGING/java/jdk-21.0.7/bin
keytool -list -keystore $CN_BUILDER_STAGING/java/jdk-21.0.7/lib/security/cacerts -alias ALIAS_NAME

Creating Secrets

Note:

The passwords and other input data such as RCU schema prefix length that you provide must adhere to the policies specified by the appropriate component.

As a pre-requisite to using the toolkit for either installing the OSM database or creating an OSM instance, you must create secrets for access to the following. For more information on creating secrets, see Reference of Secrets Created by the Scripts.

OSM database
OSM system users
RCU DB
OPSS
Operator artifacts for the instance
WebLogic Server Admin credentials used when creating the domain
OIDC credentials

Run the following script to create the required secrets:

$OSM_CNTK/scripts/manage-instance-credentials.sh -p sr -i quick -s 
$SPEC_PATH \
     create \
  osmdb,rcudb,wlsadmin,osmldap,opssWP,wlsRTE,gwOidc,ocaOidc

where:

osmdb specifies the credentials for connecting to the OSM PDB mentioned in the instance specification and credentials required to create OSM schema. This is consumed by the OSM DB installer and OSM runtime.

Note:
The osmdb secrets contain PDB sysdba user, osm main schema user, osm rule engine schema user, and osm report schema user. The names of these must be unique.
osmldap is the credential for OSM system admin and internal users. The script prompts for passwords for the following users.
- OSM admin user (username is omsadmin)
- Design Studio admin user (username is sceadmin)
- OSM internal user (username is oms-internal)
- OSM automation user (username is oms-automation)
- OSM Gateway user (username is osm-tmf-internal)
rcudb specifies the credentials required to create RCU schema. This is consumed by the OSM database installer and OSM 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.
gwOidc, ocaOidc authenticate users and provide access for the REST APIs exposed by microservices. For more details about configuring an authentication provider using OpenID Connect, see Configuring OpenID Connect for OSM Microservices.

The merged domain model and the domain ZIP are available in the operator config map and are encoded using this password.

Verify that the following secrets are created:

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 
sr-quick-gateway-credentials
sr-quick-oca-credentials

Additionally, the secret opssWF is created by the installation process and does not follow the same guidelines. It is therefore not a pre-requisite for creating a new instance. In scenarios where a database is being re-used for a different OSM instance, then this becomes a pre-requisite secret. For more details, see Reusing the Database State.

Configuring OSM Cloud Native to Connect with a TCPS Enabled Database

This section describes what you need to do to configure your OSM cloud native instance to connect with a TCPS enabled database. Follow this procedure to successfully configure your instance:

Enabling TCPS from the Instance Specification

Uncomment protocol under the db section in the instance specification and provide TCPS instead. Populate the db section with the

service
                            name

and the

db.datasourcesPrimary

section with the database's host, and tcps port. If you are using a RAC database, provide scan IPs and VIPs/Instances as well.

Note:

Providing db.datasourcePrimary.host is mandatory. If you are using a RAC DB, you need to give a SCAN address instead.

db:
  type: "STANDARD" # Acceptable values are STANDARD and ADB
  serviceName: dbserver-servicename
  # This DB protocol is all applicable for all database connections.
  # Default value is TCP, Uncomment and change it to TCPS when required.
  # If TCPS is selected, the dbwallet "<project>-<instance>-db-ssl-wallet" secret must exist
  protocol: TCPS
  # datasourcesPrimary section is applicable only for STANDARD DB. For ADB, values will be used from Autonomous Database Serverless  secrets+configMap.
  datasourcesPrimary:
    port: 2484
    # Provide the DB server hostname/IP address
    host: dbserver-ip

Create Oracle Wallet with Database SSL Certificate

OSM expects a single wallet containing the SSL certificates of the database that needs to be connected using TCPS. You can create a wallet using the orapki tool. You can obtain the orapki tool from a Fusion Middleware installation. The tool relies on Java. Use the OSM Compatibility Matrix to ensure that you are using the right versions of Fusion Middleware and Java.
1. Check the orapki version.
```
$ $FMW_HOME\Oracle_Home\oracle_common\bin>orapki
Oracle PKI Tool : Version 12.2.1.4.0
```
2. Create an Oracle wallet using orapki.
```
$ $FMW_HOME\Oracle_Home\oracle_common\bin>orapki wallet create -wallet <ssl_wallet_dir> -auto_login -pwd <password>
```
3. Add certificates to the wallet one at a time.
```
$ $FMW_HOME\Oracle_Home\oracle_common\bin>orapki wallet add -wallet <ssl_wallet_dir> -pwd <password> -trusted_cert -cert <cert_dir>/<xx.crt>
```
  where,
  - ssl_wallet_dir is the directory where the wallet is to be created.
  - cert_dir is the directory where the certificate from the database is stored.
  - xx.crt is the certificate obtained from the database.
  Note:
  You need to repeat this step for each certificate that you need to include.

Create DBWallet Secret using Oracle Wallet

Create a secret for the DBWallet using the Orace wallet you created in the previous step.

$ $OSM_CNTK/scripts/manage-instance-credentials.sh -p <project> -i <instance> -s <spec_path> create dbwallet
  
Unzipped db wallet location: <ssl_wallet_dir>
  
secret/<project>-<instance>-db-ssl-wallet configured

Create or Update the OSMDB Secret

Create or update the osmdb secret to provide the login credentials for the TCPS enabled database.

$ $OSM_CNTK/scripts/manage-instance-credentials.sh -p <project> -i <instance> -s <spec_path> create osmdb
  
$ $OSM_CNTK/scripts/manage-instance-credentials.sh -p <project> -i <instance> -s <spec_path> update osmdb

Installing the OSM and RCU Schemas

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 OSM 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 OSM Users and Groups topic.

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

Note:

Before installing the OSM and RCU schemas, stop or interrupt the automatic optimizer statistics collection maintenance task. For more details, see the New OSM Database Optimizer Statistics Management knowledge article (Doc ID 1925539.1) on My Oracle Support.

To install the OSM and RCU schemas:

Note:

YAML formatting is case-sensitive. While the next step uses vi editor for editing, if you are not familiar with editing YAML files, use a YAML editor to ensure that the you do not make any syntax errors while editing. Follow the indentation guidelines for YAML, as incorrect spacing can lead to errors.

Edit the project specification file and update the DB installer image to point to the location of your image as shown below:

Note:
Before changing the default values provided in the specification file, confirm that they align with the values used during PDB creation. For example, the default tablespace name should match the value used when PDB is created.
```
dbinstaller:
  image:  DB_installer_image_in_your_repo:<tag>
```
If your environment requires a password to download the container images from your repository, create a Kubernetes secret with the image pull credentials. See the "Kubernetes documentation" for details. Reference 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: ""
```

Set the partition size to the actual tablespace size that was created. The default value for production sizing is 20000000 (20 million) and for development is 2000000 (2 million). These may need to be overridden for this instance. See the OSM System Administrator's Guide for guidelines on partition and tablespace sizing. If required, update defaultPartitionSize in the development shape in $OSM_CNTK/charts/osm/shapes/dev.yaml. The defaultPartitionSize parameter also impacts how defaultSubPartitionCount is calculated. Calculate OSM_SUBPARTITION_COUNT from OSM_PARTITION_SIZE.

Note:

osmDBInstaller.resources is used by the pod while creating, upgrading or dropping the OSM and RCU schemas.

Table 4-3 Calculating Sub-partitions

defaultPartitionSize	Calculated Sub-partitions
< = 2M	16
> 2M and < = 10M	32
> 10M	64

Run the following script to start the OSM DB installer, which instantiates a Kubernetes Pod resource. The pod resource lives until the DB installation operation completes.
```
#(OSM Schema)
$OSM_CNTK/scripts/install-osmdb.sh -p sr -i quick -s $SPEC_PATH -c 1 
 ## once finished
# (RCU Schema)
$OSM_CNTK/scripts/install-osmdb.sh -p sr -i quick -s $SPEC_PATH -c 7 
```
You can invoke the script with -h to see the available options.
Check the console to see if the DB installer is installed successfully.
If the installation failed, run the following command to review the error message in the log:
```
kubectl logs -n sr sr-quick-dbinstaller-osm-dbinstaller
```
Clean up the failed pod by running the following command:
```
helm uninstall sr-quick-dbinstaller -n sr
```
Go back to step 4 and run the script again to install the OSM DB installer.

The following table lists the basic database parameters that are handled by the DB Installer:

Table 4-4 Database Parameters Handled by the DB Installer

Parameter	Value
cursor_sharing	FORCE
parallel_degree_policy	AUTO
deferred_segment_creation	By default, set to True. The DB Installer specification can override this to FALSE for production environments.
open_cursors	2000
optimizer_mode	ALL_ROWS
_optimizer_invalidation_period	600

OSM DB Installer Activities

The OSM DB Installer performs the following activities during OSM schema creation:

Automatic Optimizer Statistics Collection Maintenance Task: The OSM DB Installer disables this task during the creation of OSM schema. This avoids race conditions when copying partition statistics as part of the OSM schema installation. This maintenance task is re-enabled after the partition statistics are copied. This is handled as part of the OSM schema installation.
Statistics gathering schedule: The OSM DB Installer modifies the default statistics gathering schedule so that the weekend schedule is the same as the weekday schedule. By default, weekday maintenance windows start at 10 PM and are 4 hours long. The Saturday and Sunday maintenance windows are 20 hours long and start at 6 AM; this impacts order processing performance during peak weekend hours.
See the following topics in Oracle Database Administrator's Guide for more details:
- Predefined Maintenance Windows
- Configuring Automated Maintenance Tasks

Configuring the Project Specification

This section provides instructions for creating a project that is configured to support the processing of the SimpleRabbits sample cartridge that is provided with the toolkit. This sample cartridge validates that OSM processes orders successfully. The project specification is a Helm override file that contains values that are scoped to a project. The values specified in the specification are shared by all the instances of a project, unless they are overridden in an instance specification. Review the content about Helm chart layering in Overview of the OSM Cloud Native Deployment.

The toolkit provides a sample project specification by the name sr that you can use with minor adjustments.

To configure the project specification:

Edit the project specification to provide the image in your repository (name and tag) by running the following command:

# OSM CN Cluster Image
image: "osm"

# OSM Gateway Image
osm-gateway:
  image: "osm-gateway"

# OSM Runtime UX Server Image
osmRuntimeUXServer:
  image: "osm-runtime-ux-server"

The test cartridge requires JMS Queue configuration, which is provided with the toolkit. Copy the JMS Queue configuration from the location shown below into the instance specification.

vi $OSM_CNTK/samples/simpleRabbits/project_fragment.yaml

 ** Copy the queue content
  vi $SPEC_PATH/sr.yaml
  * find the existing placeholder for the queues and paste the content

The following text is an example of JMS Queue configuration:

# jms distributed queues
uniformDistributedQueues:
 - name: new_jms_queue_1
    jndiName: oracle.communication.ordermanagement.ppt.loopbackA
    jmsTemplate: defaultJmsTemplate
 
## first line is LEFT aligned with no leading spaces. each subsequent indent is 2 spaces from the last

If your environment requires a password to download the container images from your repository, create a Kubernetes secret with the image pull credentials. See the Kubernetes documentation for details. Reference 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: ""
```
For your DNS resolution mechanism, change the default load balancer domain name as needed:
```
loadBalancerDomainName: "osm.org"
```

Tuning the Project Specification

This section provides instructions for tuning the project specification. The values specified in the specification are shared by all the instances of a project, unless they are overridden in an instance specification.

Do the following to tune the project specification:

To configure the maximum number of bytes allowed in messages that are received over all WebLogic protocols, set the following parameter:
```
wlsMaxMsgSize: value_in_bytes
```
For OSM cloud native, the default value is 300000000 bytes, which is much higher than the default value of 10000000 bytes in WebLogic. The low default value in WebLogic can cause errors when this limit is reached.
To configure the tablespace name for OSM model and order tables and indexes, see the following parameters:
```
db:
  modelDataTablespace: string
  modelIndexTablespace: string
  orderDataTablespace: string
  orderIndexTablespace: string
```
For each parameter, the default value is OSM.
To configure the partition size for OSM order tables, see the following parameter:
```
defaultPartitionSize: integer
```
The default is 2,000,000 (2 million). Production shapes define a larger value of 20,000,000 (20 million), which is a better choice when combined with online purging.
To configure the sub-partition count for partitioned OSM order tables, see the following parameter:
```
defaultSubPartitionCount: integer
```
The default value is undefined. Typical values are 16, 32 and 64. Leave this parameter undefined to allow the OSM cloud native database installer to choose a value appropriate for the partition size. For example, for a large 20 million partition, the installer will choose a value of 64 so as to minimize database contention.
To configure whether database segment creation should be deferred, see the following parameter:
```
deferredSegmentCreation: "TRUE" or "FALSE"
```
The default value is TRUE. To minimize database contention, this should be set to FALSE for production systems.
To configure OSM and infrastructure data source connection pool parameters, see the parameters under the jdbc element. For example, the maximum database connection pool capacity for the OSM application data sources and for the infrastructure data sources (which support JMS and tlog JDBC stores) can be set with:
```
jdbc:
  app:
    maxCapacity: integer
  infra:
    maxCapacity: integer
```
For more details on connection pool parameters, see Oracle Fusion Middleware Remote Console Online Help for Oracle WebLogic Server 14.1.2.0. Also refer to the production and development shapes for the full list of supported parameters and default values.
To configure the message buffer cache size for individual JMS servers, see the following parameter:
```
jmsMsgBufferSize: value_in_bytes
```
The default value is approximately one-third of the maximum JVM heap size, or a maximum of 512 megabytes (536,870,912 bytes). For production environments, the recommended value is 1 gigabyte (1,073,741,824 bytes) to reduce the possibility that WebLogic will start paging JMS message bodies to disk once the buffer is full.
To configure whether database optimizer statistics should be loaded when creating OSM order table partitions, see the following parameter:
```
loadPartitionStatistics: false
```
The default value is false. This should be set to true for production systems.
To configure logging options, see the following parameter:
```
logging_options: string
```
Refer to the production and development shapes for more details and the default values. The following is an example:
```
logging_options: " -Dweblogic.log.FileMinSize=5000 -Dweblogic.log.FileCount=10 -Dweblogic.log.RotateLogOnStartup=false "
```

To configure JVM parameters for the admin server or for managed servers, see the following parameter:

user_mem_args: string

Refer to the production and development shapes for sample values. The following is an example from the prodlarge shape:

managedServers:
      shape:
        user_mem_args: "-XX:+UseG1GC -XX:G1HeapRegionSize=16m -XX:+ClassUnloadingWithConcurrentMark -XX:+UseStringDeduplication -XX:SurvivorRatio=3 -XX:CodeCacheMinimumFreeSpace=16m -XX:ReservedCodeCacheSize=512m -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -XX:+PrintTenuringDistribution -XX:+PrintAdaptiveSizePolicy -Xloggc:/u01/oracle/user_projects/domains/domain/gc.log -XX:+DisableExplicitGC -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -Xms64g -Xmx64g -Xmn22g -XX:InitiatingHeapOccupancyPercent=50 -XX:ParallelGCThreads=13 "

For more details, see the OSM Memory Tuning Guidelines (Doc ID: 2028249.1) knowledge article on My Oracle Support.

Configuring the Instance Specification

The instance specification is a Helm override file that contains values that are specific to a single instance. These values feed into the WDT model developed for the OSM WebLogic domain.

To configure the instance specification:

Edit the sr-quick.yaml file to specify the database details:

db:
  type: "STANDARD" # Acceptable values are STANDARD and ADB
  #serviceName: dbserver-servicename
  # This DB protocol is all applicable for all database connections.
  # Default value is TCP, Uncomment and change it to TCPS when required.
  # If TCPS is selected, the dbwallet "<project>-<instance>-db-ssl-wallet" secret must exist
  #protocol: TCP
  # datasourcesPrimary section is applicable only for STANDARD DB. For ADB, values will be used from Autonomous Database Serverless  secrets+configMap.
  datasourcesPrimary:
    port: 1521
    # Provide the DB server hostname/IP address
    #host: dbserver-ip
    #
    # If using RAC, provide the list of SCAN hostname/IP addresses
    # If not using RAC, comment out "#scans:"
    #scans:
    # - 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 out "#vips:" and "#instances:"
    #
    #vips:
    # - vip1-ip
    # - vip2-ip
    # --- OR ---
    #instances:
    # - instance-1
    # - instance-2

If you are using Oracle Cloud Infrastructure Load Balancer as a Service (LBaaS), run the following command to find the IP address of the load balancer, assuming the relevant service is configured in your namespace:
```
kubectl get svc -n <namespace> <service-name> --output=jsonpath="{..status.loadBalancer.ingress[0].ip}"
```
Because an external load balancer is not required to be configured for the basic OSM instance, change the value of loadBalancerPortto the default nginx-ingress nodeport of 30305 if you are not using Oracle Cloud Infrastructure LBaaS:
```
loadBalancerPort: 30305
```
If you use Oracle Cloud Infrastructure LBaaS, or any other external load balancer, set loadBalancerPort to 80, and uncomment and update the value for externalLoadBalancerIP appropriately:
```
loadBalancerPort: load_balancer_port
#externalLoadBalancerIP: IP_address_of_the_external_load_balancer
```

Creating an Ingress

An ingress establishes connectivity to the OSM instances.

To create an Ingress, run the following command:

$OSM_CNTK/scripts/create-ingress.sh -p sr -i quick -s $SPEC_PATH
Project Namespace : sr
Instance Fullname : sr-quick
LB_HOST           : quick.sr.osm.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...

Creating an OSM Instance

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

To create an OSM instance:

Run the following command:
```
$OSM_CNTK/scripts/create-instance.sh -p sr -i quick -s $SPEC_PATH
```
The create-instance.sh script uses the Helm chart located in the charts/osm directory to create and deploy the domain custom resource and the domain config map for your instance. If the scripts fails, see the Troubleshooting Issues section at the end of this topic, before you make additional attempts.

The instance creation process creates the opssWF secret, which is required for access to the RCU DB. It is possible to handle the wallet manually if needed. To do so, pass -w to the create-instance.sh script, which creates the wallet file at a location you choose. You can then use this wallet file to create a secret by using the manage instance credentials script.

Validate the important input details such as Image name and tag, specification files used (Values Applied), hostname, and port for ingress routing:

$OSM_CNTK/scripts/create-instance.sh -p sr -i quick -s $SPEC_PATH

Calling helm lint
==> Linting ./scripts/../charts/osm
[INFO] Chart.yaml: icon is recommended
 
1 chart(s) linted, 0 chart(s) failed
Project Namespace : sr
Instance Fullname : sr-quick
LB_HOST           : quick.sr.osm.org
LB_PORT           : 30305
Image             : osm:7.4.1.200504-0655-b1735.a0f9526f
Shape             : dev
Values Applied    : -f ./scripts/../charts/osm/values.yaml -f ./scripts/../charts/osm/shapes/dev.yaml   -f /home/oracle/SmokeTest/repo/sr.yaml -f /home/oracle/SmokeTest/repo/sr-quick.yaml
Output wallet     : n/a

After the script finishes executing, the log shows the following:

NAME             READY   STATUS              RESTARTS   AGE
sr-quick-admin   1/1     Running             0          2m12s
sr-quick-ms1     0/1     ContainerCreating   0          1s
 
Provide opss wallet File for 'sr-quick' ...
For example : '/path-to-osm-cntk/sr-quick.ewallet'
opss wallet File:
secret/sr-quick-opss-walletfile-secret created
 
Instance 'sr/sr-quick' admin server is now running.
Creation of instance 'sr/sr-quick' has completed successfully.

The create-instance.sh script also provides some useful commands and configuration to inspect the instance and access it for use.

If you query the status of the pods, the READY state of the managed servers may display 0/1 for several minutes while the OSM application is starting.
When the READY state shows 1/1, your OSM instance is up and running. You can then validate the instance by deploying a sample cartridge and submitting orders.

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

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

The T3 URL: http://t3.quick.sr.osm.org This is required for external client applications such as JMS and WLST.
The WebLogic Remote Console is deployed on the Admin Server and can be accessed at:http://admin.<host>:<Port>/rconsole.
For additional information, see Oracle WebLogic Remote Console Online Help.
The URL for access to the OSM UIs, which is provided through the ingress controller that requires the host to be specified as: http://quick.sr.osm.org:30305/OrderManagement/Login.jsp.

Validating the OSM Instance

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

Run the following command to display the domain configuration details of the OSM instance that you have created:

kubectl describe domain.weblogic.oracle sr-quick -n sr

The command displays the domain configuration information.

To verify the client UIs:

Log into the WebLogic Remote console using the URL specified in the output of the create-instance script: http://admin.quick.sr.osm.org:30305/rconsole

You can use the console to verify the configuration that has been applied and to see that the OSM application is in a good state.
Log into the OSM Task Web client user interface with the OSM administrator login credentials created as part of "Creating Secrets" using the URL (http://quick.sr.osm.org:30305/OrderManagement/Login.jsp) specified in the output of the create-instance script.

Note:

After an OSM instance is created, it may take a few minutes for the OSM user interface to become active.

Scaling the OSM Application Cluster

Now that your OSM instance is up and running, you can explore the ability to dynamically scale the application cluster.

To scale the OSM application cluster, edit the configuration:

In the instance specification, change the value for clusterSize manually. This change would ultimately be performed by an automated CI/CD pipeline.
```
vi $SPEC_PATH/sr-quick.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
```
Upgrade the deployed Helm release:
```
$OSM_CNTK/scripts/upgrade-instance.sh -p sr -i quick -s $SPEC_PATH 
```
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.

Deploying the Sample Cartridge

By deploying the sample cartridge that is provided with the toolkit, you can validate order processing in the OSM instance that you created.

Before deploying the cartridge, you must bring down the running domain. You can do this by scaling the cluster size down to 0.

To deploy the sample cartridge:

Scale down the cluster:
1. Reduce the cluster size in the configuration:
```
vi $SPEC_PATH/sr-quick.yaml
 
# Change the cluster size to 0
 
#cluster size
clusterSize: 0
```
2. Push the configuration to the runtime environment:
```
$OSM_CNTK/scripts/upgrade-instance.sh -p sr -i quick -s $SPEC_PATH
```
The operator terminates the managed server.

Deploy the SimpleRabbits sample cartridge by running the following command:

./scripts/manage-cartridges.sh \
 -p sr -i quick -s $SPEC_PATH
 -f $OSM_CNTK/samples/simpleRabbits/SimpleRabbits.par -c parDeploy

Scale up the cluster:
1. Increase the cluster size in the configuration:
```
vi $SPEC_PATH/sr-quick.yaml
 
# Change the cluster size to 1
 
#cluster size
clusterSize: 1
```
2. Push the configuration to the runtime environment:
```
$OSM_CNTK/scripts/upgrade-instance.sh -p sr -i quick -s $SPEC_PATH
```
The operator terminates the managed server.

Submitting Orders

The OSM cloud native toolkit provides a sample order that you can submit to validate order processing in OSM. The sample order is available at: $OSM_CNTK/samples/simpleRabbits/sample.xml.

To submit OSM orders over HTTP, use an external client such as SoapUI. The endpoint is the same as the URL used to verify the OSM Task Web client.

When using SoapUI, a Soap Envelope element needs to wrap CreateOrderBySpecification that is provided in $OSM_CNTK/samples/simpleRabbits/sample.xml

To submit OSM orders over JMS, use an external client such as Hermes JMS. The endpoint must be as follows:

jms://OSM_1::queue_oracle/communications/ordermanagement/WebServiceQueue::queue_oracle/communications/ordermangement/SoapUIResponseQueue

The connection factory's providerURL must be as follows:

http://t3.quick.sr.osm.org:30305

Deleting and Recreating Your OSM Instance

Deleting Your OSM Instance

To delete your OSM instance, run the following command:

$OSM_CNTK/scripts/delete-instance.sh -p sr -i quick

Re-creating Your OSM Instance

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

Note:

Ensure that you use the same specifications that you used for creating the instance and that the following secrets have not been deleted:

osmdb
osmldap
rcudb
opssWF
opssWP
wlsRTE

To re-create an OSM instance, run the following command:

$OSM_CNTK/scripts/create-instance.sh -p sr -i quick -s $SPEC_PATH

Note:

After re-creating an instance, client applications such as SoapUI and HermesJMS may need to be restarted to avoid using expired cache information.

Cleaning Up the Environment

To clean up the environment:

Delete the instance:

$OSM_CNTK/scripts/delete-instance.sh -p sr -i quick

Delete the ingress:

$OSM_CNTK/scripts/delete-ingress.sh -p sr -i quick

Delete the namespace, which in turn deletes the Kubernetes namespace and the secrets:
```
$OSM_CNTK/scripts/unregister-namespace.sh -p sr -d -t targets
```
Note:
wlsko and traefik are the names of the targets for registration of the namespace. The script uses WLSKO_NS and TRAEFIK_NS to find these targets. Do not provide the "traefik" target if you are not using Traefik. If the Traefik version you are using is different from the version you specified at the time of this release, modify the Traefik chart version in the unregister-namespace.sh script.
If you wish to unregister a namespace without deleting the namespace and secrets, do one of the following:
- If you have not added domainNamespaceLabelSelector, run the following command for the operator to stop monitoring your namespace:
```
$OSM_CNTK/scripts/unregister-namespace.sh -p project -t wlsko
# For example, $OSM_CNTK/scripts/unregister-namespace.sh -p sr -t wlsko
```
- If you have specified a value for domainNamespaceLabelSelector (for example, wko412=enabled) during the installation of the operator, run the following command for unregistering the namespace:
```
$OSM_CNTK/scripts/unregister-namespace.sh -p project -t wlsko
# For example, $OSM_CNTK/scripts/unregister-namespace.sh -p sr -t wlsko -l wko412
```
Drop the PDB or delete the instance schemas from it. Deleting the schemas is recommended if you are using the PDB to re-create the instance.

Note:
If PDB is dropped, all schemas hosted on it will be lost, not just the instance schemas.
```
#(Deletes OSM Schema)
$OSM_CNTK/scripts/install-osmdb.sh -p sr -i quick -s $SPEC_PATH -c 8
#(Deletes RCU Schema)
$OSM_CNTK/scripts/install-osmdb.sh -p sr -i quick -s $SPEC_PATH -c 6
```

Troubleshooting Issues with the Scripts

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.weblogic.oracle -n sr
    sr-quick
```

"Timeout" Issue

In the logs, you may sometimes see the word "timeout" when the create-instance script fails. When you run the create-instance 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.

To resolve this issue, try increasing the podStartupDeadlineSeconds parameter. The podStartupDeadlineSeconds parameter is a configurable parameter exposed in the instance specification that can be increased if required. Start with a very high timeout value and then monitor the average time it takes, because it depends on the speed with which the images are downloaded and how busy your cluster is. Once you have a good idea of the average time, you can reduce the timeout value accordingly to something that considers both the average time and some buffer.

# 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-instance script fails, you must clean up the instance before making another attempt at instance creation.

Note:

Do not retry running the create-instance script or the upgrade-instance script immediately to fix any errors, as they would return errors. The upgrade-instance script may work but re-running it does not complete the operation.

To clean up the failed instance:

Delete the instance:

$OSM_CNTK/scripts/delete-instance.sh -p sr -i quick

Delete and recreate the RCU schema:

$OSM_CNTK/scripts/install-osmdb.sh -p sr -i quick -s $SPEC_PATH -c 5

Recreating an Instance

If you face issues when creating an instance, do not try to re-run the create-instance.sh script as this will fail. Instead, perform the cleanup activities and then run the following command:

$OSM_CNTK/scripts/create-instance.sh -p sr -i quick -s $SPEC_PATH

Next Steps

A basic OSM cloud native instance should now be running in your environment. This process exposed you to some of the base functionality and concepts that are new to OSM cloud native. You can continue in your sandbox environment learning about more OSM cloud native capabilities by following the learning path.

If, however, your first priority is to understand details on infrastructure setup and structuring of OSM instances for your organization, then you should follow the infrastructure path.

To follow the infrastructure path, proceed to "Planning Infrastructure".

To follow the learning path, proceed to "Creating Your Own OSM Cloud Native Instance".