Create and Manage an Oracle Java Cloud Service Instance Using the CLI

Before You Begin

This 30-minute tutorial shows you how to create, back up, and scale an Oracle Java Cloud Service instance from the command-line interface (CLI).

Background

The Platform Service Manager (PSM) CLI is a Python module for configuring and managing the lifecycle of PaaS services on Oracle Cloud, including Oracle Java Cloud Service instances.

Note: This tutorial creates a service instance within an Oracle Cloud Infrastructure Classic region. To learn about the differences between Oracle Cloud Infrastructure Classic and Oracle Cloud Infrastructure, see About Java Cloud Service Instances in Oracle Cloud Infrastructure.

What Do You Need?

An active subscription to Oracle Java Cloud Service. See How to Begin with Oracle Java Cloud Service Subscriptions.
An existing Oracle Database Cloud Service deployment with backups enabled. See Creating a Customized Database Deployment.
A Python 3.3 or later installation
An SSH key pair. See Generating a Key Pair with OpenSSH or Generating a Key Pair with PuTTY.

Download the CLI

Sign in to Oracle Cloud as a user with the Java Administrator role.
From the Oracle Cloud Infrastructure Console, click the Navigation menu at the top left corner of the page, expand Platform Services, and then select Java.
Note: On some older Oracle Cloud accounts, you use the Oracle Cloud Infrastructure Classic Console. Click the Navigation menu , and then select Java.
If this is the first time you have accessed Java Cloud Service then you may be presented with a Welcome screen. If this happens then you can continue to the console by clicking Go to Console.
Make a note of your Data Region, which is shown in the upper right banner of the Oracle Cloud Infrastructure Console. For example: US East (Ashburn).
From the Navigation menu , select Identity, and then Federation. Click the name of your identity provider, and then click Oracle Identity Cloud Service Console.
On the Oracle Identity Cloud Service Console, click on the User Profile menu on the upper right corner of the console and select About. Record the Instance GUID. This is the Identity Service ID.
You will need the Data Region and Identity Service ID later when you configure the CLI.
Find and record the REST endpoint URL of the Oracle Cloud Infrastructure Object Storage Classic service instance in the Infrastructure Classic Console. See Accessing Object Storage in Using Oracle Cloud Infrastructure Object Storage Classic.
You will need this URL later when you configure backups.

For example: https://foo.storage.oraclecloud.com/v1/MyService-bar.
Navigate back to the Oracle Java Cloud Service console, and then click the user icon at the top right corner of the page. Expand Help, and then select Download Center.
Locate the description of the PSM CLI, and then click Download . Save the file psmcli.zip to your computer.

Install and Configure the CLI

This tutorial assumes that your Python installation has been added to the PATH environment variable.

Launch a command prompt and execute this Python command:
```
pip3 install -U psmcli.zip
```
On Linux, if Python was installed as the root user or to the default location on the file system, you must run this command using sudo.
Run the setup command:
```
psm setup
```
When prompted, enter the credentials of an Oracle Cloud user with the Java Administrator role, along with your Identity Service ID.
```
Username: your_username
Password: your_password
Retype Password: your_password
Identity domain: your_identity_service_id
```
When prompted for a region, enter one of the following values based on the Data Region for your cloud account:
- us
- emea
- aucom
Accept the default values for the remaining inputs. After the CLI setup has completed successfully, it displays the list of PaaS services in your cloud account, including Oracle Java Cloud Service (jcs). For example:
```
'psm setup' was successful. Available services are:
  o dics
       Oracle Data Integration Platform Cloud Service
  o jcs
       Oracle Java Cloud Service
  ...
```

Create a Service Instance

Download create.json to your computer, and then open it in a text editor.
Copy and paste your SSH public key into the value for the vmPublicKeyText attribute:
```
"vmPublicKeyText": "your_public_key"
```
Enter a password for Oracle WebLogic Server in the adminPassword attribute:
```
"adminPassword": "your_weblogic_password"
```
Enter the instance name and administrator password for your existing Oracle Database Cloud Service instance:
```
"dbServiceName": "your_database_instance",
"dbaName": "SYS",
"dbaPassword": "your_database_password"
```
Save your changes.
Tip: For descriptions of all available payload attributes, see Create a Service Instance in REST API for Oracle Java Cloud Service.
Run the create-service command and provide the location of create.json.
```
psm jcs create-service -c create.json
```
From the command output, identify the job ID. For example:
```
Job ID: 55550001
```
Run the operation-status command and specify the job ID. Periodically run this command until the status of the job is SUCCEED. For example:
```
psm jcs operation-status -j 55550001

Service:           MyJCS
Operation Type:    CREATE_SERVICE
Status:            SUCCEED
```
Tip: For more detailed information about the job, specify the JSON output format: -of json.

Run the service command to view details about your service instance, MyJCS.

psm jcs service -s MyJCS

Service:            MyJCS
Status:             Ready
Version:            12.2.1.2.180823
Edition:            Enterprise Edition

Back Up a Service Instance

Run the add-backup-service command. Provide the name of your service instance, your Oracle Cloud credentials, and your storage REST endpoint.
```
psm jcs add-backup-service -s MyJCS -k BOTH -wc true -g true -t your_cloud_user -o your_cloud_password -d your_storage_REST_endpoint/MyJCSBackup

Command completed with status [SUCCEED].
```
Tip: If you set the wc option to true, the command waits until it completes and a response it sent from the server.

Run the backup command.

psm jcs backup -s MyJCS -o "My Test Backup"

From the command output, identify the job ID. For example:
```
Job ID: 55550002
```
Run the operation-status command and specify the job ID. Periodically run this command until the status of the job is SUCCEED. For example:
```
psm jcs operation-status -j 55550002

Service:           MyJCS
Operation Type:    BACKUP
Status:            SUCCEED
```
Run the view-backups command.
```
psm jcs view-backups -s MyJCS -of json
```

From the command output, locate your new backup. For example:

{
    "backups":[
        {
            "backupId":"11111111-2222-3333-4444-555555555555",
            "jobId":"55550002",
            "backupStartDate":"2018-10-02T20:22:18.837+0000",
            "backupCompleteDate":"2018-10-02T20:24:40.227+0000",
            "expirationDate":"2018-11-01T20:22:18.837+0000",
            ...
            "notes":"My Test Backup"
        }
    ]
}

Scale Out a Service Instance

Download scale-out.json to your computer, and then open it in a text editor. No changes are necessary.
Tip: For descriptions of all available payload attributes, see Scale Out a Service Instance REST API for Oracle Java Cloud Service.
Run the scale-out command on your service instance, MyJCS. Provide the location of scale-out.json.
```
psm jcs scale-out -s MyJCS -c scale-out.json
```
From the command output, identify the job ID. For example:
```
Job ID: 55550003
```
Run the operation-status command and specify the job ID. Periodically run this command until the status of the job is SUCCEED. For example:
```
psm jcs operation-status -j 55550003

Service:           MyJCS
Operation Type:    SCALE_OUT
Status:            SUCCEED
```
Run the service command.
```
psm jcs service -s MyJCS -of json
```

From the command output, verify that there are now two nodes in the service instance.

...
"vmInstances":{
    "myjcs-wls-2":{
        ...
    },
    "myjcs-wls-1":{
        ...
    }
}