Skip to content

Connect CD3 Container to OCI Tenancy

Note

  • When a new region is subscribed to the tenancy, rerun createTenancyConfig.py by using the same tenancyconfig.properties file that was originally used. It will create new directory for the new region under /cd3user/tenancies/<prefix>/terraform_files without touching the existing ones and will commit the latest terraform_files folder to DevOps GIT repo.

Step 1 - Login (Exec) into the Container:

Step 2 - Choose Authentication Mechanism for OCI SDK

  • Click here to configure any one of the available authentication mechanisms.

  • Make sure to assign required OCI Tenancy Access to user/instance as defined in Prerequisites.

Step 3 - Edit tenancyconfig.properties:

  • Run 

    cd /cd3user/oci_tools/cd3_automation_toolkit/user-scripts/

  • Fill the input parameters in tenancyconfig.properties file.

tenancyconfig.properties

Parameter Description
Parameter Description Example
prefix Friendly name for the Customer Tenancy demo
tenancy_ocid OCID of the tenancy ocid1.tenancy.oc1..aaaaaa...5t
region OCI Region identifier us-phoenix-1
auth_mechanism Auth Mechanism for OCI APIs api_key, instance_principal, session_token
user_ocid Required only if ${auth_mechanism} is selected as api_key. Leave empty if 'instance_principal' or 'session_token' is used ocid1.user.oc1..aaaaa...6a
key_path Required only if ${auth_mechanism} is selected as api_key. Leave empty if 'instance_principal' or 'session_token' is used. Path of API Private Key (PEM Key) File Defaults to /cd3user/tenancies/keys/oci_api_private.pem when left empty
fingerprint Required only if ${auth_mechanism} is selected as api_key. Leave empty if 'instance_principal' or 'session_token' is used 9f:20:0b:....:8c
outdir_structure_file The outdir_structure_file defines the grouping of the terraform auto.tf.vars for the various generated resources.To group resources into different directories within each region - specify the absolute path to the file.To have all the files generated in a single directory in the corresponding region, leave this variable blank. Defaults to /cd3user/oci_tools/cd3_automation_toolkit/user-scripts/outdir_structure_file.properties
tf_or_tofu IaC Tool to be configured - Terraform or OpenTofu terraform
ssh_public_key SSH Key for launched instances; Use '\n' as the delimiter to add multiple ssh keys. ssh-rsa AAXXX......yhdlo\nssh-rsa AAxxskj...edfwf
Advanced Parameters - Fill this to use toolkit with Jenkins
Parameter Description Example
compartment_ocid Compartment OCID where Bucket and DevOps Project/repo will be created; defaults to root if left empty. ocid1.compartment.oc1..aaaaaaaa7....ga
use_remote_state Remote state configuration: Enter yes if remote state needs to be configured, else tfstate will be stored on local filesystem. Needs to be set as "yes" for Jenkins. yes/no
remote_state_bucket_name Specify bucket name if you want to use existing bucket else leave empty.If left empty, Bucket with name ${prefix}-automation-toolkit-bucket will be created/reused in ${region}. demo_bucket
use_oci_devops_git OCI DevOps GIT configuration: Enter yes if generated terraform_files need to be stored in OCI DevOps GIT Repo else they will be stored on local filesystem. Will enforce 'yes' for use_remote_state in case this value is set to 'yes'. Needs to be set as "yes" for Jenkins. yes/no
oci_devops_git_repo_name Specify Repo name if you want to use existing OCI Devops GIT Repository else leave empty Format: . If left empty, DevOps items with names ${prefix}-automation-toolkit-project/repo/topic will be created/reused in ${region}. demo_repo
oci_devops_git_user User Details to perform GIT operations in OCI Devops GIT Repo. Mandatory when using $(auth_mechanism) as instance_principal or session_token. Format: <domainName>/<userName>@<tenancyName> When left empty, it will be fetched from $(user_ocid) for $(auth_mechanism) as api_key. Customer Secret Key will also be configured for this user for S3 credentials of the bucket when $(auth_mechanism) is instance_principal or session_token oracleidentitycloudservice/devopsuser@oracle.com@ocitenant
oci_devops_git_key When left empty, same key file from $(key_path) used for $(auth_mechanism) as api_key will be copied to /cd3user/tenancies/<prefix>/ and used for GIT Operations. Make sure the api key file permissions are rw(600) for cd3user /cd3user/tenancies/keys/oci_api_private.pem


