renamed operator_instance_principal variable (#51)

hyder · web-flow · commit 2ae4e517f1c7 · 2021-09-14T15:11:20.000+10:00
Signed-off-by: Ali Mukadam &lt;ali.mukadam@oracle.com&gt;
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -16,6 +16,7 @@ The format is based on {uri-changelog}[Keep a Changelog].
 * Renamed variable operating_system_version --> operator_os_version
 * Renamed variable operator_upgrade --> upgrade_operator
 * Renamed variable timezone --> operator_timezone
+* Renamed variable operator_instance_principal --> enable_operator_instance_principal
 * Added support for Bastion service
 * AD lookup mechanism reimplemented to remove dependency on deprecated template_file data source
 * Replaced deprecated template_file data source with templatefile function
diff --git a/docs/codingconventions.adoc b/docs/codingconventions.adoc
@@ -0,0 +1,118 @@
+= Coding conventions
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+:sectnums:
+:toc:
+
+:uri-terraform-standard-module-structure: https://www.terraform.io/docs/language/modules/develop/structure.html
+
+This is a list of coding conventions you should observe when contributing code for this project.
+
+Current conventions:
+
+- module structure
+- adopting the right case type
+- good names for files and terraform objects (resources, variables, outputs)
+
+It is not an exhaustive list and it will be updated as we go. In the mean time, your PR reviewer may suggest conventions that are not listed here.
+
+Use PR comments and the GitHub suggestion feature to agree on the final result.
+
+== Module Structure
+
+- We adhere to the {uri-terraform-standard-module-structure}[Terraform Standard Module Structure]
+- Any nested module calls should be in the main file: `main.tf` is the primary entrypoint of the module
+- All variables and ouputs declarations should be in `variables.tf` and `outputs.tf`
+- All variables and outputs should have descriptions
+- Nested modules should exist under the `modules/` folder
+- Examples of using the module should exist under the `examples/` folder and have a README to explain the goal and usage of the example
+
+== Documentation format
+
+We use https://asciidoc.org/[AsciiDoc] with the `*.adoc` file extension. The only exception is for the README files that need to be displayed on the Terraform Registry: as the Terraform Registry does not support AsciiDoc, the `README` and certain other documentation must be available in Markdown format.
+
+[NOTE]
+====
+As GitHub renders AsciiDoc files using https://asciidoctor.org/[AsciiDoctor], it is the current reference regarding AsciiDoc syntax we use in the documentation.
+====
+
+=== Internal links
+
+For internal links to AsciiDoc file (repo documentation content), we use relative links with the `xref:` macro.
+
+```
+xref:CONTRIBUTING.adoc[CONTRIBUTING]
+```
+
+For internal links to non-AsciiDoc file (e.g: README files), we use relative links with the `link:` macro.
+
+```
+link:examples/README.md[examples README]
+```
+
+=== External links
+
+For external links, we use https://docs.asciidoctor.org/asciidoc/latest/macros/autolinks/[autolinks].
+
+[TIP]
+====
+Links that are used multiple times must be defined in the header using the `:uri-xxx:` reference format. This makes any future updates to the URI much simpler.
+
+. Defining a link in the document header
+. Calling the reference
+
+----
+:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-vcn
+
+{uri-repo}[link caption]
+----
+
+====
+
+===  Terraform registry requirements
+
+- README files must be in Markdown format
+- All links must use absolute path, relative links are not supported
+
+== Terraform code
+
+=== Case type, Files, Names
+
+- Use `snake_case` when naming Terraform files, variables and resources
+- If you need a new .tf file for better clarity, use this naming scheme: `<resources_group>`: e.g. `subnets.tf`, `nsgs.tf`
+- If your variable is controlling a behaviour, use imperative style to name it: e.g. `create_internet_gateway`, `use_encryption`
+
+=== Variable blocks
+
+Variables should always be in the format below:
+
+----
+variable "xyz" {
+  default = "A default value"
+  description:  "Add (Updatable) at the begining of the description if this value do not triggers a resource recreate"
+  type: string
+----
+
+When defining variables:
+
+. do not hesitate to insert a brief comment in the variable block if it helps to clarify your intention.
+. the type should always be specified. We prefer:
+.. string
+.. boolean
+.. number
+.. collection (list, set, map, tuples) of the above
+. if you specify a default value, it should:
+.. reflect a sensible default
+.. match the type specified
+.. be reflected in terraform.tfvars.example
+
+WARNING: No default value for `compartment_id` or any other variables related to provider authentication in module or examples files. The user will have to explicitly set these values.
+
+=== Examples
+
+Examples should promote good practices as much as possible e.g. avoid creating resources in the tenancy root compartment.
diff --git a/docs/instanceprincipal.adoc b/docs/instanceprincipal.adoc
@@ -1,8 +1,9 @@
 = Instance Principal
-
 :idprefix:
 :idseparator: -
 :sectlinks:
+:sectnums:
+:toc:
 
 :uri-repo: https://github.com/oracle/terraform-oci-terraform-oci-operator
 
@@ -43,11 +44,11 @@ When you enable this feature, by default, the operator host has privileges to ma
 
 You can also turn on and off the feature at any time without impact on the operator host.
 
-To enable, set operator_instance_principal to true:
+To enable, set enable_operator_instance_principal to true:
 
 [source,hcl]
 ----
-operator_instance_principal = true
+enable_operator_instance_principal = true
 ----
 
 and verify:
@@ -60,11 +61,11 @@ You should be able to see a list of VCNs created in the compartment.
 
 ==== Disabling instance_principal on the operator host
 
-To disable, set operator_instance_principal to false:
+To disable, set enable_operator_instance_principal to false:
 
 [source, hcl]
 ----
-operator_instance_principal = false
+enable_operator_instance_principal = false
 ----
 
 . Run terraform apply again:
diff --git a/docs/prerequisites.adoc b/docs/prerequisites.adoc
@@ -1,8 +1,9 @@
 = Pre-requisites
-
 :idprefix:
 :idseparator: -
 :sectlinks:
+:sectnums:
+:toc:
 
 :uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-operator
 
diff --git a/docs/quickstart.adoc b/docs/quickstart.adoc
@@ -1,8 +1,9 @@
 = Quickstart
-
 :idprefix:
 :idseparator: -
 :sectlinks:
+:sectnums:
+:toc:
 
 :uri-bastion: https://github.com/oracle-terraform-modules/terraform-oci-bastion
 :uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-operator
@@ -89,7 +90,7 @@ provider "oci" {
 
 . Optional parameters to override:
 
-* `operator_instance_principal`
+* `enable_operator_instance_principal`
 * `operator_shape`
 * `operator_upgrade`
 * `enable_operator_notification`
diff --git a/docs/terraformoptions.adoc b/docs/terraformoptions.adoc
@@ -3,8 +3,9 @@
 :idseparator: -
 :sectlinks:
 :sectnums:
-:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-operator
+:toc:
 
+:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-operator
 :uri-rel-file-base: link:{uri-repo}/blob/main
 :uri-rel-tree-base: link:{uri-repo}/tree/main
 
@@ -122,7 +123,7 @@ Ensure you review the {uri-terraform-dependencies}[dependencies].
 |imageid/Oracle
 |Oracle
 
-|`operator_instance_principal`
+|`enable_operator_instance_principal`
 |Whether to enable instance_principal on the operator.
 |true/false
 |false
diff --git a/instance_principal.tf b/instance_principal.tf
@@ -1,7 +1,7 @@
 # Copyright 2017, 2021 Oracle Corporation and/or affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
 
-resource "oci_identity_dynamic_group" "operator_instance_principal" {
+resource "oci_identity_dynamic_group" "enable_operator_instance_principal" {
   provider = oci.home
 
   compartment_id = var.tenancy_id
@@ -14,16 +14,16 @@ resource "oci_identity_dynamic_group" "operator_instance_principal" {
   matching_rule = "ALL {instance.id = '${join(",", data.oci_core_instance.operator.*.id)}'}"
   name          = "operator-instance-principal-${substr(uuid(), 0, 8)}"
 
-  count = var.operator_instance_principal == true ? 1 : 0
+  count = var.enable_operator_instance_principal == true ? 1 : 0
 }
 
-resource "oci_identity_policy" "operator_instance_principal" {
+resource "oci_identity_policy" "enable_operator_instance_principal" {
   provider = oci.home
 
   compartment_id = var.compartment_id
   description    = "policy to allow operator host to call services"
   name           = var.label_prefix == "none" ? "operator-instance-principal" : "${var.label_prefix}-operator-instance-principal"
-  statements     = ["Allow dynamic-group ${oci_identity_dynamic_group.operator_instance_principal[0].name} to manage all-resources in compartment id ${var.compartment_id}"]
+  statements     = ["Allow dynamic-group ${oci_identity_dynamic_group.enable_operator_instance_principal[0].name} to manage all-resources in compartment id ${var.compartment_id}"]
 
-  count = var.operator_instance_principal == true ? 1 : 0
+  count = var.enable_operator_instance_principal == true ? 1 : 0
 }
diff --git a/outputs.tf b/outputs.tf
@@ -5,8 +5,8 @@ output "operator_private_ip" {
   value = join(",", data.oci_core_vnic.operator_vnic.*.private_ip_address)
 }
 
-output "operator_instance_principal_group_name" {
-  value = var.operator_instance_principal == true ? oci_identity_dynamic_group.operator_instance_principal[0].name : null
+output "enable_operator_instance_principal_group_name" {
+  value = var.enable_operator_instance_principal == true ? oci_identity_dynamic_group.enable_operator_instance_principal[0].name : null
 }
 
 output "operator_subnet_id" {
diff --git a/terraform.tfvars.example b/terraform.tfvars.example
@@ -34,7 +34,7 @@ operating_system_version = "8"
 
 operator_image_id = "Oracle"
 
-operator_instance_principal = true
+enable_operator_instance_principal = true
 
 operating_os_version = "8"
 
diff --git a/variables.tf b/variables.tf
@@ -59,6 +59,11 @@ variable "vcn_id" {
 }
 
 # operator host parameters
+variable "enable_operator_instance_principal" {
+  description = "whether to enable instance_principal on the operator"
+  default     = false
+  type        = bool
+}
 
 variable "freeform_tags" {
   description = "Freeform tags for operator"
@@ -76,12 +81,6 @@ variable "operator_image_id" {
   type        = string
 }
 
-variable "operator_instance_principal" {
-  description = "whether to enable instance_principal on the operator"
-  default     = false
-  type        = bool
-}
-
 variable "operator_os_version" {
   description = "The version of the Oracle Linux to use."
   default     = "8"

Original file line number	Diff line number	Diff line change
`@@ -5,8 +5,8 @@ output "operator_private_ip" {`
`5`	`5`	`value = join(",", data.oci_core_vnic.operator_vnic.*.private_ip_address)`
`6`	`6`	`}`
`7`	`7`
`8`		`-output "operator_instance_principal_group_name" {`
`9`		`- value = var.operator_instance_principal == true ? oci_identity_dynamic_group.operator_instance_principal[0].name : null`
	`8`	`+output "enable_operator_instance_principal_group_name" {`
	`9`	`+ value = var.enable_operator_instance_principal == true ? oci_identity_dynamic_group.enable_operator_instance_principal[0].name : null`
`10`	`10`	`}`
`11`	`11`
`12`	`12`	`output "operator_subnet_id" {`