1. Migrating Oracle Application Container Cloud Service Applications to Oracle Cloud Infrastructure
  2. Migrate Your Oracle Application Container Cloud Service Applications to Oracle Cloud Infrastructure Container Engine for Kubernetes
  3. Migrate Your Applications Using the Script Tool

Migrate Your Applications Using the Script Tool

Migrate your Oracle Application Container Cloud Service applications to Oracle Cloud Infrastructure Container Engine for Kubernetes by using the migration script tool. The migration script tool helps you to create the Oracle Cloud Infrastructure resources required to create a Kubernetes cluster and deploy your application. Also, you can deploy your application in an existing Kubernetes cluster.

Migrating an application using the migration script tool involves the following steps:

Create Application

  1. Configures Kubectl for the given Kubernetes cluster in Oracle Cloud Infrastructure Container Engine for Kubernetes. If the Kubernetes cluster doesn't exist, creates a Kubernetes cluster with the following details:
    • A VCN with the following:
      • An Internet gateway
      • A NAT gateway
      • Two load balancer subnets. One per availability domain for two availability domains
      • Three worker node subnets. One per availability domain for three availability domains
      • Security lists and routing rules for the load balancing and worker node subnets
    • A worker node pool with the following:
      • Three worker nodes. One per availability domain for three availability domains.
      • Node image: Oracle-Linux-7.5
      • Node shape: VM.Standard2.1
  2. Builds the application image
    • If a URL is provided downloads the application image to the local disk
    • Builds a local Docker image with optional Linux packages
    • Pushes the local Docker image to Oracle Cloud Infrastructure Registry
  3. Creates the application in the Kubernetes cluster
    • Creates the ConfigMap for the environment variables
    • Creates the secret for the TLS certificate and key, if SSL is required
    • Creates the Kubernetes deployment and the service yaml configuration
    • Creates the deployment and the service for the application using a yaml configuration
    • Sets up an Nginx ingress controller, if HTTP to HTTPS redirect or IP_HASH load balancing policy is configured in application manifest
  4. (Optional) Sets up a custom URL
    • Creates a DNS zone (if it doesn't exist already)
    • Adds a DNS record for the application in a DNS zone

Delete Application

  1. Deletes the DNS record
  2. Deletes the Kubernetes resources (service, deployment, ConfigMap and secrets)
  3. (Optional) Deletes the temporary files (application archive and contents, Dockerfile, Kubernetes configuration file and logs)

Topics:

Download and Install the Migration Script Tool

The migration script tool helps you to migrate your Oracle Application Container Cloud Service applications to Oracle Cloud Infrastructure Container Engine for Kubernetes.

To download and install the migration script tool:
  1. In the Oracle Application Container Cloud Service console, click Help, then click Download Center, and download the migration script tool.
  2. Extract the contents of zip file to a directory.
  3. Open a command-line window and go to the directory where you extracted the content.
  4. Run the help command.
    python app.py -h

Example:

$ python app.py -h
usage: app.py [-h] [-a ACTION] [-f CONFIGFILE]
 
Performs various actions on an application in OKE (OCI).
 
optional arguments:
  -h, --help            show this help message and exit
  -a ACTION, --action ACTION
                        Action to perform: a) create - Create an application
                        (default), b) delete - Delete an application.
  -f CONFIGFILE, --configFile CONFIGFILE
                        Location of config file containing information
                        required to perform the action.

Create a Configuration File

You need to create a configuration file to migrate an application using the migration script tool. This file is required to create an application in Oracle Cloud Infrastructure Container Engine for Kubernetes and contains the information in JSON format.

