1. Cloud Native Deployment Guide
  2. Creating an ASAP Cloud Native Instance

4 Creating an ASAP Cloud Native Instance

This chapter describes how to create an ASAP cloud native instance in your cloud environment using the operational scripts and the base ASAP configuration provided in the ASAP cloud native toolkit. You can create an ASAP instance quickly 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 an ASAP instance in your environment.

Before you create an ASAP instance, you must do the following:

  • Download the ASAP cloud native tar file and extract the asap-cntk.zip file. For more information about downloading the ASAP cloud native toolkit, see "Downloading the ASAP Cloud Native Artifacts".
  • Install the Traefik container images

Installing the ASAP Cloud Native Artifacts and the Toolkit

Build container image for the ASAP application using the ASAP cloud native Image Builder.

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

Copy the ASAP cloud native toolkit that is the asap-cntk.zip file to one of the nodes in the Kubernetes cluster:

  • 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 asap_cntk_path is the installation directory of the ASAP cloud native toolkit:
$ export ASAP_CNTK=asap_cntk_path

Installing the Traefik Container Image

Note:

If you are installing Order Balancer in the ASAP namespace, ignore this section.

To leverage the ASAP cloud native samples that integrate with Traefik, the Kubernetes environment must have the Traefik ingress controller installed and configured.

If you are working in an environment where the Kubernetes cluster is shared, confirm whether Traefik has already been installed and configured for ASAP cloud native. If Traefik is already installed and configured, set your TRAEFIK_NS environment variable to the appropriate name space.

The instance of Traefik that you installed to validate your cloud environment must be removed as it does not leverage the ASAP cloud native samples. Ensure that you have removed this installation in addition to purging the Helm release. Check that any roles and rolebindings created by Traefik are removed. There could be a clusterrole and clusterrolebinding called "traefik-operator". There could also be a role and rolebinding called "traefik-operator" in the $TRAEFIK_NS name space. Delete all of these before you set up Traefik.

To download and install the Traefik container image:

  1. Ensure that Podman in your Kubernetes cluster can pull images from the container registry. See ASAP Compatibility Matrix for the required and supported versions of the Traefik image.
  2. Run the following command to create a name space ensuring that it does not already exist:

    Note:

    You might want to add the traefik name space to the environment setup such as .bashrc. 
    kubectl get namespaces
export TRAEFIK_NS=traefik   
kubectl create namespace $TRAEFIK_NS
  3. Run the following commands to install Traefik using the $ASAP_CNTK/samples/charts/traefik/values.yaml file in the samples:

    Note:

    Set kubernetes.namespaces and the chart version specifically using command-line. 
    helm repo add traefik repo_link
helm install traefik-operator traefik/traefik \
 --namespace $TRAEFIK_NS \
 --values $ASAP_CNTK/samples/charts/traefik/values.yaml \
  --set "kubernetes.namespaces={$TRAEFIK_NS}" 
   --version 26.0.0

    where repo_link is https://helm.traefik.io/traefik or https://traefik.github.io/charts based on the helm chart version. For more details, see: https://github.com/traefik/traefik-helm-chart

    Note:

    When the Traefik chart version is 26.0.0, you must use the Traefik image version 2.10.6 only.

After the installation, Traefik monitors the name spaces listed in its kubernetes.namespaces field for Ingress objects. The scripts in the toolkit manage this name space list as part of creating and tearing down ASAP cloud native projects.

When the values.yaml Traefik sample in the ASAP cloud native toolkit is used as is, Traefik is exposed to the network outside of the Kubernetes cluster through port 30305. To use a different port, edit the YAML file before installing Traefik. Traefik metrics are also available for Prometheus to scrape from the standard annotations.

Traefik function can be viewed using the Traefik dashboard. Create the Traefik dashboard by running the instructions provided in the $ASAP_CNTK/samples/charts/traefik/traefik-dashboard.yaml file. To access this dashboard, the URL is: http://traefik.asap.org. This is if you use the values.yaml file provided with the ASAP cloud native toolkit; it is possible to change the hostname as well as the port to your desired values.

