OCI Compute Jenkins Plugin

Oracle Cloud Infrastructure Compute Plugin allows users to access and manage cloud resources on the Oracle Cloud Infrastructure (OCI) from Jenkins. A Jenkins master instance with OCI Compute Plugin can spin up OCI Instances (slaves or agents) on demand within OCI, and remove the Instances and free its resources automatically once the Job completes.

NOTE: From v1.0.6, the OCI plugin added support and functionality for OCI Credentials. It is not possible to separate the OCI Credentials functionality to a separate Plugin as it will cause issues with existing OCI Compute plugin installations. If you require OCI Credentials functionality, please install the OCI Compute plugin.

Table of Contents

• Features
• Prerequisites
• Compatibility
• Installation
• Building
• Upgrade
• Configuration
• Contributing
• Security
• License
• Changelog

Features

OCI Compute Plugin provides functionality to dynamically allocate OCI resources for continuous integration tasks, and to bring up and down OCI Instances and resources as required to serve Jenkins Build Jobs.

After installing the Plugin, you can add OCI Clouds and Templates with your required OCI Instance configuration. The Template will have a Label that you can use in your Jenkins Job. Multiple Templates are supported. The Template options include Labels, Domains, Credentials, Shapes, Images, Virtual Cloud Network, Template Instance Cap, etc. After your Jenkins Job completes its work, the OCI Instance is cleanly removed and resources are released back to the OCI pool.

View OCI Compute Plugin page on the plugins.jenkins.io site for more information.

Prerequisites

1. Oracle Cloud Account. To sign up, visit Oracle Cloud.

2. Jenkins installed with JDK 11 or higher.

3. Required Plugins: bouncycastle API, SSH Credentials, Credentials and Jersey2 API

Compatibility

Minimum Jenkins requirement: 2.426.3

Installation

There are a number of ways to install the OCI Compute Plugin.

• Using the Plugin Manager in the web UI.
• Using the Jenkins CLI install-plugin command.
• Copying the .hpi file to the JENKINS_HOME/plugins directory.

Using the Plugin Manager

The simplest and most common way of installing plugins is through the Manage Jenkins > Manage Plugins view, available to Administrators of a Jenkins environment.

To install the Plugin in Jenkins:

1. Click on Manage Jenkins in Home
2. Click Manage Plugins
3. Click Available tab
4. Search for Oracle Cloud Infrastructure Compute Plugin or oracle-cloud-infrastructure-compute
5. Click Install
6. Restart Jenkins

Using the Jenkins CLI

Administrators may also use the Jenkins CLI which provides a command to install plugins.

java -jar jenkins-cli.jar -s http://localhost:8080/ install-plugin SOURCE ... [-deploy] [-name VAL] [-restart]

Installs a plugin either from a file, an URL, or from update center.

 SOURCE    : If this points to a local file, that file will be installed. If
         	 this is an URL, Jenkins downloads the URL and installs that as a
        	 plugin.Otherwise the name is assumed to be the short name of the
             plugin i.e. "oracle-cloud-infrastructure-compute",and the
         	 plugin will be installed from the update center.
 -deploy   : Deploy plugins right away without postponing them until the reboot.
 -name VAL : If specified, the plugin will be installed as this short name
         	 (whereas normally the name is inferred from the source name
         	 automatically).
 -restart  : Restart Jenkins upon successful installation.

Link to latest .hpi version can be found here.

Copying the .hpi file to the plugin directory

Using the .hpi file that has been explicitly downloaded by a systems administrator, the administrator can manually copy the downloaded .hpi file into the JENKINS_HOME/plugins directory on the Jenkins master. Link to latest .hpi version can be found here.

The Jenkins master will need to be restarted before the plugin is loaded and made available in the Jenkins environment.

Building

Jenkins plugins are packaged as self-contained .hpi files, which have all the necessary code, images, and other resources which the plugin needs to operate successfully.

If desired, you can build the OCI Compute Plugin .hpi from the source code, and then install the .hpi file in Jenkins.

To build the .hpi file, OCI Java SDK is required and is available on Maven Central and JCenter.

Refer to OCI Java SDK licensing here.

Compile the Plugin

1. git clone repo

2. If you want to use the latest version of OCI Java SDK, update pom.xml

   <oci-java-sdk.version>2.46.0</oci-java-sdk.version>

3. Compile and Install package:

   $ mvn package

Install the Plugin

A logged-in Jenkins administrator may upload the file from within the web UI.

1. Navigate to the Manage Jenkins > Manage Plugins page in the web UI
2. Click on the Advanced tab
3. Choose the .hpi file under the Upload Plugin section
4. Click Upload

or