To create a configuration file, use the following template:
{
    "account": {
        "authToken": "<auth-token>",
        "profile": "<oci-profile-name>",
        "OCIConfig":"<oci-config-path>"
    },
    "application": {
        "name": "<application-name>",
        "runtime": "<application-runtime>",
        "source": "<application-archive-location>",
        "manifest": "<manifest-file>",        
        "deployment": "<deployment-file>",
        "ssl": {
            "tlsKey": "<TLS-key>",
            "tlsCert": "<TLS-certificate>"
        },
        "environment-variables":{
            "<env-var-key1>": "<env-var-value1>",
            "<env-var-key2>": "<env-var-value2>"
        }
    },
    "cluster": {
        "compartmentOCID": "<compartmentOCID>",
        "name": "<oke-cluster-name>",
        "sshPublicKey": "<sshPublicKey>"
    },
    "dnszone": {
        "name": "<dnszone-name>",
        "compartmentOCID": "<compartmentOCID-zone>"
    }
}
The template contains the following sections:
  • Account: Contains the Oracle Cloud Infrastructure account user information.
  • Application: Contains the details of the application.
  • Cluster: Contains the details of the Oracle Cloud Infrastructure Container Engine for Kubernetes cluster. You can use an existing cluster, or if the cluster doesn't exist, it's created.
  • Dnszone: This section is optional and contains the DNS zone details for the custom URL. If the DNS zone specified in the dnszone.name property doesn't exist, it's created. The application URL is generated as: http[s]://${application.name}.${dnszone.name}.

Use the following table to replace the placeholders in the configuration file:

Placeholder Description Required
auth-token Oracle Cloud Infrastructure authentication token. Yes
oci-config-path Path of the Oracle Cloud Infrastructure configuration file. The default value is: ~/.oci/config. No
oci-profile-name Oracle Cloud Infrastructure configuration profile name. The default value is: DEFAULT. No
application-name Name of the application. Yes
application-runtime Application runtime: java, node, php, javaee, dotnet, ruby, python, or golang. Yes
application-archive-location The Pre-authenticated request URL of the application archive in Oracle Cloud Infrastructure Object Storage or the application archive location in your local disk. Yes
manifest-file Path of the manifest.json file. If the path of the manifest.json file is specified, the manifest.json file in the application archive is ignored. No
deployment-file Path of the deployment.json file. If the path of the deployment.json file is specified, then the deployment.json file in the application archive is ignored. No
env-var-keyN and env-var-valueN Custom environment variables used by the application. No
TLS-certificate Path of the SSH public key file for worker nodes. In order to access worker nodes with this SSH public key, you will need to set up a bastion host. See Bastion Hosts. It's required if you specified the application.ssl section.
TLS-key Path of the TLS key file. It's required if you specified the application.ssl section.
compartmentOCID OCID of the compartment where the cluster exists, or needs to be created. Yes
oke-cluster-name Name of cluster. Yes
sshPublicKey Path of the SSH public key file for worker nodes. No
compartmentOCID-zone OCID of the compartment where the DNS zone exists, or needs to be created. It's required if you specified the dnszone section.
dnszone-name Name of the DNS zone. It's required if you specified the dnszone section.

Example:

{
    "account": {
        "authToken": "wIp6s6Ag1klYZ:;QcxDR",
        "profile": "DEFAULT",
        "OCIConfig":"~/.oci/config"
    },
    "application": {
        "name": "testApp",
        "runtime": "java",
        "source": "https://objectstorage.us-ashburn-1.oraclecloud.com/p/Wul6OaR7rjB9kHwgYSY-wEjF5a-VBO1zURGZCODL50k/n/tenancy1/b/dt-accs/o/java-sample-18.4.6.zip",
        "ssl": {
            "tlsKey": "tls.key",
            "tlsCert": "tls.crt"
        },
        "environment-variables": {
            "key1": "value1",
            "key2": "value2"
        }
    },
    "cluster": {
        "compartmentOCID": "ocid1.compartment.oc1..aaaaaaaac5auvec5dn746hr7cndfan5rscrawzdkzwolsgew4deow3shjyra",
        "name": "testCluster",
        "sshPublicKey": "/home/user1/.ssh/id_rsa.pub"
    },
    "dnszone": {
        "name": "example.com",
        "compartmentOCID": "ocid1.compartment.oc1..aaaaaaaac5auvec5dn746hr7cndfan5rscrawzdkzwolsgew4deow3shjyra"
    }
}

Set up the Environment Variables

Migrate the environment variables that are required for your Oracle Application Container Cloud Service application to a Kubernetes configuration.

Custom Environment Variables

You defined these variables for your application in the deployment.json file. The migration script reads the deployment.json file and automatically adds the variables to the Kubernetes configuration.

Service Binding Environment Variables

Oracle Application Container Cloud Service created these variables automatically when you added service bindings in your application. If your applications has configured one or more service bindings, locate the environment variables for each service binding.

To configure the service binding environment variables:

  1. Access your application in the Oracle Application Container Cloud Service console.
  2. Click the Deployment tab and identity the service binding variables from the Environment Variables section.
  3. Edit the configuration file and add each variable as "key": "value" on a separate line.

