OCI Java SDK Gradle Plugin

1. Introduction

A Gradle plugin for the Oracle Cloud Infrastructure Java SDK.

Currently supported OCI Java SDK version is 3.0.1.

For the time being, this plugin provides the minimum capabilities to setup instances. In the future this plugin may provide access to all services exposed by the OCI Java SDK.

This plugin is not endorsed by Oracle nor does the company provide any support for it.

2. Usage

There are two choices for applying the plugin described in this document

Option #1

buildscript {
    repositories {
        jcenter()
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:oci-gradle-plugin:0.9.0'
    }
}
apply plugin: 'org.kordamp.gradle.oci'

Option #2

plugins {
    id 'org.kordamp.gradle.oci' version '0.9.0'
}

2.1. Requirements

Java 8 and Gradle 5 are the minimum requirements to use this plugin.

2.1.1. Example

Provisioning an Instance with brand new Vcn, Subnets, InternetGateway, and InstanceConsoleConnection, making sure that OpenJDK is installed and port 8080 is open

gradle setupInstance \
  --compartment-id=ocid1.compartment.oc1... \
  --verbose \
  --instance-name=myInstance \
  --image=Oracle-Linux-7.6-2019.04.18-0 \
  --shape=VM.Standard2.1 \
  --public-key-file=/home/myuser/.oci/oci-key.pub \
  --user-data-file=/home/myuser/oci/cloud-init.sh

cloud-init.sh

#!/bin/bash

cp /etc/motd /etc/motd.bkp
cat << EOF > /etc/motd
I have been modified by cloud-init at $(date)
EOF

# install Java
yum install -y yum java-1.8.0-openjdk

# amend firewall rules to allow port 4567
function conf-firewalld() {
    setenforce 0
    firewall-cmd --permanent --permanent --zone=public --add-port=4567/tcp
    systemctl restart firewalld
    setenforce 1
}

conf-firewalld

2.2. Configuration

You can configure tasks in two ways:

Using the standard ~/.oci/config file.
Defining an ociConfig block on a task.

2.2.1. Standard Config File

The format of the configuration file is specified at this page, it looks something similar to

[DEFAULT]
user=ocid1.user.oc1...
tenancy=ocid1.tenancy.oc1...
region=eu-frankfurt-1
key_file=~/.oci/oci_api_key.pem
pass_phrase=<secret>
fingerprint=f9:14:d0:...

2.2.2. OciConfig Extension Block

Alternatively you may define an ociConfig block in a task. This block defines properties that match settings found on the config file

build.gradle

listInstances {
    ociConfig {
        userId.set('ocid1.user.oc1...')
        tenantId.set('ocid1.tenancy.oc1...')
        region.set('eu-frankfurt-1')
        keyfile.set(~'/.oci/oci_api_key.pem')
        passphrase.set('<secret>')
        fingerprint.set('f9:14:d0:...')
    }
}

2.3. Tasks

Invoke gradle help --task <taskname> to learn more about the properties that can be set for a particular task. All tasks share the following properties

Property	Type	Option	System	Environment	Default
profile	String	oci-profile	oci.profile	OCI_PROFILE	DEFAULT
region	String	region	oci.region	OCI_REGION
showSecrets	boolean	show-secrets			false
displayStreamLogs	boolean	display-stream-logs	oci.display.stream.logs	OCI_DISPLAY_STREAM_LOGS	false

Property

Type

Option

System

Environment

Default

Required

profile

String

oci-profile

oci.profile

OCI_PROFILE

DEFAULT

region

String

region

oci.region

OCI_REGION

showSecrets

boolean

show-secrets

false

displayStreamLogs

boolean

display-stream-logs

oci.display.stream.logs

OCI_DISPLAY_STREAM_LOGS

false

Where each column defines

Property	The name of the task property.
Type	The type of the property.
Option	The command line flag to set this property’s value. Use `--` as prefix, i.e, `--oci-profile=mine`.
System	The system property to set this property’s value. Use `-D` as prefix, i.e, `-Doci.profile=mine`
Environment	The environment key to set this property’s value. Set as key/value in command shell, i.e, `export OCI_PROFILE=mine`.
Default	Default value for this property (if any).
Required	Whether this property is required or not.

Property values are resolved in the following order

Environment > System Property > Option > Property

Task paths may be used as prefix for Environment and System properties such that, for a task named step01 on a subproject named project1 you get the following Environment and System keys for the profile property

PROJECT1_STEP01_OCI_PROFILE
project1.step01.oci.profile
PROJECT1_OCI_PROFILE
project1.oci.profile
OCI_PROFILE
oci.profile

Whitespace and hyphen (-) characters will be replaced with underscore (_).

2.3.1. OCI Create

createBucket	Creates a Bucket.
createCompartment	Creates a Compartment.
createInstanceConsoleConnection	Creates an InstanceConsoleConnection.
createInstance	Creates an Instance.
createInternetGateway	Creates a InternetGateway.
createSubnet	Creates a Subnet.
createVcn	Creates a Vcn.

Table 1. createBucket
Property	Type	Option	System	Environment	Default
compartmentId	String	compartment-id	oci.compartment.id	OCI_COMPARTMENT_ID
bucketName	String	bucket-name	oci.bucket.name	OCI_BUCKET_NAME
namespaceName	String	namespace-name	oci.namespace.name	OCI_NAMESPACE_NAME
verbose	boolean	verbose	oci.verbose	OCI_VERBOSE	false