Creating an ASAP Instance

This section describes how to create an ASAP instance.

Setting Environment Variables

ASAP cloud native relies on access to certain environment variables to run seamlessly. Ensure the following variables are set in your environment:
  • Path to your private specification repository
  • Traefik name space

To set the environment variables:

  • Set the TRAEFIK_NS variable for Traefik name space as follows:
    $ export TRAEFIK_NS=Treafik Namespace

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, ASAP cloud native does not establish password policies.

For an ASAP could native instance, the following secrets are required:
  • imagepull-secret: If the private registry or repository is password protected, create this secret.
  • tls-secret: If the traefik ingress is ssl-enabled, create this secret. For more information about creating tls-secret, see "Setting Up ASAP Cloud Native for Incoming Access."

To create imagepull-secret:

  1. Run the following command:
    podman login
  2. Enter the credentials or access token.

    The login process creates or updates the config.json file that contains an authorization token.

  3. Run the following command to run the secret:
    kubectl create secret generic asap-imagepull -n namespace

Registering the Namespace

After you set the environment variables, register the name space. To register the name space, run the following command:

$ASAP_CNTK/scripts/register-namespace.sh -p sr -t targets
# For example, $ASAP_CNTK/scripts/register-namespace.sh -p sr -t traefik

Where -p is the namespace where ASAP is being deployed.

Note:

traefik is the name of the targets for registration of the namespace sr. The script uses TRAEFIK_NS to find these targets. Do not provide the traefik target if you are not using Traefik.

Creating an ASAP Instance

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

To create an ASAP instance:
  1. Update the $ASAP_CNTK/charts/asap/values.yaml file with the following values:
    # Default values for asap.
# This is a YAML-formatted file.
# Declare variables to be passed into your templates.

replicaCount: 1
image:
  repository: asapcn
  pullPolicy: IfNotPresent
  tag: "7.4.1.0.0"
imagePullSecrets:
  - name: asap-imagepull
asapEnv:
  envid: cne1
  port: 7890
  host: asaphost
persistence:
  enabled: false
readiness:
  enabled: true
  initialDelaySeconds: 240
  periodSeconds: 60
liveness:
  enabled: true
  periodSeconds: 120
  initialDelaySeconds: 120
  failureThreshold: 3
nameOverride: ""
fullnameOverride: ""

serviceAccount:
  # Specifies whether a service account should be created
  create: true
  # Annotations to add to the service account
  annotations: {}
  # The name of the service account to use.
  # If not set and create is true, a name is generated using the fullname template
  name: ""

podAnnotations: {}
podSecurityContext: {}
  # fsGroup: 2000
securityContext: {}
  # capabilities:
  #   drop:
  #   - ALL
  # readOnlyRootFilesystem: true
  # runAsNonRoot: true
  # runAsUser: 1000
servicechannel:
  name: channelport
  type: ClusterIP
  port: 7891
service:
  name: adminport
  type: ClusterIP
  port: 7890

ingress:
  type: TRAEFIK
  enabled: true
  sslIncoming: false
  adminsslhostname: adminhost.asap.org
  adminhostname: adminhostnonssl.asap.org
  secretName: project-instance-asapcn-tls-cert
  hosts:
    - host: adminhost.asap.org
      paths: []
  tls: []
  #  - secretName: chart-example-tls
  #    hosts:
  #      - chart-example.local

resources: {}
autoscaling:
  enabled: false
nodeSelector: {}
tolerations: []