Example:

"environment-variables": {
  "MYSQLCS_CONNECT_STRING": "10.x.x.x:3306/mydb",
  "MYSQLCS_MYSQL_PORT": "3306",
  "MYSQLCS_USER_PASSWORD": "<your_password> ",
  "MYSQLCS_USER_NAME": "TestUser",
  "DBAAS_DEFAULT_CONNECT_DESCRIPTOR": "10.x.x.x:1521/mydb",
  "DBAAS_USER_NAME": "TestUser",
  "DBAAS_USER_PASSWORD": "<your_password>",
  "DBAAS_LISTENER_HOST_NAME": "10.x.x.x",
  "DBAAS_LISTENER_PORT": "1521",
  "DBAAS_DEFAULT_SID": "ORCL",
  "DBAAS_DEFAULT_SERVICE_NAME": "mydb"
}

Configure Java EE System and Service Binding Properties

In a Java EE application, if you use the system and JNDI service binding properties, you can specify those properties in the environment variables section in the configuration file..

System Properties

For Java EE applications you can configure system properties using the EXTRA_JAVA_PROPERTIES environment variable in the configuration file.

  1. Identify any system properties for your Java EE application.
  2. Add an environment variable named EXTRA_JAVA_PROPERTIES to the configuration file. Within the value of this variable, specify each system property using the -D flag. Separate each -D flag with a space.
    Example:
    "EXTRA_JAVA_PROPERTIES": "-DconfigPath=/u01/app/conf/ -DlogFile=/u01/app/logs/app.log"

Service Binding Properties

If your Java EE application uses one or more of the JNDI service binding properties namely jndi-name, max-capacity, min-capacity, or driver-properties, you must add those in the configuration file.

  1. Identify the service bindings used by your application.
  2. Edit the configuration file.
  3. Add an environment variables of your service using the key: 
    "<service-type>_SERVICE_BINDING_NAME": "<service-name>",

    Where:

    • <service-type> is the service type. For example, DBAAS, MYSQLCS etc.
    • <service-name> is the name of your service.

    Example:

    "DBAAS_SERVICE_BINDING_NAME": "testDb"
  4. Provide the JNDI service binding properties for your service using the key: 
    "<service-type>_PROPERTIES": "jndi-name:<jndi-name>|max-capacity:<max-capacity>|min-capacity:<min-capacity>|driver-properties:<driver-properties>|"

    Where:

    • <ocic-service-type> is the service type. For example DBAAS, MYSQLCS etc.
    • <jndi-name> is the JNDI name of your service. It should be in format "jdbc/<value>".For example, "jdbc/dbcs".
    • <max-capacity> is maximum capacity of the connection pool.
    • <min-capacity> is minimum capacity of the connection pool.
    • <driver-properties> is semi-colon separated list of properties that are passed to the JDBC driver.

Example:

"environment-variables": {
  "MYSQLCS_CONNECT_STRING": "10.x.x.x:3306/mydb",
  "MYSQLCS_MYSQL_PORT": "3306",
  "MYSQLCS_USER_PASSWORD": "<your_password>",
  "MYSQLCS_USER_NAME": "TestUser",
  "DBAAS_DEFAULT_CONNECT_DESCRIPTOR": "10.x.x.x:1521/mydb",
  "DBAAS_USER_NAME": "TestUser",
  "DBAAS_USER_PASSWORD": "<your_password>",
  "DBAAS_LISTENER_HOST_NAME": "10.x.x.x",
  "DBAAS_LISTENER_PORT": "1521",
  "DBAAS_DEFAULT_SID": "ORCL",
  "DBAAS_DEFAULT_SERVICE_NAME": "mydb",
  "EXTRA_JAVA_PROPERTIES": "-DconfigPath=/u01/app/conf/ -DlogFile=/u01/app/logs/app.log",
  "DBAAS_SERVICE_BINDING_NAME": "dbaasDb",
  "DBAAS_PROPERTIES": "jndi-name:jdbc/dbcs|max-capacity:5|min-capacity:1|driver-properties:user=admin;database=test|",
  "MYSQLCS_SERVICE_BINDING_NAME": "mysqlDb",
  "MYSQLCS_PROPERTIES": "jndi-name:jdbc/mysqlcs|max-capacity:10|min-capacity:1|driver-properties:user=oci;database=app|"
}