Important

  • Have the details ready for Authentication mechanism you are planning to use.
  • Choose whether the outdir needs to be configured with OpenTofu or Terraform. Its a one time selection for that prefix and cannot be modified later.
  • Review outdir_structure_file parameter as per requirements. It is recommended to use separate outdir structure to manage a large number of resources.
  • Review Advanced Parameters Section for CI/CD setup. The toolkit can be used either with CLI or with Jenkins. If you plan to use the toolkit with Jenkins then be ready with user details that will be used to connect to DevOps Repo in OCI. Specifying these parameters as 'yes' in properties file will create Object Storage Bucket and Devops Git Repo/Project/Topic in OCI and enable toolkit usage with Jenkins. The toolkit supports users in primary IDCS stripes or default domains only for DevOps GIT operations.

Step 4 - Initialise the environment:

  • Initialise your environment to use the Automation Toolkit. 

    python createTenancyConfig.py tenancyconfig.properties

    Note

    • When running the CD3 container on a Linux VM host (without using the Resource Manager stack option), refer to point no. 7 under FAQ to avoid any permission issues.
    • Running the above command immediately after adding API key to the user profile in OCI might result in Authentication Errors. In such cases, retry after a minute.

  • Example execution of the script with Advanced Parameters for CI/CD

    Screenshot 2024-01-10 at 5 54 02 PM

Output:

Output files and OCI resources -
Files Generated At File Path Comment/Purpose
setUpOCI.properties /cd3user/tenancies/<prefix>/<prefix>_setUpOCI.properties Customer Specific properties
outdir_structure_file.properties /cd3user/tenancies/<prefix>/<prefix>_outdir_structure_file Customer Specific properties file for outdir structure. This file will not be generated if 'outdir_structure_file' parameter was set to empty(single outdir)in tenancyconfig.properties while running createTenancyConfig.py
Region based directories /cd3user/tenancies/<prefix>/terraform_files Tenancy's subscribed regions based directories for the generation of terraform files. Each region directory will contain individual directory for each service based on the parameter 'outdir_structure_file'
Variables File,Provider File, Root and Sub terraform modules /cd3user/tenancies/<prefix>/terraform_files/<region> Required for terraform to work. Variables file and Provider file will be generated based on authentication mechanism chosen.
out file /cd3user/tenancies/<prefix>/createTenancyConfig.out This file contains a copy of information displayed as the console output.
OCI Config File /cd3user/tenancies/<prefix>/.config_files/<prefix>_oci_config Customer specific Config file for OCI API calls. This will have data based on authentication mechanism chosen.
Public and Private Key Pair Copied from /cd3user/tenancies/keys/ to /cd3user/tenancies/<prefix>/.config_files API Key for authentication mechanism as API_Key are copied to customer specific out directory locations for easy access.
GIT Config File /cd3user/tenancies/jenkins_home/git_config GIT Config file for OCI Dev Ops GIT operations.This is generated only if use_oci_devops_git is set to yes. Symlink is created for this file at /cd3user/.ssh/config
S3 Credentials File /cd3user/tenancies/<prefix>/.config_files/<prefix>_s3_credentials This file contains access key and secret for S3 compatible bucket to manage remote terraform state. This is generated only if use_remote_state is set to yes
Jenkins Home /cd3user/tenancies/jenkins_home This folder contains jenkins specific data. Single Jenkins instance can be setup for a single container.
tenancyconfig.properties /cd3user/tenancies/<prefix>/.config_files/<prefix>_tenancyconfig.properties The input properties file used to execute the script is copied to customer folder to retain for future reference. This can be used when the script needs to be re-run with same parameters at later stage.
OCI Resources Created Name Comment/Purpose
OCI DevOps Project and Repository <prefix>-automation-toolkit-project and <prefix>-automation-toolkit-repo Devops Project and repo are created under compartment specified under compartment_ocid property in tenancyconfig.properties. This will host the terraform/tofu code. This is created only if use_oci_devops_git is set to yes.
OCI Topic <prefix>-automation-toolkit-topic An empty OCI Topic (without any subscription) is created which is needed for Devops Project.
OCI Bucket <prefix>-automation-toolkit-bucket An OCI bucket is created to store the state file. This is created only if use_remote_state is set to yes.
Customer Secret Key <prefix>-automation-toolkit-csk A Customer Secret Key is created for the user specified in tenancyconfig.properties file. This is used as S3 credentials for the bucket storing remote state.


The next pages will guide you to use the toolkit either via CLI or via Jenkins. You can continue with the instructions provided.

Use Toolkit with CLI Use Toolkit with Jenkins