The System Administrator can copy the .hpi file into the JENKINS_HOME/plugins directory on the Jenkins master. The master will need to be restarted before the plugin is loaded and made available in the Jenkins environment.

Upgrade

Updates are listed in the Updates tab of the Manage Plugins page and can be installed by checking the checkbox of the OCI Compute plugin updates and clicking the Download now and install after restart button.

Note: Upgrading the Plugin may require you to update your already created OCI Cloud and Templates Configuration. After upgrade please check all OCI Cloud values are OK in Manage Jenkins > Manage Nodes and Clouds > Configure Clouds. Then Click Save.

For example, a new method of adding OCI Credentials was added in v106 of the Plugin. Previously these OCI Credentials were added in the OCI Cloud Configuration. If upgrading from a version earlier than v106, then you may have to update the values in your existing Cloud configuration.

Note: A plugin version with new functionality may only take effect on Slaves built with that new version. You may need to remove older Slaves.

Configuration

Add OCI Credentials

OCI Credentials are required to connect to your OCI. For more information on OCI Credentials and other required keys, please see Security Credentials.

You can add these OCI Credentials by navigating to the Jenkins Server console, Credentials, System, and Add Credentials

or

by navigating to the Jenkins Server console, click Manage Jenkins, then Manage Nodes and Clouds, and Configure Clouds. Click Add a new cloud and select Oracle Cloud Infrastructure Compute. In Credentials, click Add.

Once in the New Credentials Screen, select Oracle Cloud Infrastructure Credentials from the Kind Drop-Down.

• Fingerprint - The Fingerprint for the key pair being used. See How to Get the Key's Fingerprint for additional information.
• API Key - The OCI API Signing Private Key. See How to Generate an API Signing Key for additional information.
• PassPhrase - The PassPhrase for the key pair being used. See How to Generate an API Signing Key for additional information.
• Tenant Id - The Tenant OCID. See Where to Get the Tenancy's OCID and User's OCID for additional information.
• User Id - The OCID of the User whose API signing key you are using. See Where to Get the Tenancy's OCID and User's OCID for additional information.
• Region - The OCI region to use for all OCI API requests for example, us-phoenix-1.
• ID - An internal unique ID by which these credentials are identified from jobs and other configuration.
• Description - An optional description to help tell similar credentials apart.

Separately you can select the Instance Principals option. Using this option you can authorize an instance to make API calls in OCI services. After you set up the required resources and policies in OCI, an application running on an instance can call OCI public services, removing the need to configure user credentials or a configuration file. If using this functionality, then the Jenkins Master is configured to authorize an instance to make API calls in OCI services. By checking this Option, only the Tenant Id and Region Fields are required. See Calling Services from an Instance for additional information.

Click Verify Credentials that you can connect successfully to your OCI.

Using your OCI credentials with the Credential Binding plugin

The OCI config provided for creating instances can also be used as a credential in jenkins pipelines.

pipeline {
   agent {
      label "my-oci-label"
   }

   stages {
      stage("My OCI Test") {
         steps {
            withCredentials([ociCredential(credentialsId: 'MY_OCI_CREDENTIAL')]) {
               sh 'oci iam compartment list'
            }
         }
      }
   }
}

Add OCI Cloud

1. In Jenkins, click Manage Jenkins > Manage Nodes and Clouds > Configure Clouds.
2. Click Add a new cloud and select Oracle Cloud Infrastructure Compute
3. Enter credentials to access your OCI account. You can create multiple Clouds.
   • Name - A name for this OCI Compute Cloud.
   • Credentials - The OCI credentials required to connect to your OCI. If you want to add an OCI Credential click Add. See the previous Add OCI Credentials section for more information.
4. Click Advanced for more options.
   • Instance Cap - A number to limit the maximum number of instances that can be created for this Cloud configuration. Leave this field empty to have no cap.
   • Max number of async threads - The max number of async threads to use to load the Templates configuration. Consider reducing this value for Cloud configurations with a large number of Templates and if some values fail to load due to OCI API limit being exceeded. In this case the logs will show "User-rate limit exceeded" errors.

Add OCI Template

1. Click Add in Instance Templates section to add the OCI configuration. You can add multiple Templates to a Cloud configuration.