Enable Connectivity between the Kubernetes Cluster and Oracle Cloud Services

If your application in Oracle Application Container Cloud Service uses service bindings to enable communication with other Oracle Cloud services, then you need to ensure that after the migration your application is able to communicate with those services.

There are two scenarios:

  • If your service is in Oracle Cloud Infrastructure Classic, then in the Oracle Cloud Infrastructure Classic service, create an access rule that allows the Public IP address of NAT Gateway attached to the worker nodes of the Kubernetes cluster to connect to the service. For example, if your application uses Oracle Database Classic Cloud Service, then see Managing Network Access to Database Cloud Service.

    Note:

    The public IP address of the NAT Gateway can be located in the Oracle Cloud Infrastructure console from the menu: Developer Services, Container Clusters (OKE), Cluster Details, Node Pool Section, Node Instance Details, Virtual Cloud Network Details, NAT Gateways, Public IP Address.

  • If your service is in Oracle Cloud Infrastructure, then locate the VCN and subnets in which the service is deployed. Ensure that an ingress security rule exists to allow traffic from the Kubernetes cluster to the service. See Security Lists in the Oracle Cloud Infrastructure documentation.

Create the Application

Migrate your Oracle Application Container Cloud Service application to Oracle Cloud Infrastructure Container Engine for Kubernetes by using the create action in the migration script tool.

  1. To create the application, open a command-line window and run the migration script. Provide the path to your configuration file.
    python app.py -f <path-of-config-file>
  2. In the command-line window, enter YES to create the cluster. If you're using an existing cluster, this message is not displayed.
  3. Enter YES to create the DNS zone. If you're using an existing DNS Zone or you didn't specified one, this message is not displayed.

Example:

$ python app.py -f ./config.json
2019-03-12 13:59:18,794 root INFO Using default action: create
2019-03-12 13:59:18,794 root INFO Starting application creation.
2019-03-12 13:59:18,795 root INFO You have opted for SSL setup. Checking if TLS key and cert details are given.
2019-03-12 13:59:18,795 root INFO You have opted for URL setup. Checking if zone name and compartment OCID is given.
2019-03-12 13:59:18,795 root INFO Fetching OCI details....
2019-03-12 13:59:26,649 root INFO Checking OKE cluster existence in OCI with provided name: testCluster
2019-03-12 13:59:29,379 root INFO OKE Cluster testCluster with ocid: ocid1.cluster.oc1.eu-frankfurt-1.aaaaaaaaaxxxx already exists and it's in ACTIVE state in OCI, using this Cluster for further operations.
DNS Zone with name: example.com does not already exists in OCI and it needs to be created to proceed further. Do you want to continue ? Yes/No: yes
2019-03-12 14:01:36,390 root INFO Found existing cluster, creating kubeconfig
2019-03-12 14:01:36,391 root INFO Creating kubeconfig at file location: /root/.kube/config
2019-03-12 14:01:52,070 root INFO Using baseimage: iad.ocir.io/tenancy1/accs/java8:latest
2019-03-12 14:01:52,193 root INFO Pulling base image : iad.ocir.io/tenancy1/accs/java8:latest
2019-03-12 14:01:56,234 root INFO Building application image. This can take several minutes...
2019-03-12 14:01:56,470 root INFO Image tag is: FRA.ocir.io/tenancy1/accs/oci_user1/webapp01:latest
2019-03-12 14:01:56,528 root INFO Pushing application image to OCI registry. This can take several minutes...
2019-03-12 14:03:12,734 root INFO Application image successfully pushed to OCI registry.
2019-03-12 14:03:19,092 root INFO Config Map created successfully
2019-03-12 14:03:19,092 root INFO Creating docker-registry secret for pulling images from ocir.
2019-03-12 14:03:21,278 root INFO Docker-registry secret for pulling images from ocir has been created successfully.
2019-03-12 14:03:21,279 root INFO Creating deployment for application. This can take several minutes...
deployment "webapp01-deployment" successfully rolled out
2019-03-12 14:03:27,578 root INFO Deployment created successfully.
2019-03-12 14:03:27,579 root INFO Creating service for application. This can take several minutes...
2019-03-12 14:03:29,638 root INFO Kubernetes service created successfully.
2019-03-12 14:03:39,432 root INFO Checking if load balancer is accessible. This can take several minutes...
2019-03-12 14:03:41,542 root INFO Load balancer is accessible. Public IP address of load balancer is: 130.x.x.x
2019-03-12 14:03:46,846 root INFO Zone not found. Creating new zone: example.com
2019-03-12 14:03:58,930 root INFO Zone created.
2019-03-12 14:04:04,346 root INFO Adding DNS record: webapp01.example.com
2019-03-12 14:04:12,202 root INFO DNS record added.
2019-03-12 14:04:12,202 root INFO Application URL is: https://webapp01.example.com
2019-03-12 14:04:12,203 root INFO Application creation completed.

