|
| 1 | += Terraform for Oracle Linux Cloud Native Environment |
| 2 | + |
| 3 | +:idprefix: |
| 4 | +:idseparator: - |
| 5 | +:sectlinks: |
| 6 | + |
| 7 | +:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-olcne |
| 8 | + |
| 9 | +:uri-rel-file-base: link:{uri-repo}/blob/master |
| 10 | +:uri-rel-tree-base: link:{uri-repo}/tree/master |
| 11 | + |
| 12 | +:uri-docs: {uri-rel-file-base}/docs |
| 13 | +:uri-changelog: {uri-rel-file-base}/CHANGELOG.adoc |
| 14 | +:uri-oci: https://cloud.oracle.com/cloud-infrastructure |
| 15 | +:uri-olcne: https://docs.oracle.com/en/operating-systems/olcne/ |
| 16 | +:uri-terraform-oke: https://github.com/oracle-terraform-modules/terraform-oci-oke |
| 17 | +:uri-oke: https://www.oracle.com/cloud/compute/container-engine-kubernetes.html |
| 18 | +:uri-oci-key: https://docs.cloud.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingkeys.htm |
| 19 | +:uri-oci-bmshapes: https://docs.cloud.oracle.com/en-us/iaas/Content/Compute/References/computeshapes.htm#bmshapes |
| 20 | +:uri-oci-vault: https://docs.cloud.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingvaults.htm |
| 21 | +:uri-terraform-oci-base: https://github.com/oracle-terraform-modules/terraform-oci-base |
| 22 | +:uri-docs: {uri-rel-file-base}/docs |
| 23 | +:uri-medium-dns: https://medium.com/oracledevs/loadbalancer-service-oracle-container-engine-oke-and-oci-dns-d7b1f7b4f9bd |
| 24 | + |
| 25 | + |
| 26 | +__Current version: 0.1__ |
| 27 | + |
| 28 | +The {uri-repo}[Terraform OCI OLCNE module] for {uri-oci}[Oracle Cloud Infrastructure] (OCI) provides a reusable and extensible Terraform module that provisions {uri-olcne}[Oracle Linux Cloud Native Environment] on OCI. It is developed as a tool for developers as a technical preview. It simplifies the setup needed to quickly deploy using Oracle Cloud compute infrastructure. |
| 29 | + |
| 30 | +This _Technical Preview_ is not intended for production use, and has the following limitations: |
| 31 | + |
| 32 | +* OLCNE is currently supported on Bare Metal shapes only. You can use this module to install on Virtual Machine shapes, |
| 33 | + but you should be aware that while that may work, it is not a supported configuration. |
| 34 | +* Multi-master clusters are not supported. |
| 35 | +* The OLCNE nodes must opt out of OS Management Service to prevent RPM conflicts. |
| 36 | +
|
| 37 | +If you are deploying a production Kubernetes cluster on OCI, you should consider using {uri-oke}[Oracle Cloud Infrastructure |
| 38 | +Container Engine for Kubernetes] (OKE). You can use {uri-terraform-oke}[terraform-oci-oke] to provision an OKE cluster. |
| 39 | + |
| 40 | + |
| 41 | +== What this module will create |
| 42 | + |
| 43 | +This module will create the following resources: |
| 44 | + |
| 45 | +image::docs/images/infrastructure.png[align="Infrastructure"] |
| 46 | + |
| 47 | +. Base module: |
| 48 | + |
| 49 | +** A VCN with internet, service and NAT gateways, and route tables. |
| 50 | +** A security list, subnet and a bastion host (using Oracle Autonomous Linux). |
| 51 | +** An optional notification topic and subscription. |
| 52 | + |
| 53 | +. Network module: |
| 54 | + |
| 55 | +** Network security groups for operator, master and worker nodes as well as a public load balancer. |
| 56 | +** Separate subnets for operator, master, worker and load balancer. |
| 57 | + |
| 58 | +. Operator module: |
| 59 | + |
| 60 | +** An operator node to perform installation of OLCNE on the master and worker nodes. |
| 61 | +** An ingress controller of type `NodePort`. |
| 62 | +** An optional Kata container runtime class. |
| 63 | + |
| 64 | +. Master: |
| 65 | + |
| 66 | +** Single master node. Multi-master is not supported yet. |
| 67 | +** Instance pools to manage the master nodes. |
| 68 | + |
| 69 | +. Worker: |
| 70 | + |
| 71 | +** A configurable number of worker nodes. |
| 72 | +** Instance pools to manage to worker nodes. |
| 73 | + |
| 74 | +. Load balancer: |
| 75 | + |
| 76 | +* A public load balancer with automatic backend creation. |
| 77 | + |
| 78 | + |
| 79 | += Instructions |
| 80 | + |
| 81 | +To use this module to create an OLCNE environment: |
| 82 | + |
| 83 | +== Vault |
| 84 | + |
| 85 | +Create a vault to store the SSH keys securely. |
| 86 | + |
| 87 | +=== Create a key |
| 88 | + |
| 89 | +. In the OCI Console, create a vault by navigating to Security > Vault. See {uri-oci-vault}[Managing Vaults] for more details. |
| 90 | +. Click on the vault and click 'Create Key'. See {uri-oci-key}[Managing Keys] for more details. |
| 91 | + |
| 92 | +=== Creating a secret for private ssh key |
| 93 | + |
| 94 | +. Click on Secrets and click 'Create Secret'. |
| 95 | +. Select compartment where you want to create the secret, enter a name and description. |
| 96 | +. Select the encryption key you created previously. |
| 97 | +. Set the secret type template as `plain-text`. |
| 98 | +. Paste the contents of your private SSH key in secret contents. |
| 99 | +. After the secret is created, click on the secret name and note down the OCID of the secret as you will need it later. |
| 100 | + |
| 101 | +== Create the base infrastructure |
| 102 | + |
| 103 | +The base infrastructure consists of the bastion and the admin server. It reuses the {uri-terraform-oci-base}[terraform-oci-base] module to create a VCN, a bastion host and an admin host with `instance_principal` enabled. You only need the bastion host; the `admin_host` is not needed. |
| 104 | + |
| 105 | +. Copy `terraform.tfvars.example`: |
| 106 | + |
| 107 | ++ |
| 108 | +---- |
| 109 | +cp terraform.tfvars.example terraform.tfvars |
| 110 | +---- |
| 111 | + |
| 112 | +. Edit `terraform.tfvars` and set the following parameters to the correct values for your environment: |
| 113 | + |
| 114 | ++ |
| 115 | +---- |
| 116 | +api_fingerprint = "" |
| 117 | +api_private_key_path = "" |
| 118 | +compartment_id = "" |
| 119 | +tenancy_id = "" |
| 120 | +user_id = "" |
| 121 | +ssh_private_key_path = "/path/to/ssh_private_key" |
| 122 | +ssh_public_key_path = "/path/to/ssh_public_key" |
| 123 | +---- |
| 124 | + |
| 125 | +. In terraform.tfvars, enable only the bastion host: |
| 126 | + |
| 127 | ++ |
| 128 | +---- |
| 129 | +bastion_enabled = true |
| 130 | +admin_enabled = false |
| 131 | +admin_instance_principal = false |
| 132 | +---- |
| 133 | + |
| 134 | +. Run Terraform and create the base module: |
| 135 | + |
| 136 | ++ |
| 137 | +---- |
| 138 | +terraform apply --target=module.base -auto-approve |
| 139 | +---- |
| 140 | + |
| 141 | +. SSH to the bastion to check whether you can proceed: |
| 142 | + |
| 143 | ++ |
| 144 | +---- |
| 145 | +ssh opc@xxx.xxx.xxx |
| 146 | +---- |
| 147 | + |
| 148 | +If you are not able to ssh to the bastion host, you will not be able to proceed any further. |
| 149 | + |
| 150 | +== Complete the rest of the OLCNE infrastructure |
| 151 | + |
| 152 | +. Update your `terraform.tfvars` and enter the values for the `secret_id` and certificate information to create private CA certificates. |
| 153 | + |
| 154 | ++ |
| 155 | +---- |
| 156 | +secret_id = "ocid1.vaultsecret....." |
| 157 | +org_unit = "my org unit" |
| 158 | +org = "my org" |
| 159 | +city = "Sydney" |
| 160 | +state = "NSW" |
| 161 | +country = "au" |
| 162 | +common_name = "common name" |
| 163 | +---- |
| 164 | + |
| 165 | +. Run `terraform apply` again: |
| 166 | + |
| 167 | ++ |
| 168 | +---- |
| 169 | +terraform apply -auto-approve |
| 170 | +---- |
| 171 | + |
| 172 | +When complete, Terraform will output details of how to connect to the bastion, master and operator, for example: |
| 173 | + |
| 174 | +---- |
| 175 | +Outputs: |
| 176 | +
|
| 177 | +ssh_to_bastion = ssh -i /path/to/ssh/key opc@123.45.67.209 |
| 178 | +ssh_to_master = ssh -i /path/to/ssh/key -J opc@123.45.67.209 opc@10.0.3.2 |
| 179 | +ssh_to_operator = ssh -i /path/to/ssh/key -J opc@123.45.67.209 opc@10.0.0.146 |
| 180 | +---- |
| 181 | + |
| 182 | +You can SSH to the operator and access the cluster, for example: |
| 183 | + |
| 184 | +---- |
| 185 | +[opc@cne-operator ~]$ kubectl get nodes |
| 186 | +NAME STATUS ROLES AGE VERSION |
| 187 | +cne-master Ready master 22m v1.17.4+1.0.1.el7 |
| 188 | +cne-worker Ready <none> 21m v1.17.4+1.0.1.el7 |
| 189 | +cne-worker-550781 Ready <none> 21m v1.17.4+1.0.1.el7 |
| 190 | +cne-worker-585063 Ready <none> 21m v1.17.4+1.0.1.el7 |
| 191 | +---- |
| 192 | + |
| 193 | +== Controlling the cluster size |
| 194 | + |
| 195 | +=== Master nodes |
| 196 | + |
| 197 | +Only one master node is created. |
| 198 | + |
| 199 | +=== Worker nodes |
| 200 | + |
| 201 | +By default, three worker nodes are created. You can change this by setting _worker_size = 5_. |
| 202 | + |
| 203 | +== Using Kata Containers |
| 204 | + |
| 205 | +If you want to use Kata containers, you must: |
| 206 | + |
| 207 | +. Select one of the {uri-oci-bmshapes}[Bare Metal shapes] for your worker nodes. |
| 208 | +. Enable the creation of kata runtime class in `terraform.tfvars`. |
| 209 | + |
| 210 | ++ |
| 211 | +---- |
| 212 | +create_kata_runtime = true |
| 213 | +---- |
| 214 | + |
| 215 | +By default, the name of the kata runtime class is 'kata'. You can configure that with the _kata_runtime_class_name_ parameter. |
| 216 | + |
| 217 | +When deploying kata containers, set the runtimeClassName accordingly: |
| 218 | + |
| 219 | +---- |
| 220 | +apiVersion: v1 |
| 221 | +kind: Pod |
| 222 | +metadata: |
| 223 | + name: kata-nginx |
| 224 | +spec: |
| 225 | + runtimeClassName: kata |
| 226 | + containers: |
| 227 | + - name: nginx |
| 228 | + image: nginx |
| 229 | + ports: |
| 230 | + - containerPort: 80 |
| 231 | +---- |
| 232 | + |
| 233 | +== Testing a deployment |
| 234 | + |
| 235 | +. Print out the output to access the operator: |
| 236 | + |
| 237 | ++ |
| 238 | +---- |
| 239 | +terraform output |
| 240 | +ssh_to_operator = ssh -i ~/.ssh/id_rsa -J opc@XXX.XXX.XXX.XXX opc@10.0.0.146 |
| 241 | +---- |
| 242 | + |
| 243 | +. Copy the ssh_to_operator command and run: |
| 244 | + |
| 245 | ++ |
| 246 | +---- |
| 247 | +ssh -i ~/.ssh/id_rsa -J opc@XXX.XXX.XXX.XXX |
| 248 | +---- |
| 249 | + |
| 250 | +. Deploy an application |
| 251 | + |
| 252 | ++ |
| 253 | +---- |
| 254 | +git clone https://github.com/hyder/okesamples/ |
| 255 | +cd okesamples |
| 256 | +kubectl apply -f ingresscontrollers/acme/ |
| 257 | +---- |
| 258 | + |
| 259 | +. Edit the ingresses in `ingresscontrollers/nginx` and replace `www.acme.com` with a domain within your control |
| 260 | + |
| 261 | +. Create the ingresses: |
| 262 | + |
| 263 | ++ |
| 264 | +---- |
| 265 | +kubectl apply -f ingresscontrollers/nginx/ |
| 266 | +---- |
| 267 | + |
| 268 | +. Follow the steps towards the end of this article to {uri-medium-dns}[configure DNS in OCI] and use the domain you set in the ingress above. |
0 commit comments