Note:

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.

workflow

Objectives

Prerequisites

Task 1: Set up the Toolkit Container

  1. Click Deploy to Oracle Cloud to launch the OCI Resource Manager stack that creates the CD3 WorkVM.

    Deploy_To_OCI

  2. 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.

  3. Check the Run Apply section at the bottom and click Create.

  4. 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.

    rmstackoutput

    After logging into the container, connect it to the OCI tenancy to execute the OCI APIs.

Task 2: Connect the Container to OCI Tenancy

  1. Navigate to cd /cd3user/oci_tools/cd3_automation_toolkit/user-scripts/ and open the tenancyconfig.properties file .

  2. 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.

  3. 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.

  4. Leave the outdir_structure_file parameter to its default value to group the generated auto.tfvars files for each service.

  5. For IaC tool, terraform or tofu can be selected. Default is terraform. To use OpenTofu, specify tofu.

  6. Under Advanced Parameters for DevOps, select yes for the use_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.

  7. Save the file and execute createTenancyConfig.py to initialize the environment and start using CD3.

    python createTenancyConfig.py tenancyconfig.properties

  8. Verify the output.

  9. 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

  1. 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.

  2. Open /cd3user/tenancies/<prefix>/terraform_files/<region>/compute/variables_<region>.tf from the container. Under instance_ssh_keys variable, add the variable name for SSH keys specified in excel sheet: ssh_public_key with its corresponding value (key content).

  3. Under instance_source_ocids variable, include the variable name specified in the excel sheet for the source image myimageocid and assign its OCID as the corresponding value. The following screenshots are for reference.

    ssh_key

    sourceocids

  4. 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

  1. 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.

  2. 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 and terraform_files folder. Click setupoci pipeline and Build with Parameters.

    Note: If accessing the Jenkins URL for the first time, set up log in credentials.

    excel_template

  3. Under the Excel template section, upload the excel file fetched in Task 3.1.

    excel_template

  4. Under Workflow, select Create New Resources in OCI (Greenfield Workflow).

  5. Under MainOptions, select Identity, Network and Compute.

  6. Under SubOptions, select Add/Modify/Delete Groups, Add/Modify/Delete Policies, Create Network, Add/Modify/Delete Instances/Boot Backup Policy.

  7. Click Build. The setupoci pipeline stages are executed in order.

Task 3.3: Provide Approval for Each Service Plan

  1. 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.

    terraformpipeline

  2. 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.

  3. 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.

  4. 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.

  5. 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)

  6. Specify the Compartment name. Click on Build and the setupoci Pipeline stages start executing.

  7. The Excel sheet will be populated with Security Rules, Route Rules, DRG Route Rules data. Terraform tfvars files are generated for these services.

  8. 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>.

  9. 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.

  10. 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

  1. Start Jenkins and access it using the following commands from the container.

    1. To start Jenkins, use the /usr/share/jenkins/jenkins.sh & command.

    2. To access Jenkins, use this url https://<IP Address of the machine hosting docker container>:8443.

  2. Log in to Jenkins.

    Note: If accessing the Jenkins URL for the first time, set up log in credentials.

    excel_template

Task 4.3: Execute setupoci Pipeline

  1. On the Jenkins dashboard, folders with <prefix> names are present. Click the <prefix> name you are working with. It has the corresponding setupoci pipeline and terraform_files folder. Click setupoci pipeline and Build with Parameters.

  2. Under the Excel template section, upload the Excel file fetched in Task 4.1.

  3. Under Workflow, select Export Existing Resources from OCI (Non-Greenfield Workflow).

  4. Under MainOptions, select Export Identity, Export Network and Export Compute.

  5. 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.

  6. Click Build. The setupoci pipeline stages are executed in order for each of the services.

    excel_template

  7. 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.

  8. 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>.

Acknowledgments

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.