affinity: {}
    The variables in the example have the following values:
    • repository is the repository name of the configured container registry
    • tag is the version name that is used when you create a final ASAP image from the container
    • name is the name of the imagepull-secret if it is configured. For more information about imagepull-secret, see "Creating Secrets".
    • envid is the unique environment ID of the instance. This ID should include only the lower-case alphanumeric characters. For example, asapinstance1.
    • port is the port number of the WebLogic Server where ASAP is deployed.
    • host is the hostname of the Podman container.

      Note:

      The hostname should match with the hostname when you create the ASAP image. If the hostname mismatches, the ASAP servers may not start.
    • persistence.enabled is set to true if PVC is enabled.
    • readiness.enabled is set to true to enable the readiness probe in Kubernetes. You configure the readiness and liveness probes in Kubernetes to restart the failed ASAP instances automatically and to restore the services. Kubernetes uses the liveness and readiness probes to find the failed ASAP instances and restarts those instances to restore the services automatically. Kubernetes uses the readiness probe to know when a container is ready to start accepting traffic.
    • initialDelaySeconds is the number of seconds after the ASAP instance has started before the readiness probes are initiated.
    • periodSeconds specifies how often (in seconds) to perform the readiness probe.
    • liveness.enabled is set to true to enable the liveness probe. Kubernetes uses the liveness probes to know when to restart a container.
    • periodSeconds specifies how often (in seconds) to perform the liveness probe.
    • initialDelaySeconds is the number of seconds after the ASAP instance has started before the liveness probes are initiated.
    • failureThreshold is the number of times that Kubernetes retry the liveness probes before restarting the ASAP instance.
    • servicechannel.port is the channel port when you create a channel in the WebLogic domain.
    • service.port is the admin port of the WebLogic Server.
    • type is the ingress controller type. This type can be TRAEFIK or GENERIC or OTHER.
    • enabled is the status of the ingress controller whether it is enabled or not. The value is true or false. By default, this is set to true.
    • sslIncoming is the status of the SSL/TLS configuration on incoming connections whether it is enabled or not. The configuration value is true or false. By default, this is set to false. If you want to set the value to true, create keys, certificate, and secret by following the instructions in the "Setting Up ASAP Cloud Native for Incoming Access" section.
    • adminsslhostname is the hostname of the https access.
    • adminhostname is the hostname of the http access.
    • secretName is the secret name of the certificate created for SSL/TLS. For more information about creating keys and secret name, see "Setting Up ASAP Cloud Native for Incoming Access."

    Note:

    adminsslhostname and secretName are applicable only if sslIncoming is set to true.
  2. Create PV and PVC if the persistence.enabled is set to true in the $ASAP_CNTK/charts/asap/values.yaml file for the ASAP instance. The PV path is used to store the logs of the ASAP instance. The sample files are available in the asap_cntk.zip at $ASAP_CNTK/samples/nfs/ file. Use the hostPath to access the local nodes. Use nfs to access all the nodes. 
    # This is pv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: project-asapEnv.envid-nfs-pv
  labels:
    type: local
spec:
  storageClassName: asaplogs
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
#  hostPath:
#   path: "/mnt/asap/logs/
  nfs:
    server: <server>
    path: <path>
# This is pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <asapEnv.envid>-pvc
  namespace: sr
spec:
  storageClassName: asaplogs
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
    Where:
    • project is the namespace. In the above example, value is sr.
    • asapEnv.envid is the environment ID provided in the $ASAP_CNTK/charts/asap/values.yaml file. In the above example, value is cne1.

    This path will be mounted on the Pod as /scratch/oracle/asap/DATA/logs/

  3. Run the following command to create the ASAP instance:
    $ASAP_CNTK/scripts/create-instance.sh -p sr -i quick

    The create-instance.sh script uses the Helm chart located in the charts/asap directory to deploy the ASAP image, service, and ingress controller for your instance. If the script fails, see "Troubleshooting Issues with the Scripts" before you make additional attempts.

  4. After you run the create-instance.sh script, validate the important input details in the response such as Image name and tag, specification files used (Values Applied), hostname, and port for ingress routing:
    
1 chart(s) linted, 0 chart(s) failed
Project Namespace : sr
Instance Fullname : sr-quick

NAME: sr-quick
LAST DEPLOYED: Sun Feb 27 17:49:25 2022
NAMESPACE: sr
STATUS: deployed
REVISION: 1
TEST SUITE: None
  5. If you query the status of the ASAP pod, the READY state of the ASAP pod displays 0/1 for several minutes when the ASAP application is starting.

    When the READY state shows 1/1, your ASAP instance is up and running. You can then validate the instance by submitting work orders.

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

