Terraform for Oracle Cloud Native Environment

Introduction

This repository is the top level for a modularized method for deploying OCNE and its subcomponents into OCI using terraform. Each submodule focuses on a specific portion of an OCNE deploymnent, allowing users to select specific configurations to deploy.

This module will create the following resources:

OCNE API Server: The OCNE API Server to orchestrate OCNE agents running on Control Plane and Worker nodes to perform installation of Kubernetes and other OCNE modules.
Control Plane Nodes: The compute instances for the Control Plane Nodes of Kubernetes cluster.
Worker Nodes: The compute instances for the Worker Nodes of Kubernetes cluster.
Kubernetes API Load Balancer: The Load Balancer to distribute Kubernetes API requrests to the Control Plane Nodes.

High-Level Deployment Options

This module supports several common deployment scenarios out of the box. They are listed here to avoid having to duplicated them in each of the relevant module descriptions below

OCNE API Server on a dedicated compute instance
Passing in a default network to build the deployment in
Allowing these modules to create and configure a new network
Use openssl to generate and distribute certificates to each node

Getting Started

Install Terraform

Start by installing Terraform and configuring your path.

Download Terraform

Open your browser and navigate to the Terraform download page. You need version 1.0.0+.
Download the appropriate version for your operating system
Extract the contents of compressed file and copy the terraform binary to a location that is in your path (see next section below)

Configure path on Linux/macOS

Open a terminal and type the following:

$ sudo mv /path/to/terraform /usr/local/bin

Configure path on Windows

Follow the steps below to configure your path on Windows:

Click on 'Start', type 'Control Panel' and open it
Select System > Advanced System Settings > Environment Variables
Select System variables > PATH and click 'Edit'
Click New and paste the location of the directory where you have extracted the terraform.exe
Close all open windows by clicking OK
Open a new terminal and verify terraform has been properly installed

Testing Terraform installation

Open a terminal and test:

terraform -v

Install jq and yq

The OCNE provision module uses jq and yq to process yaml files

Install yq (>= 4.16): https://github.com/mikefarah/yq#install
Install jq (>= 1.5): https://stedolan.github.io/jq/download/

Generate API keys

Follow the documentation for generating keys on OCI Documentation.

Upload your API keys

Follow the documentation for uploading your keys on OCI Documentation.

Note the fingerprint.

Create an OCI compartment

Follow the documentation for creating a compartment.

Obtain the necessary OCIDs

The following OCIDs are required:

Compartment OCID
Tenancy OCID
User OCID

Follow the documentation for obtaining the tenancy and user ids on OCI Documentation.

To obtain the compartment OCID:

Navigate to Identity > Compartments
Click on your Compartment
Locate OCID on the page and click on 'Copy'

Deploy OCNE using terraform

The best place to start when using these Terraform modules is in the terraform-oci-olcne module (i.e. here). This module deploys a complete OCNE stack including a Kubernetes cluster.

The terraform.tfvars.example file can be renamed as terraform.tfvars to set the input variables for the terraform-oci-olcne module. Please refer to the variable descriptions in variables.tf for information about how each is used.

Overview of terraform.tfvars.example file variables

Name	Description
tenancy_id	The OCID of your tenancy. To get the value, see Where to Get the Tenancy's OCID and User's OCID.
compartment_id	The OCID of the compartment.
user_id	The OCID of the user that will be used by terraform to create OCI resources. To get the value, see Where to Get the Tenancy's OCID and User's OCID.
fingerprint	Fingerprint for the key pair being used. To get the value, see How to Get the Key's Fingerprint
api_private_key_path	The path to the private key used by the OCI user to authenticate with OCI API's. For details on how to create and configure keys see How to Generate an API Signing Key and How to Upload the Public Key.
region	The OCI region where resources will be created. To get the value, See Regions and Availability Domains.
availability_domain_id	The ID of the availability domain inside the `region` to create the deployment
prefix	A unique prefix to attach to the name of all OCNE resources that are created as a part of the deployment.
ssh_private_key_path	The SSH private key path that goes with the SSH public key that is used when accessing compute resources that are created as part of this deployment. To generate the keys see - Generating an SSH Key Pair for Oracle Compute Cloud Service Instances.
ssh_public_key_path	The SSH public key path to use when configuring access to any compute resources created as part of this deployment. To generate the keys see - Generating an SSH Key Pair for Oracle Compute Cloud Service Instances.
control_plane_node_count	The number of Kubernetes control plane nodes to deploy. To view the recommended worker node count, please see Kubernetes High Availability Requirements.
worker_node_count	The number of Kubernetes worker nodes to deploy. To view the recommended worker node count, please see Kubernetes High Availability Requirements.
os_version	The version of Oracle Linux to use as the base image for all compute resources that are part of this deployemnt.
environment_name	The name of the OCNE Environment that is created by this module to deploy module instances into. For more details, please see Creating an Environment.
kubernetes_name	The name of the instance of the OCNE Kubernetes module that is installed as part of this deployment. For more details, please see Creating a Kubernetes Module.
ocne_version	The version and release of OCNE to deploy. For more details on the versions, please see the OCNE Release Notes. To install the latest patch version of <major.minor>, please set the value to `<major.minor>` or set the value to `<major.minor.patch>` to install a specific patch version.
config_file_path	The path to the OCNE configuration file. For more details on the configuration file, please see the OCNE configuration file

Using Object Storage for State Files

Using Object Storage statefile requires that you create an AWS S3 Compatible API Key on OCI. This can be done from both the OCI UI and CLI. For more details visit Using Object Storage for State Files.

To get started, rename state_backend.tf.example to state_backend.tf and fill out the appropriate variables. Variable definitions for the S3 Backend can be found in the Hashicorp Terraform S3 Backend Documentation.

Deploying Environment

Once all required variabes are set, source them and then initialise, validate and apply terraform. These commands must be run from within this module.

terraform init

The terraform init command is used to initialize a working directory containing Terraform configuration files. This is the first command that should be run after writing a new Terraform configuration or cloning an existing one from version control. It is safe to run this command multiple times.
terraform validate

The terraform validate command validates the configuration files in a directory, referring only to the configuration.
terraform apply

The terraform apply command is used to apply the changes required to reach the desired state of the configuration.

oracle-terraform-modules/terraform-oci-ocne