2. Input or select values in the Instance Template section:

   • Description - Provide a description for this Template.
   • Usage - It's recommended that you select "Only build jobs with label expressions matching this node" for now.
   • Labels - Enter a unique identifier which allows Jenkins to pick the right instance template to run Job.
   • Compartment - The compartment from which the new Instance is launched.
   • Availability Domain - The Availability Domain for your instance.
   • Image Compartment - The compartment from which to select the Instance's image.
   • Image - Select the Image the instance will use. Note: Java should be installed on the image as a Jenkins requirement. Alternatively refer to Init Script in Advanced section below to install Java on the newly launched Linux instances. Note: Windows images also need to be preconfigured and to be able to authenticate with SSH.
   • Shape - The Shape for your instance.
   • Number of OCPUs - You can customize the number of OCPUs that are allocated to a flexible shape. This field only takes effect if you select a flexible shape. For more information, see Compute Shapes.
   • Memory in GBs - You can customize the amount of memory that is allocated to a flexible shape. This field only takes effect if you select a flexible shape. For more information, see Compute Shapes.
   • Virtual Cloud Network Compartment - The compartment from which to select the Virtual Cloud Network.
   • Virtual Cloud Network - The Virtual Cloud Network for your instance.
   • Subnet Compartment - The compartment from which to select the Network's Subnet.
   • Subnet - Subnet of your Virtual Cloud Network.
   • Network Security Groups - Click Add to select Network Security Groups. For more information, see Network Security Groups.
   • Assign Public IP Address - The Plugin will assign a public IP to an instance, provided the subnet has an available public IP range. If this Option is unchecked, only the private IP is assigned.
   • Connect Agent using Public IP - The Plugin will connect to the public IP of the instance. If this Option is unchecked, the Plugin will connect to the private IP of the instance.
   • SSH credentials - The Private SSH Key in PEM format for accessing the OCI instance. For more information, see Credentials.

3. Click Advanced for more options:

   • Remote FS root - Dedicated directory for Jenkins agent in instance.
   • Instance Creation Timeout - Number of seconds to wait for instance to reach state Running.
   • Employ knownHost verification strategy - Check this option to employ knownHost verification strategy. By default, this strategy adds a new host entry to a file which is used for ssh connection verification to the hosts.
   • Instance SSH Connection Timeout - Number of seconds to wait for instance from state Running to be able to ssh connect from Jenkins master.
   • Idle Termination Minutes - Number of minutes for Jenkins to wait before deleting and completely removing an idle instance. A value of 0 (or an empty string) indicates that instance will never be stopped/deleted.
   • Number of Executors - Number of concurrent builds that Jenkins can perform. Value should be at least 1.
   • JenkinsAgentUser - The custom user to start the Jenkins agent process. This user must be baked into the OS image you select or created through an init script. To use this feature, the ssh user should have sudo privileges.
   • Custom Java Path - Provide a custom java path if you wish to not use the java present in the current user's path to launch agent.jar. Make sure the current user has permission on that java bin directory. Example: /home/opc/installs/jdk-11.0.9/bin/ with the given user having permission on this directory.
   • Override JVM Options - Provide JVM Options string to override the defaults. Eg: To increase heap size, provide this: -Xms256m -Xmx512m -Djava.awt.headless=true
   • Init Script - You can define several lines of shell based commands to configure the instance (one-time) before it comes online. For example, if the image selected does not have Java pre-installed, you can add command "sudo yum -y install java". This functionality works for Linux instances only.
   • Init Script Timeout - Number of seconds to wait for the completion of Init Script.
   • Template Instance Cap - Places a limit on the number of OCI Instances that Jenkins may launch from this Template. Leave this field empty to remove the Template Instance Cap.
   • Identical Named Images - Check this Box if you want to automatically select the newest Image if multiple Images exist with same name.
   • Stop on Idle Timeout - If this is checked, the Instance is stopped when the Idle timeout expires. If the Instance is required again, then the plugin will look for a stopped Instance that exactly matches the OCI Template specification and resume it if found.
   • Tags - Click Add Button to add Tagging to your Instance. See the Tagging Overview documentation for additional information.
   • Instance Name Prefix - Using this option, you can add additional naming to the Instance in OCI. Default name is "jenkins-{IP_Address}-{OCID}", using this option it would be "jenkins-{Instance_Name_Prefix}-{IP_Address}-{OCID}".
   • Do Not Disable - If this is checked, then the template will not be disabled upon any kind of failure. The job tied to this template will remain to stay in the queue until there is a resource available (or) the issue is manually resolved. The template will be retried after a configured time. Make sure you understand the effects of this option and configure the retry time accordingly.
   • Retry Timeout Mins - Number of minutes after which the provisioning of an instance shall be attempted using this template. Applicable only when the do not disable option is checked. (Provided that there is existing workload after the waiting period.)

4. Click Save or Apply

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Security

Please consult the security guide for our responsible security vulnerability disclosure process

License

Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.

This Plugin is licensed under the Universal Permissive License 1.0

This software is dual-licensed to you under the Universal Permissive License (UPL) and Apache License 2.0.

See LICENSE.txt for more details.

Changelog

For CHANGELOG please refer to CHANGELOG.md.