Note:

Configure CD3 Toolkit with CLI 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 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, Virtual Machine (VM) Name, Shape and other details for the workVM.

    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 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. The following image shows the sample output.

    rmstackoutput

    After logging into the container, follow Task 2 and connect to the OCI tenancy to execute the OCI APIs.

Task 2: Connect the Container to OCI Tenancy

  1. Inside the container, 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. Go to the 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. Keep the default value for the outdir_structure_file parameter. This will group the generated auto.tfvars files for each service under its service specific folder.

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

    tenancyconfig_properties

    Note: Leave the Advanced Parameters for DevOps section as is since Jenkins set up is not in the scope of this tutorial. To run the toolkit using Jenkins, see Configure CD3 with Jenkins to Create and Export Oracle Cloud Infrastructure Resources.

  6. Save the file and run createTenancyConfig.py to initialize the environment and start using CD3.

    python createTenancyConfig.py tenancyconfig.properties

  7. Verify the output.

    tenancyconfig_output

    Next, to create resources in OCI, follow Task 3 and to export resources, follow Task 4.

Task 3: Create Resources

Task 3.1: Prepare Excel and Variables File

  1. Download the prefilled Excel template from here: cd3quickstart.xlsx. Modify the Region and Compartment values in the sheet based on your environment and switch back to the container.

  2. Add the Excel file inside the container at /cd3user/tenancies/cd3_demo_cli/ using below scp command.

    Note: The tenancies folder in the CD3 container is mapped to the /cd3user/mount_path folder in the compute VM. Log in with cd3user to avoid permission issues.

    scp -i ~/.ssh/id_rsa /Users/xyz/cd3quickstart.xlsx cd3user@<workvm_ip>:/cd3user/mount_path/cd3_demo_cli/cd3quickstart.xlsx

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

    ssh_key

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

    sourceocids

Task 3.2: Run the setUpOCI.py Script to Generate Resource Terraform Files

  1. Open the /cd3user/tenancies/cd3_demo_cli/cd3_demo_cli_setUpOCI.properties file and add the CD3 excel file path under the cd3file variable. Set workflow_type variable to create_resources and save the file.

    image

  2. Change the directory to cd /cd3user/oci_tools/cd3_automation_toolkit/ and run the setUpOCI.py script.

    python setUpOCI.py /cd3user/tenancies/cd3_demo_cli/cd3_demo_cli_setUpOCI.properties

    Note: If you are running the script for the first time, select y for the Execute Script to fetch the compartment OCIDs into variables file prompt .

    image

  3. Select the options Network and Compute from the output menu and then select the sub-options: Create Network to create VCN and subnets, Add/Modify/Delete Instances/Boot Backup Policy to provision instances.

  4. Change the directory to /cd3user/tenancies/cd3_demo_cli/terraform_files/<region>/network/. Run Terraform commands to provision the network resources.

    terraform init
terraform plan -out tfplan
terraform apply tfplan

  5. 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 the subnets tab). To sync them to the Excel file, run the setUpOCI script again using the same Excel sheet as above. Ensure workflow is set to Create Resources in the cd3_demo_cli_setUpOCI.properties file. 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. Once successfully done, DRGRouteRulesinOCI, RouteRulesinOCI and SecRulesinOCI sheets in the Excel template will be populated with corresponding data and cd3_demo_cli_seclists.auto.tfvars, cd3_demo_cli_routetables.auto.tfvars and cd3_demo_cli_drg-routetables.auto.tfvars files will be generated under the folder /cd3user/tenancies/cd3_demo_cli/terraform_files/<region_dir>/<service_dir>.

  7. Verify terraform plan and terraform apply. Running terraform apply completes the export of security rules, route rules and DRG route rules from OCI. Now, the terraform state should be in sync with OCI.

  8. To provision compute resources, change the directory to /cd3user/tenancies/cd3_demo_cli/terraform_files/<region>/compute/ and run the Terraform commands.

    terraform init
terraform plan -out tfplan
terraform apply tfplan

    Verify the provisioned resources in the OCI Console.

Task 4: Export Resources

Task 4.1: Add Excel Template to the Container

  1. Download CD3-Blank-template and add it to the container at /cd3user/tenancies/cd3_demo_cli/.

    Note: The tenancies folder in cd3 container is mapped to the /cd3user/mount_path folder in the compute VM. Log in with cd3user to avoid permission issues.

  2. Navigate to the /cd3user/tenancies/cd3_demo_cli/ folder and open the cd3_demo_cli_setUpOCI.properties file.

  3. Add the CD3 Excel file path under the variable cd3file.

  4. Set the workflow_type parameter to export_resources and save the file.

Task 4.2: Run the setUpOCI.py Script

  1. Change the directory to cd /cd3user/oci_tools/cd3_automation_toolkit/ and run the setUpOCI.py script.

    python setUpOCI.py /cd3user/tenancies/cd3_demo_cli/cd3_demo_cli_setUpOCI.properties

    Note: If you are running the script for the first time, select y for the Execute Script to fetch the compartment OCIDs into variables file prompt.

    image

  2. Provide comma separated region values if you have to export resources from multiple regions. If no region value is provided, the toolkit will export resources from all subscribed regions.

  3. Select the resource options to be exported (Network and Compute). You can choose to export the resources only from specific compartments or all compartments. If the compartment name is not unique, it should be specified in the following format based on the hierarchy.

    Parent Compartment::Child Compartment1::Child Compartment2

  4. To export only specific resources, enter the required filter values when prompted.

    Note: For more information on exporting OCI Networking resources and OCI Compute resources, see Export OCI Networking Resources and Export OCI Compute Resources.

  5. After successful completion, the exported resource data is populated in the input Excel file. The updated excel sheet is present under the /cd3user/tenancies/cd3_demo_cli folder inside the container and needs to be copied manually to the local system using scp command.

    scp -i ~/.ssh/id_rsa cd3user@<workvm_ip>:/cd3user/mount_path/cd3_demo_cli/CD3-Blank-template.xlsx /Users/xyz/CD3-export.xlsx

  6. Service specific .tfvars and .sh files with terraform import commands are generated within the respective service folders under the region folder:

    • /cd3user/tenancies/cd3_demo_cli/terraform_files/<region_dir>/network/

    • /cd3user/tenancies/cd3_demo_cli/terraform_files/<region_dir>/compute/

    For OCI Compute, The associated ssh public keys are placed in variables_<region>.tf under the instance_ssh_keys variable and source OCIDs are placed under the instance_source_ocid variable.

Task 4.3: Execute the Generated .sh files

  1. From network and compute service folders, run each of the generated .sh files containing Terraform import commands.

    Note: For OCI Networking, before running the other .sh scripts, ensure to run the .sh script for major_objects: sh import_commands_network_major-objects.sh

  2. After successful completion of the .sh scripts, Terraform state file is generated and terraform plan is updated to the latest.

This generated Terraform code can be used with OCI Resource Manager or leveraged by the organization CI/CD processes for further management.

To add new resources or modify existing ones, export the resources first to CD3, make the required changes in the exported Excel template and then, in the /cd3user/tenancies/cd3_demo_cli/cd3_demo_cli_setUpOCI.properties file, modify the workflow_type to create_resources and execute the toolkit.

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.