Merge pull request #39 from hyder/issue-38

formatting, variables and output descriptions, updated docs

Author: hyder

docs/instanceprincipal.adoc

@@ -37,16 +37,20 @@ This section documents the use of {uri-oci-instance-principal}[instance_principa
 
 Any user who has access to the instance (who can SSH to the instance), automatically inherits the privileges granted to the instance. Before you enable this feature, ensure that you know who can access it, and that they should be authorized with the permissions you are granting to the instance.
 
-By default, this feature is *_enabled_*.
+By default, this feature is *_disabled_*.
 
-When you enable this feature, by default, the admin host has privileges to all resources in the compartment. 
+When you enable this feature, by default, the admin host has privileges to manage all resources in the compartment. 
 
 You can also turn on and off the feature at any time without impact on the admin host.
 
-To enable, set enable_instance_principal to true:
+To enable, set enable_instance_principal in oci_base_admin to true:
 
 ----
-enable_instance_principal = "true"
+oci_base_admin = {
+  ....
+  enable_instance_principal = true
+  ....
+}
 ----
 
 and verify:
@@ -55,13 +59,19 @@ and verify:
 oci network vcn list --compartment-id <compartment-ocid>
 ----
 
+You should be able to see a list of VCNs created in the compartment.
+
 ==== Disabling instance_principal on the admin host
 
-. Set enable_instance_principal to false in terraform.tfvars
+To disable, set enable_instance_principal in oci_base_admin to false:
 
 +
 ----
-enable_instance_principal = false
+oci_base_admin = {
+  ....
+  enable_instance_principal = false
+  ....
+}
 ----
 
 . Run terraform apply again:

docs/notifications.adoc

@@ -32,10 +32,14 @@ The {uri-oci-notifications}[Oracle Cloud Infrastructure Notifications service] c
 Set the following parameters in the terraform.tfvars in order to enable ONS Notification for the bastion host:
 
 ----
-  notification_enabled       = true
-  notification_endpoint      = "email_address"
-  notification_protocol      = "EMAIL"
-  notification_topic         = "bastion"
+oci_base_bastion = {
+  ...
+  notification_enabled  = true
+  notification_endpoint = "valid_email_address"
+  notification_protocol = "EMAIL"
+  notification_topic    = "bastion"
+  ...
+}
 ----
 
 If your bastion is already created, set the above parameters in the terraform.tfvars and run terraform apply again:
@@ -46,26 +50,16 @@ terraform apply
 
 You'll then receive a notification email to confirm the subscription.
 
-Note that at the time of enabling ONS notification, instance_principal for the bastion must be enabled by setting *enable_instance_principal* to _true_. This can subsequently be disabled by setting it to _false_:
-
-----
-  enable_instance_principal = false
-----
-
-and running terraform apply again:
-
-----
-terraform apply
-----
-
-Read more on {uri-instance-principal}[instance_principal].
-
 ==== Disabling ONS Notification for the bastion host
 
 Set the following parameters in the terraform.tfvars to disable ONS Notification:
 
 ----
-  notification_enabled        = false
+oci_base_bastion = {
+  ...
+  notification_enabled  = false
+  ...
+}
 ----
 
 and run terraform apply again:

docs/terraformoptions.adoc

@@ -69,9 +69,9 @@ Configuration Terraform Options:
 |Default
 
 |label_prefix
-|a string to be prepended to the name of resources.
+|a string to be prepended to the name of resources. *Recommended*
+|
 |
-|base
 
 |region
 |Region where to provision the resources. {uri-oci-region}[List of regions]. *Required*
@@ -97,22 +97,22 @@ Configuration Terraform Options:
 |service_gateway_enabled
 |Whether to create a Service Gateway to use Oracle Services.
 |true/false
-|false
+|true
 
 |vcn_cidr
 |The VCN's CIDR block.
 |
 |10.0.0.0/16
 
 |vcn_dns_label
-|The internal DNS domain for resources created and prepended to "oraclevcn.com" which is the VCN-internal domain name.
+|The internal DNS domain for resources created and prepended to "oraclevcn.com" which is the VCN-internal domain name. *Required*
+|
 |
-|base
 
-|vcn_name
-|The name of the VCN that will be appended to the label_prefix.
+|vcn_name. 
+|The name of the VCN that will be appended to the label_prefix. *Recommended*
+|
 |
-|base
 
 |===
 
@@ -145,28 +145,23 @@ Configuration Terraform Options:
 |bastion_enabled
 |Whether to create the bastion host.
 |true/false
-|true
+|false
 
 |bastion_image_id
-|Custom image id for the bastion host
+|Provide a custom image id for the bastion host or leave as Autonomous.
 |imageid/Autonomous
 |Autonomous
 
 |bastion_shape
-|The shape of bastion instance.
+|The shape of bastion instance. *Required if bastion_enabled = true*
+|
 |
-|VM.Standard.E2.1
 
 |bastion_upgrade
-|Whether to upgrade the bastion host packages after provisioning. It's useful to set this to false during development so the bastion is provisioned faster.
+|Whether to upgrade the bastion host packages after provisioning. It's useful to set this to false during development/testing so the bastion is provisioned faster.
 |true/false
 |true
 
-|enable_notification
-|Whether to enable ONS notification for the bastion host.
-|true/false
-|false
-
 |newbits
 |The difference between the VCN's netmask and the desired subnets' masks specified in the form of a map. The values of the map are used as the newbits parameter in the {uri-terraform-cidrsubnet}[cidrsubnet] Terraform function to calculate each subnet's mask.
 |[source]
@@ -191,8 +186,13 @@ Configuration Terraform Options:
 32
 ----
 
+|notification_enabled
+|Whether to enable ONS notification for the bastion host.
+|true/false
+|false
+
 |notification_endpoint
-|The subscription notification endpoint. Email address to be notified.
+|The subscription notification endpoint. Email address to be notified. *Required if notification_enabled = true* .
 |
 |
 
@@ -236,7 +236,7 @@ Configuration Terraform Options:
 |admin_enabled
 |Whether to create the admin host.
 |true/false
-|true
+|false
 
 |admin_image_id
 |Custom image id for the admin host
@@ -246,24 +246,24 @@ Configuration Terraform Options:
 |enable_instance_principal
 |Whether to enable instance_principal on the admin server. Refer to {uri-instance-principal-note}[instance_principal][instance_principal]
 |true/false
-|true
+|false
 
-|admin_notification_enabled
+|notification_enabled
 |Whether to enable ONS notification for the admin host. *Do not enable for now*.
 |true/false
 |false
 
-|admin_notification_endpoint
+|notification_endpoint
 |The subscription notification endpoint. Email address to be notified. Only email is currently supported although ONS can also support Slack, Pagerduty among others.
 |
 |
 
-|admin_notification_protocol
+|notification_protocol
 |The notification protocol used.
 |EMAIL
 |EMAIL
 
-|admin_notification_topic
+|notification_topic
 |The name of the notification topic
 |
 |admin
@@ -276,7 +276,7 @@ Configuration Terraform Options:
 |admin_shape
 |The shape of admin instance.
 |
-|VM.Standard.E2.1
+|
 
 |admin_timezone
 |The preferred timezone for the admin host. {uri-timezones}[List of timezones]

main.tf

@@ -10,7 +10,7 @@ module "bastion" {
   source                   = "./modules/bastion"
   oci_base_identity        = var.oci_base_identity
   oci_bastion_general      = local.oci_bastion_general
-  oci_bastion_network        = local.oci_bastion_network
+  oci_bastion_network      = local.oci_bastion_network
   oci_bastion              = local.oci_bastion
   oci_bastion_notification = local.oci_bastion_notification
 }

modules/admin/cloudinit/admin.template.yaml

@@ -14,7 +14,7 @@ write_files:
     content: |
       ${admin_sh_content}
 runcmd:
- - echo "Configuring admin..." | tee /root/admin/admin.txt
+ - echo "Configuring admin..."
  - bash /root/admin/admin.sh
  - echo "export OCI_CLI_AUTH=instance_principal" >>  /home/opc/.bashrc
  - touch /home/opc/admin.finish

modules/admin/compute.tf

@@ -14,17 +14,16 @@ resource "oci_core_instance" "admin" {
 
   display_name = "${var.oci_admin_general.label_prefix}-admin"
 
-  extended_metadata = {
-    ssh_authorized_keys = file(var.oci_admin.ssh_public_key_path)
-    user_data           = data.template_cloudinit_config.admin[0].rendered
-    subnet_id           = oci_core_subnet.admin[0].id
-  }
-
   # prevent the bastion from destroying and recreating itself if the image ocid changes 
   lifecycle {
     ignore_changes = [source_details[0].source_id]
   }
 
+  metadata = {
+    ssh_authorized_keys = file(var.oci_admin.ssh_public_key_path)
+    user_data           = data.template_cloudinit_config.admin[0].rendered
+  }
+
   shape = var.oci_admin.admin_shape
 
   source_details {

modules/admin/datasources.tf

@@ -11,7 +11,8 @@ data "oci_core_images" "admin_images" {
 
 data "template_file" "admin_template" {
   template = file("${path.module}/scripts/admin.template.sh")
-  count    = var.oci_admin.admin_enabled == true ? 1 : 0
+
+  count = var.oci_admin.admin_enabled == true ? 1 : 0
 }
 
 
@@ -23,6 +24,7 @@ data "template_file" "admin_cloud_init_file" {
     admin_upgrade    = var.oci_admin.admin_upgrade
     timezone         = var.oci_admin.timezone
   }
+
   count = var.oci_admin.admin_enabled == true ? 1 : 0
 }
 
@@ -36,6 +38,7 @@ data "template_cloudinit_config" "admin" {
     content_type = "text/cloud-config"
     content      = data.template_file.admin_cloud_init_file[0].rendered
   }
+
   count = var.oci_admin.admin_enabled == true ? 1 : 0
 }
 
@@ -44,17 +47,19 @@ data "oci_core_vnic_attachments" "admin_vnics_attachments" {
   availability_domain = element(var.oci_admin_network.ad_names, (var.oci_admin_network.availability_domains - 1))
   compartment_id      = var.oci_admin_identity.compartment_id
   instance_id         = oci_core_instance.admin[0].id
-  count               = var.oci_admin.admin_enabled == true ? 1 : 0
+
+  count = var.oci_admin.admin_enabled == true ? 1 : 0
 }
 
 # Gets the OCID of the first (default) VNIC on the admin instance
 data "oci_core_vnic" "admin_vnic" {
   vnic_id = lookup(data.oci_core_vnic_attachments.admin_vnics_attachments[0].vnic_attachments[0], "vnic_id")
-  count   = var.oci_admin.admin_enabled == true ? 1 : 0
+
+  count = var.oci_admin.admin_enabled == true ? 1 : 0
 }
 
 data "oci_core_instance" "admin" {
-  #Required
   instance_id = oci_core_instance.admin[0].id
-  count       = var.oci_admin.admin_enabled == true ? 1 : 0
+
+  count = var.oci_admin.admin_enabled == true ? 1 : 0
 }

modules/admin/instance_principal.tf

@@ -23,19 +23,23 @@ data "oci_identity_compartments" "compartments_id" {
 }
 
 resource "oci_identity_dynamic_group" "admin_instance_principal" {
-  provider       = oci.home
+  provider = oci.home
+
   compartment_id = var.oci_admin_identity.tenancy_id
   description    = "dynamic group to allow instances to call services for 1 admin"
   matching_rule  = "ALL {instance.id = '${join(",", data.oci_core_instance.admin.*.id)}'}"
   name           = "${var.oci_admin_general.label_prefix}-admin_instance_principal"
-  count          = var.oci_admin.admin_enabled == true && var.oci_admin.enable_instance_principal == true ? 1 : 0
+
+  count = var.oci_admin.admin_enabled == true && var.oci_admin.enable_instance_principal == true ? 1 : 0
 }
 
 resource "oci_identity_policy" "admin_instance_principal" {
-  provider       = oci.home
+  provider = oci.home
+
   compartment_id = var.oci_admin_identity.compartment_id
   description    = "policy to allow admin host to call services"
   name           = "${var.oci_admin_general.label_prefix}-admin_instance_principal"
   statements     = ["Allow dynamic-group ${oci_identity_dynamic_group.admin_instance_principal[0].name} to manage all-resources in compartment id ${data.oci_identity_compartments.compartments_id.compartments.0.id}"]
-  count          = var.oci_admin.admin_enabled == true && var.oci_admin.enable_instance_principal == true ? 1 : 0
+
+  count = var.oci_admin.admin_enabled == true && var.oci_admin.enable_instance_principal == true ? 1 : 0
 }

modules/admin/security.tf

@@ -4,7 +4,6 @@
 resource "oci_core_security_list" "admin" {
   compartment_id = var.oci_admin_identity.compartment_id
   display_name   = "${var.oci_admin_general.label_prefix}-admin"
-  vcn_id         = var.oci_admin_network.vcn_id
 
   egress_security_rules {
     protocol    = local.all_protocols
@@ -22,5 +21,7 @@ resource "oci_core_security_list" "admin" {
       max = local.ssh_port
     }
   }
+  vcn_id         = var.oci_admin_network.vcn_id
+
   count = var.oci_admin.admin_enabled == true ? 1 : 0
 }

modules/admin/subnets.tf

@@ -2,8 +2,8 @@
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
 
 resource "oci_core_subnet" "admin" {
-  compartment_id             = var.oci_admin_identity.compartment_id
   cidr_block                 = cidrsubnet(var.oci_admin_network.vcn_cidr, var.oci_admin_network.newbits, var.oci_admin_network.netnum)
+  compartment_id             = var.oci_admin_identity.compartment_id
   display_name               = "${var.oci_admin_general.label_prefix}-admin"
   dns_label                  = "admin"
   prohibit_public_ip_on_vnic = true