The create-instance script prints out the following valuable information that you can use when you work with your ASAP domain:

  • The T3 URL: http://t3.quick.sr.asap.org This is required for external client applications such as JMS and WLST.
  • The URL for accessing the WebLogic UI, which is provided through the ingress controller at host: http://admin.quick.sr.asap.org:30305/console.

Validating the ASAP Instance

After creating an instance, you can validate it by accessing the WebLogic Server console.

Run the following command to display the pod details of the ASAP instance that you have created:
$ kubectl get all -n sr
NAME                                   READY   STATUS    RESTARTS   AGE
pod/asapinstance1-deployment-9845fbcb6-8qq2h    1/1     Running   0          5d15h
NAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
service/asapinstance1-service   ClusterIP   10.99.231.206   <none>        7890/TCP,7891/TCP   5d21h
NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/asapinstance1-deployment   1/1     1            1           5d21h
NAME                                         DESIRED   CURRENT   READY   AGE
replicaset.apps/asapinstance1-deployment-d5bd787f8    0         0         0       5d15h
To get the ASAP server status enter into the pod by using the following command:
kubectl exec -it asapinstance1-deployment-9845fbcb6-8qq2h bash -n sr
You are now entered into the ASAP pod. Navigate to the ASAP installation directory by using the following command:
cd $ASAP_BASE
source Environment_Profile
status
The status of ASAP servers are displayed. Ensure that there are minimum 5 processes in the output of status command, one process each of Control server, Daemon server, SARM, NEP and JNEP. In ASAP 7.4.1, on successful startup, the minimum process count is 5 as compared to 8 processes in 7.3.0 and 7.4.0.For example:
[root@asaphost asap]# status
               **** ASAP Application Status ****

    #  CPU       PID      Program                                  Application Location
    -- --------- -------- ---------------------------------------- ----------- --------
    1  00:00:16  251011   $ASAP_BASE/programs/ctrl_svr             CTRLCNE1    LOCAL   
    2  00:00:30  251381   $ASAP_BASE/programs/sarm                 SARMCNE1    LOCAL   
    3  00:00:08  251497   java                                     DAEMCNE1    LOCAL   
    4  00:00:08  279257   java                                     JNEP_CNE1   LOCAL   
    5  00:00:07  279319   $ASAP_BASE/programs/asc_nep              NEP_CNE1    LOCAL   

               **** End of Application Status ****

CNE1 is the ENV_ID.

Note:

After an ASAP instance is created, it may take a few minutes to start ASAP servers and WebLogic Server.
To access WebLogic Administration Console outside the cluster, enter the following URL in the browser:
http://adminhostnonssl.asap.org:30305/console

The system prompts for the user name and password. Enter the WebLogic domain user name and password.

Update the hosts file with the hostname and master_ip address on the machine where the URL is getting accessed with the following information:
ip_address adminhostnonssl.asap.org

Note:

The hosts file is located in /etc/hosts on Linux and MacOS machines and in C:\Windows\System32\drivers\etc\hosts on Windows machines.

Submitting Orders

After you install ASAP, install the POTS cartridge. You can submit ASAP orders over JMS and Web Services.

To submit ASAP orders over JMS, use an external runJMSclient. The endpoint must be as follows: 
System.${ENV_ID}.ApplicationType.ServiceActivation.Application.1-0;7-4;ASAP.Comp.MessageQueue

The connection factory's provider URL must be as follows:

For non-SSL: 
http://adminhostnonssl.asap.org:30305/

For SSL: 

https://adminhostssl.asap.org:30443/
To submit ASAP orders over Web Services, type the following URL in the web browser and access the ASAP Web Services WSDL:
http://adminhostnonssl.asap.org:30305/env_id/Oracle/CGBU/Mslv/Asap/Ws?WSDL