Property	Type	Option	System	Environment	Default
compartmentDescription	String	compartment-description	oci.compartment.description	OCI_COMPARTMENT_DESCRIPTION
compartmentId	String	compartment-id	oci.compartment.id	OCI_COMPARTMENT_ID
compartmentName	String	compartment-name	oci.compartment.name	OCI_COMPARTMENT_NAME
verbose	boolean	verbose	oci.verbose	OCI_VERBOSE	false
waitForCompletion	boolean	wait-for-completion	oci.wait.for.completion	OCI_WAIT_FOR_COMPLETION	false

Property	Type	Option	System	Environment	Default
internetGatewayName	String	internet-gateway-name	oci.internet.gateway.name	OCI_INTERNET_GATEWAY_NAME
verbose	boolean	verbose	oci.verbose	OCI_VERBOSE	false
waitForCompletion	boolean	wait-for-completion	oci.wait.for.completion	OCI_WAIT_FOR_COMPLETION	false

Property	Type	Option	System	Environment	Default
availabilityDomain	String	availability-domain	oci.availability.domain	OCI_AVAILABILITY_DOMAIN
compartmentId	String	compartment-id	oci.compartment.id	OCI_COMPARTMENT_ID
dnsLabel	String	dns-label	oci.dns.label	OCI_DNS_LABEL
subnetName	String	subnet-name	oci.subnet.name	OCI_SUBNET_NAME
vcnId	String	vcn-id	oci.vcn.id	OCI_VCN_ID
verbose	boolean	verbose	oci.verbose	OCI_VERBOSE	false
waitForCompletion	boolean	wait-for-completion	oci.wait.for.completion	OCI_WAIT_FOR_COMPLETION	false

deleteBucket	Deletes a Bucket.
deleteCompartment	Deletes a Compartment.
deleteInstanceConsoleConnection	Deletes an InstanceConsoleConnection.
deleteInternetGateway	Deletes a InternetGateway.
deleteObject	Deletes an Object.
deleteSubnet	Deletes a Subnet.
deleteVcn	Deletes a Vcn.

Property	Type	Option	System	Environment	Default	Required
instanceConsoleConnectionId	String	instance-console-connection-id	oci.instance.console.connection.id	OCI_INSTANCE_CONSOLE_CONNECTION_ID
waitForCompletion	boolean	wait-for-completion	oci.wait.for.completion	OCI_WAIT_FOR_COMPLETION	false

getBucket	Displays information for a specific Bucket.
getCompartment	Displays information for a specific Compartment.
getInstanceConsoleConnection	Displays information for a specific InstanceConsoleConnection.
getInstancePublicIp	Displays public Ip addresses for a particular Instance.
getInstance	Displays information for a specific Instance.
getInternetGateway	Displays information for a specific InternetGateway.
getNamespace	Displays information for a specific Namespace.
getObject	Displays information for a specific Object.
getRouteTable	Displays information for a specific RouteTable.
getSecurityList	Displays information for a specific SecurityList.
getSubnet	Displays information for a specific Subnet.
getVcn	Displays information for a specific Vcn.

addIngressSecurityRule	Adds IngressSecurityRules to a SecurityList.
instanceAction	Performs a given action on an Instance.
setupInstance	Setups an Instance with Vcn, InternetGateway, Subnets, InstanceConsoleConnection, and Volume.
terminateInstance	Terminates an Instance.

Property	Type	Option	System	Environment	Default
sourcePort	int	source-port
destinationPort	int	destination-port
portType	String	port-type	oci.port.type	OCI_PORT_TYPE	TCP
securityListId	String	security-list-id	oci.security.list.id	OCI_SECURITY_LIST_ID

Property	Type	Option	System	Environment	Default	Required
action	String	action	oci.action	OCI_ACTION	STOP
compartmentId	String	compartment-id	oci.compartment.id	OCI_COMPARTMENT_ID
instanceId	String	instance-id	oci.instance.id	OCI_INSTANCE_ID		*
instanceName	String	instance-name	oci.instance.name	OCI_INSTANCE_NAME		*
waitForCompletion	boolean	wait-for-completion	oci.wait.for.completion	OCI_WAIT_FOR_COMPLETION	false

listAvailabilityDomains	Lists AvailabilityDomains available on a Compartment.
listBuckets	Lists available Buckets.
listCompartments	Lists available Compartments.
listImages	Lists Images available on a Compartment.
listInstanceConsoleConnections	Lists available InstanceConsoleConnection on an Instance.
listInstances	Lists available Instances.
listInternetGateways	Lists InternetGateways available on a Vcn.
listObjects	Lists available Objects in a Bucket.
listRegions	Lists available Regions.
listRouteTables	Lists RouteTables available on a Vcn.
listSecurityLists	Lists SecurityLists available on a Vcn.
listShapes	Lists Shapes available on a Compartment.
listSubnets	Lists Subnets available on a Vcn.
listUsers	Lists available Users.
listVcns	Lists Vcns available on a Compartment.

clearBucket	Clears a Bucket.
copyObject	Copies an Object.
downloadObject	Downloads an Object to a specific location.
headBucket	Heads a specific Bucket.
headObject	Heads a specific Object.
putObject	Puts an Object on a Bucket.

OCI Java SDK Gradle Plugin

1. Introduction

2. Usage

2.1. Requirements

2.1.1. Example

2.2. Configuration

2.2.1. Standard Config File

2.2.2. OciConfig Extension Block

2.3. Tasks

2.3.1. OCI Create

2.3.2. OCI Delete

2.3.3. OCI Get

2.3.4. OCI Instance

2.3.5. OCI List

2.3.6. OCI Object

2.3.7. OCI Query

3. Links