Note:
- This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
- It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.
Configure CD3 with Jenkins to Create and Export Oracle Cloud Infrastructure Resources
Introduction
The Cloud Deployment Design Deliverable (CD3) automation toolkit enables you to effortlessly build, export and manage Oracle Cloud Infrastructure (OCI) resources by easily converting Microsoft Excel templates to fully functional Terraform modules.
The toolkit also supports seamless resource management using the OCI DevOps Git service and Jenkins pipelines.
Objectives
- Launch the CD3 container with a single click and then create, export OCI identity, network, and compute resources using Jenkins pipelines.
Prerequisites
-
Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) policy to allow user or Instance principal to manage the services that are required to be created or exported using the toolkit.
-
The user deploying the stack should have access to launch OCI Resource Manager stack, Compute instance and Network resources.
Task 1: Set up the Toolkit Container
-
Click Deploy to Oracle Cloud to launch the OCI Resource Manager stack that creates the CD3 WorkVM.
-
Accept the terms and conditions. Enter the network, compartment, VM name, shape and so on, for the workVM to be created.
Note: To maintain a secure environment, provide a specific source CIDR range to access the VM. Do not use
0.0.0.0/0
. -
Check the Run Apply section at the bottom and click Create.
-
After the apply job is successful, click the job and scroll down to the end of logs.
Find the details for the created VM and commands to be executed to log in to the toolkit container. Sample output shown in the following image.
After logging into the container, connect it to the OCI tenancy to execute the OCI APIs.
Task 2: Connect the Container to OCI Tenancy
-
Navigate to
cd /cd3user/oci_tools/cd3_automation_toolkit/user-scripts/
and open thetenancyconfig.properties
file . -
Add the required configuration values in the Required parameters and Auth Details Parameters sections.
Note: In this tutorial, we will use API key authentication. Keep the
auth_mechanism
to its default value. -
In OCI Console, under User settings, upload public key to APIkeys. Place the private key inside the container. Copy the required config values and paste under the corresponding parameters in the
tenancyconfig.properties
file. -
Leave the
outdir_structure_file
parameter to its default value to group the generatedauto.tfvars
files for each service. -
For IaC tool, terraform or tofu can be selected. Default is terraform. To use OpenTofu, specify tofu.
-
Under Advanced Parameters for DevOps, select
yes
for theuse_oci_devops_git
parameter.This will create an OCI DevOps Git Repository for the generated terraform files, OCI Object Storage bucket for the state file and an OCI Notification topic to notify for the changes in DevOps repo.
-
Save the file and execute
createTenancyConfig.py
to initialize the environment and start using CD3.python createTenancyConfig.py tenancyconfig.properties
-
Verify the output.
-
Next, to create resources in OCI, follow Task 3 or to export resources, follow Task 4.
Task 3: Create Resources in OCI
Task 3.1: Prepare Excel and Variables File
-
Download the prefilled excel template from here: cd3quickstart.xlsx for this tutorial. Modify region, compartment values based on your environment and switch to the container.
-
Open
/cd3user/tenancies/<prefix>/terraform_files/<region>/compute/variables_<region>.tf
from the container. Underinstance_ssh_keys
variable, add the variable name for SSH keys specified in excel sheet: ssh_public_key with its corresponding value (key content). -
Under
instance_source_ocids
variable, include the variable name specified in the excel sheet for the source imagemyimageocid
and assign its OCID as the corresponding value. The following screenshots are for reference. -
Run the following commands in sequence to sync the above local changes with the DevOps Git repo.
cd /cd3user/tenancies/<prefix>/terraform_files git status git add -A . git commit -m "msg" git push
Task 3.2: Log in to Jenkins and Execute setupoci Pipeline
-
Start Jenkins and access it using the following commands from the container.
-
To start Jenkins, use the
/usr/share/jenkins/jenkins.sh &
command. -
To access Jenkins, use this url
https://<IP Address of the machine hosting docker container>:8443
.
-
-
Log in to Jenkins. On the dashboard, folders with
<prefix>
names are present. Click the<prefix>
name you are working with. It has the corresponding setupoci pipeline andterraform_files
folder. Click setupoci pipeline and Build with Parameters.Note: If accessing the Jenkins URL for the first time, set up log in credentials.
-
Under the Excel template section, upload the excel file fetched in Task 3.1.
-
Under Workflow, select Create New Resources in OCI (Greenfield Workflow).
-
Under MainOptions, select Identity, Network and Compute.
-
Under SubOptions, select Add/Modify/Delete Groups, Add/Modify/Delete Policies, Create Network, Add/Modify/Delete Instances/Boot Backup Policy.
-
Click Build. The setupoci pipeline stages are executed in order.
Task 3.3: Provide Approval for Each Service Plan
-
Click on the identity stage for logs and click on the link to identity apply pipeline build. Under Get Approval stage, click logs and select Proceed. Check the logs under Apply stage to verify the created identity resources.
-
Similarly, from the network stage in setupoci pipeline, click logs and then the link for network apply pipeline build. Under Get Approval stage, click logs and select Proceed. Check the logs under Apply stage to verify the created network resources.
-
Click the compute stage logs. Click the link to compute apply pipeline build.
Note: You would notice that the compute terraform pipeline failed. This is because the compute resources depend on the network to be ready. To resolve this, trigger the compute terraform pipeline manually after the network apply pipeline is successful. The next step shows how to execute this.
-
Click Build Now for the compute apply pipeline. After the pipeline stages start executing, under Get Approval stage, click logs and select Proceed. Check the logs under Apply stage to verify the created compute resources.
-
Executing Create Network creates few rules in the VCN which are not present in the CD3 Excel sheet yet (as these details are initially taken from Subnets tab). To sync them to the Excel file, build setupoci Pipeline again using the same Excel sheet as above, set workflow as Create Resources in OCI, select Network under main options and then the below sub-options.
Security Rules ---> Export Security Rules (From OCI into SecRulesinOCI sheet), Add/Modify/Delete Security Rules (Reads SecRulesinOCI sheet) Route Rules ---> Export Route Rules (From OCI into RouteRulesinOCI sheet), Add/Modify/Delete Route Rules (Reads RouteRulesinOCI sheet) DRG Route Rules ---> Export DRG Route Rules (From OCI into DRGRouteRulesinOCI sheet), Add/Modify/Delete DRG Route Rules (Reads DRGRouteRulesinOCI sheet)
-
Specify the Compartment name. Click on Build and the setupoci Pipeline stages start executing.
-
The Excel sheet will be populated with Security Rules, Route Rules, DRG Route Rules data. Terraform
tfvars
files are generated for these services. -
The updated Excel file containing exported data from OCI is present under Build Artifacts of the particular setupoci build. The Excel file is also present inside the container under
/cd3user/tenancies/<prefix>
. -
Click on the Network stage logs and click on the link to Network apply pipeline build. The terraform plan should show No changes inferring these services in OCI and CD3 are in sync.
-
This completes the resource creation process in OCI. Verify the resources that are created on the OCI console.
Task 4: Export Resources from OCI
Task 4.1: Download CD3-Blank-template.xlsx
File
For export workflow, the toolkit overwrites any existing data in the particular service sheet. So it is recommended to use CD3-Blank-template.xlsx
which has no data by default.
Download the CD3 blank template from here: CD3-Blank-template.xlsx.
Task 4.2: Log in to Jenkins
-
Start Jenkins and access it using the following commands from the container.
-
To start Jenkins, use the
/usr/share/jenkins/jenkins.sh &
command. -
To access Jenkins, use this url
https://<IP Address of the machine hosting docker container>:8443
.
-
-
Log in to Jenkins.
Note: If accessing the Jenkins URL for the first time, set up log in credentials.
Task 4.3: Execute setupoci Pipeline
-
On the Jenkins dashboard, folders with
<prefix>
names are present. Click the<prefix>
name you are working with. It has the corresponding setupoci pipeline andterraform_files
folder. Click setupoci pipeline and Build with Parameters. -
Under the Excel template section, upload the Excel file fetched in Task 4.1.
-
Under Workflow, select Export Existing Resources from OCI (Non-Greenfield Workflow).
-
Under MainOptions, select Export Identity, Export Network and Export Compute.
-
Under SubOptions, select Export Compartments/Groups/Policies for identity and Export all Network Components for network and Export Instances (excludes instances launched by OKE) for compute.
Note: Add details under AdditionalFilters if required, to filter resources.
-
Click Build. The setupoci pipeline stages are executed in order for each of the services.
-
Check logs under Run Import Commands stage. If it shows as successful, respective terraform pipelines triggered should have Plan stage show as No Changes.
Note: If you find any changes in the plan, review them and apply as needed.
-
The updated Excel file containing exported data from OCI is present under Build Artifacts of the particular setupoci build. The Excel file is also present inside the container under
/cd3user/tenancies/<prefix>
.
Related Links
Acknowledgments
- Authors - Lasya Vadavalli (Senior Cloud Engineer), Dipesh Kumar Rathod (Master Principal Cloud Architect, Infrastructure)
More Learning Resources
Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.
For product documentation, visit Oracle Help Center.
Configure CD3 with Jenkins to Create and Export Oracle Cloud Infrastructure Resources
F95114-05
October 2024