Connect 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:

Login to the previously launched container using either RM Stack or Manual Launch.

Step 2 - Choose Authentication Mechanism for OCI SDK

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

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

Output:

Output files -

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 directorywill 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 willbe genrated based on authentication mechanism chosen.
out file	/cd3user/tenancies/<prefix>/createTenancyConfig.out	This file contains acopy 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 havedata based on authentication mechanism chosen.
Public and Private Key Pair	Copied from /cd3user/tenancies/keys/ to /cd3usertenancies/<prefix>/.config_files	API Key for authentication mechanism as API_Key arecopied to customer specific out directory locations for easy access.
GIT Config File	/cd3user/tenancies/<prefix>/.config_files/<prefix>_git_config	Customer specific GIT Config file for OCI Dev Ops GIT operations.This is generated only if use_oci_devops_git is set to yes
S3 Credentials File	/cd3user/tenancies/<prefix>/.config_files/<prefix>_s3_credentials	This file contains access key and secret for S3 compatible OSbucket 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 custome folder to retain for future reference. This can be used when the script needs tobe re-run with same parameters at later stage.

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