The example creates a Java application with an existing cluster and using an SSL endpoint, a custom URL and a new DNS zone.

Delete the Application

If you face issues during the creation, you can delete your application from the Oracle Cloud Infrastructure Container Engine for Kubernetes cluster, and start again. You can use the delete application action which reads the configuration file and deletes the DNS record, application resources in Kubernetes cluster, and the application directory (migration_tool/work/<application-name>) .

  1. To delete the application, open a command-line window and run the migration script. Provide the path to your configuration file.
    python app.py -a delete -f <path-of-config-file>
  2. In the command-line window, enter YES to delete the application directory.

Note:

The delete option doesn't delete the Oracle Cloud Infrastructure resources such as clusters, VCNs, subnets, or DNS Zones. If you require to delete the resources, you need to delete them manually using the Oracle Cloud Infrastructure console or the REST API.

Example:

$ python app.py -a delete -f ./config.json
2019-03-27 16:30:36,348 root INFO Starting application deletion.
2019-03-27 16:30:36,348 root INFO Verifying input config file...
2019-03-27 16:30:36,348 root INFO URL setup is enabled. Checking if zone name and compartment OCID is given.
2019-03-27 16:30:36,348 root INFO Fetching OCI details....
2019-03-27 16:30:44,007 root INFO Checking if any Kubernetes resources exist for the application...
2019-03-27 16:30:57,031 root INFO Some Kubernetes resources found for the application. Cleaning up...
2019-03-27 16:31:08,109 root INFO Kubernetes resources cleaned up successfully.
2019-03-27 16:31:08,110 root INFO Checking if application data exists in local directory...
The application data exists at location /home/amanmi/migration/webapp01 . Do you want to remove it ? Yes/No: y
2019-03-27 16:31:10,480 root INFO Successfully removed application data from local directory.
2019-03-27 16:31:10,662 root INFO Checking if DNS zone record exists...
2019-03-27 16:31:15,467 root INFO DNS zone record exists. Removing it...
2019-03-27 16:31:21,199 root INFO DNS zone record removed successfully.
2019-03-27 16:31:21,199 root INFO Application deletion completed

Get Script Logs

You can get detailed script logs from: $SCRIPT_ROOT_FOLDER/work/<app-name>/<action>/logs/accs-migration.log.

Where:
  • $SCRIPT_ROOT_FOLDER the directory where it's the migration script tool (app.py).
  • <app-name> it's the application name you specified in your configuration file.

Example:

$ tail -10 /home/user1/migration/work/webapp01/create/logs/accs-migration.log
2019-03-11 20:30:59,143 root INFO Load balancer is accessible. Public IP address of load balancer is: 132.x.x.x
2019-03-11 20:31:10,166 root INFO Zone already exists: example.com
2019-03-11 20:31:10,167 root DEBUG DNS record: webapp01.example.com
2019-03-11 20:31:14,101 root INFO Zone record already exists: {u'domain': u'webapp01.example.com', u'record-hash': u'd4b80feda63ed0a90523073253f6edfa', u'rtype': u'A', u'ttl': 1800, u'rdata': u'132.x.x.x', u'is-protected': False, u'rrset-version': u'146'}
2019-03-11 20:31:14,101 root INFO Deleting existing zone record: webapp01.example.com
2019-03-11 20:31:18,998 root INFO Zone record deleted.
2019-03-11 20:31:18,998 root INFO Adding DNS record: webapp01.example.com
2019-03-11 20:31:27,295 root INFO DNS record added.
2019-03-11 20:31:27,296 root INFO Application URL is: https://webapp01.example.com
2019-03-11 20:31:27,297 root INFO Application creation completed.