HTTP protocol is used for a handshake with the application server to authenticate and request a web service client stub, which is used as the launch pad to talk to Web Services. Then the client can communicate with the ASAP Web Services using HTTP or HTTPS protocols.

Deleting and Recreating Your ASAP Instance

Deleting Your ASAP Instance

To delete your ASAP instance, run the following command:
$ASAP_CNTK/scripts/delete-instance.sh -p sr -i quick

Recreating Your ASAP Instance

When you delete an ASAP instance, the database state for that instance still remains unaffected. You can re-create an ASAP instance by using the same ASAP image.

To re-create an ASAP instance, run the following command:
$ASAP_CNTK/scripts/create-instance.sh -p sr -i quick

Note:

After recreating an instance, client applications such as SoapUI may need to be restarted to avoid using expired cache information.

If another ASAP instance is created in the same database using the same Environment ID, the ASAP installer deletes the previous ASAP database users and recreates new users.

You should not create multiple ASAP instances with the same ASAP image.

Cleaning Up the Environment

To clean up the environment:
  1. Delete the instance:
    $ASAP_CNTK/scripts/delete-instance.sh -p sr -i quick
  2. Delete the name space, which in turn deletes the Kubernetes name space and the secrets:
    $ASAP_CNTK/scripts/unregister-namespace.sh -p sr -d -t target

    Note:

    traefik is the name of the target for registration of the name space. The script uses TRAEFIK_NS to find this target. Do not provide the "traefik" target if you are not using Traefik.
  3. Delete the ASAP database users.

Troubleshooting Issues with the Scripts

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

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

  • Check the "Status" section of the domain to see if there is useful information:
    kubectl describe pod name -n sr

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:

  1. Delete the instance:
    $ASAP_CNTK/scripts/delete-instance.sh -p sr -i quick

Recreating an Instance

If you encounter 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:
$ASAP_CNTK/scripts/create-instance.sh -p sr -i quick

Accessing the OCA Client

Similar to the ASAP traditional deployment, ASAP cloud native also connects through the Order Control Application (OCA) client using thin client.

To configure the OCA client:

  1. Add an entry to the hosts file to the machine (Unix or Windows) from which the user is planning to launch the OCA client to resolve DNS.

    This entry contains the IP address of the master node and hostname of the ASAP instance running in a cloud native. You can obtain the hostname from the values.yaml file.

    The hosts configuration file is located at:
    • On Windows: C:\Windows\System32\drivers\etc\hosts
    • On Linux: /etc/hosts
    For example:
    Kubernetes_Cluster_Master_IP hostname provided in the values.yaml file
  2. Update the TBL_SERVER_INFO table in the CTRL database.

    The hostname column contains the hostname mentioned in the values.yaml file and INFO column contains ‘HTTPS:<ingressport>’

    For example:
    update tbl_server_info set HOST_NAME='adminhost.asap.org';
update tbl_server_info set INFO='HTTP:30305';
update tbl_server_info set INFO='HTTPS:30443';
update tbl_server_info set INFO='HTTPS:80';

    Note:

    Based on the Ingressroute configuration use HTTP or HTTPS. The port number is the traefik nodeport.
  3. Launch the thin client once the database is updated with the following URL: https:HOST:ingressport/ENVID/OCA

Next Steps

The ASAP instance is ready to add the Order Balancer cloud native instance. The URL for adding the Order Balancer instance is:

t3://service-name.namespace.svc.cluster.local:portnumber

Where:
  • service-name is the name of the service.
  • namespace is the namespace of the ASAP instance.
  • portnumber is the port number of the WebLogic Server Domain in the ASAP instance.
Here is an example for adding the ASAP instance to Order Balancer:
  • ./addASAPServer -asapSrvName ASAP1 -asapSrvURL t3://cne1-service.sr.svc.cluster.local:7890 -asapSrvUser weblogic -asapSrvRequestQueue "System.CNE1.ApplicationType.ServiceActivation.Application.1-0;7-4;ASAP.Comp.MessageQueue"

For more information about managing ASAP instances, see "Setting Up ASAP for High Availability" in ASAP System Administrator's Guide.