While infrastructure configuration management tools have been around since the 1970s, the rise in popularity of DevOps and cloud computing brought a new perspective to how we can all provision and maintain infrastructure using our favorite programming language. In this post I will disclose how I build Oracle Cloud Infrastructure (OCI) Instances with Java and Oracle Cloud Infrastructure (OCI) provider for Pulumi.
WARNING: At the time of writing this article, Pulumi Java support is in public preview.
Goals and Prerequisites
Before going into action, let's discuss what we want to achieve:
Have a Java project running on the latest JDK release (at the moment I am writing this is 21) that builds one or more OCI instances.
As environment parameters can vary, would be great to maintain them in one or more .properties or .yaml configuration files.
There are several SDKs in the market that support building OCI components with Java, including an Oracle Cloud Infrastructure SDK for Java, but I have seen a few presentations about Pulumi at several conferences in 2023, so I thought to give it a try.
Here is the full lists of ingredients for the project:
An Integrated Development Environment (IDE) of your choice, preferably one that has a Terminal integrated.
Once you have those installed, you can proceed with initializing and customizing your project.
Initialize and Polish Your Maven Project
Every Pulumi project is deployed to a stack, meaning as an isolated and independently configurable instance. Each stack has its own state, and Pulumi uses it to know when and how to change cloud resources. Let's create a home directory where you will store a state file and your stack source code, for example by running the following command in a terminal window:
mkdir oci-vm-providerIn order to track changes on your infrastructure, Pulumi stores the state of your Stack in Pulumi Service or in a local state file. In this article, the state is stored it in a local state file by running the following commands:
mkdir pulumi-state-local
pulumi login file://pulumi-state-localNow we can generate a new Java project that uses maven by running:
pulumi new java --forceKeep the defaults suggested by the tool and you will obtain a maven Java project running with minimum Java 11. In order for the project to use the OCI provider for Pulumi, add also the dependency:
<dependency>
<groupId>com.pulumi</groupId>
<artifactId>oci</artifactId>
<version>${oci.version}</version>
</dependency>If you want to run your project with Java 21+, you must change the maven-compiler-plugin setup and add an extra configuration in order to try some preview features too:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<compilerArgs>--enable-preview</compilerArgs>
</configuration>
</plugin>Pulumi stores the name, runtime and project description in the Pulumi.yaml file. The file named Pulumi.<stack-name>.yaml contains key-value pairs for credentials and other specific configurations (like amount of instances to create):
config:
oci-vm-provider:amount_vm: 1
oci-vm-provider:compartment_ocid: your-parent-compartment
oci-vm-provider:operating_system: Oracle Linux
oci-vm-provider:operating_system_version: "9"
oci-vm-provider:routetable_displayname: demo_routetable
oci-vm-provider:subnet_cidr: 10.0.0.0/28
oci-vm-provider:subnet_displayname: demo_subnet
oci-vm-provider:subnet_dns_label: demoendpoints
oci-vm-provider:internetgateway_name: demo_internetgateway
oci-vm-provider:ssh_authorized_keys: your-ssh-key
oci-vm-provider:ssh_private_key_file: your-private-key-file
oci-vm-provider:vcn_cidr_block: 10.0.0.0/16
oci-vm-provider:vcn_display_name: demo_vcn
oci-vm-provider:vcn_dns_label: demodnsSome of those details, such as oci-vm-provider:ssh_authorized_keys, require for you to modify them. You can do that one by one by running :
pulumi config set ssh_private_key_file your-ssh-keyor you can run the setup.sh script provided in the repository. The script will ask you for several credentials details which you can find by going to the Oracle Cloud Console user interface and clicking the Profile menu and selecting your user (usually your email address). In your profile you have an area named Capabilities, containing a link to a configuration file.
Click the link and copy the following values into the setup.sh prompt:
tenancy to fulfill your tenancy OCID.
user for your userOcid
fingerprint to fill in your oci fingerprint
privateKey associated with the fingerprint
region where you wish to provision the infrastructure
To make sure that the project is correct from infrastructure and Java point of view, you can run:
pulumi previewThe generated project contains a Java class with the following content:
In the main method, you can call Pulumi.run and pass it a method that will construct the resources you wish to deploy:
You can use the values from Pulumi.<stack-name>.yaml via the config variable.Yet, there are a few infrastructure components that require to be built and placing all together in the same method would create a cluttered entrypoint. So let's see how we can elegantly split the responsibilities.
Processing Configurations with Records and Sealed Classes
The SDK provides classes to access or create infrastructure resources independently. Yet,
as this Java project creates a piece of infrastructure putting together all these independent parts, it is better to describe those with language constructs that will help to this purpose:
To build an OCI Compute Instance you need the following immediate components:
An availability domain which consists of a set of data centers within an Oracle Cloud Infrastructure region where your compartment and future instance reside;
A compute shape which is a template that determines the number of OCPUs , amount of memory, and other resources that are allocated to that instance;
A platform image that determines the operating system and other software for that instance;
An available Subnet in your compartment.
These components are related to the structure of the Instance, hence you can choose to represent their class hierarchy as allowed heirs of InstanceStructure sealed interface:
To find existing compute shapes in OCI you need an availability domain, so you can model the two components as nested record patterns:
Similarly, you should determine a suitable platform image for that compute shape, so PlatformImage is also a record containing a ComputeShape field:
The project can build a subnet in the given compartment. A subnet is a logical part of a Virtual Cloud Network (VCN) that requires a few components as well:
A Virtual Cloud Network (VCN) described by the definition of the VirtualNetwork record.
Your VCN will need access the internet and the NetworkGateway record describes that resource.
The subnet needs rules for to and from internet access and the RouterTable record has a NetworkGateway field to represent that.
The subnet itself is described by Subnetwork record that contains a RouterTable field:
These records belong of SubnetStructure hierarchy as you need them to build a subnet:
Now that you caught a glimpse to the class hierarchy, let's look at the operations required to work with these records.
Building Infrastructure with Pattern Matching
As availability domains, compute shapes and platform images are part of the built-in Oracle Cloud Infrastructure, one would need just to find them. In consequence, you can use pattern matching for switch to find any of these InstanceStructure records:
Similarly, building the instance structure is done via a pattern matching for switch on each SubnetStructure type:
You can find the entire code of the project and instructions on how to run it by going to its Github repository: https://github.com/ammbra/oci-vm-provider/.
Replicate Project Setup for Many Environments
To run the existing project, you just simply have to run the following command in the terminal window:
pulumi upIf you want to deploy to another environment, easily create a new stack by running:
pulumi stackThe above command will end up creating a new Pulumi.<stack_name>.yaml where you can store new cloud credentials, such as a new compartment id where you need to create compute instances. When you no longer need the resources within a specific stack, you can run:
pulumi destroyThoughts to ponder
While this project is easy to run from your computer, managing certificates and other secrets from your local can become a tedious operation on the long term. One possible way to evolve the current setup is to have Github workflows that execute all the command line steps provided in this article. Yet, if you search for a one time spin of resources and enjoy coding with Java, give this tutorial a try. Have fun 😉!