Connect CD3 Container to OCI Tenancy
Connecting the CD3 container to an OCI tenancy authenticates the toolkit, allowing it to create, update, or export resources from the tenancy.
🛠️ Steps:
1 - Login (Exec) into the Container
-
Login to the previously launched container using either RM Stack or Manual Launch.
2 - Choose Authentication Mechanism for OCI SDK
- Click here to configure any one of the available authentication mechanisms.
Access Requirements
Make sure to assign required OCI Tenancy Access to user/instance as defined in Prerequisites.
3 - Edit tenancyconfig.properties
-
Run
-
Fill the input parameters in
tenancyconfig.propertiesfile. Expand below tables for parameter description and sample data. Description for each parameter is also provided within the 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 - 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: |
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 Users in Custom Domain are not supported as of now. | 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 Configuration Tips
- 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.
4 - Initialise the environment
-
Initialise your environment to use the Automation Toolkit.
Heads-Up!
- 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.
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. |
Example execution of the script with Advanced Parameters for CI/CD
Subscribing to a new OCI Region?
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 modifying the existing ones
✅ It will also commit the latest terraform_files folder to OCI DevOps GIT repo.
Managing Multiple Prefixes?
Need to manage multiple environments separately by using distinct prefixes, all within a single CD3 container?
Check this out: Multiple Prefixes
Choose how to use the toolkit and follow the corresponding instructions: