Update Documentation (#21)

- add missing description for outputs
- remove uncorrect module version from examples (Issue #18)
- fix typo in example/main.tf for iam_dynamic_group module source path (Issue #19)
- fix explanation of `enable_delete` argument behaviour in modules/iam-compartment documentation (Issue #20)

Author: kral2

CHANGELOG.md

@@ -11,6 +11,19 @@ Given a version number MAJOR.MINOR.PATCH:
 - MINOR version when adding functionality in a backwards compatible manner,
 - PATCH version when making backwards compatible bug fixes.
 
+## [2.0.1] - 2021-02-09
+
+### Fixed
+
+- missing description for outputs
+- Remove uncorrect module version from examples (Issue #18)
+- typo in examples/main.tf for iam_dynamic_group module source path (Issue #19)
+- explanation of `enable_delete` argument behaviour in modules/iam-compartment documentation (Issue #20)
+
+### Changed
+
+- no more version pinning in examples to keep documentation current, but add a note on how to do it for production code.
+
 ## [2.0.0] - 2021-01-27
 
 ### Added

LICENSE

@@ -1,23 +1,42 @@
-// Copyright (c) 2018, 2021, Oracle and/or its affiliates.
+Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 
 This software is dual-licensed to you under the Universal Permissive License (UPL) or Apache License 2.0. See below for license terms. You may choose either license.
 ____________________________
 The Universal Permissive License (UPL), Version 1.0
-// Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 
-Subject to the condition set forth below, permission is hereby granted to any person obtaining a copy of this software, associated documentation and/or data (collectively the "Software"), free of charge and under any and all copyright rights in the Software, and any and all patent rights owned or freely licensable by each licensor hereunder covering either (i) the unmodified Software as contributed to or provided by such licensor, or (ii) the Larger Works (as defined below), to deal in both
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
 
 (a) the Software, and
-(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if one is included with the Software (each a "Larger Work" to which the Software is contributed by such licensors),
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
 
-without restriction, including without limitation the rights to copy, create derivative works of, display, perform, and distribute the Software and make, use, sell, offer for sale, import, export, have made, and have sold the Software and the Larger Work(s), and to sublicense the foregoing rights on either these or other terms.
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
 
 This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 
-The above copyright notice and either this complete permission notice or at a minimum a reference to the UPL must be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
+____________________________
 The Apache Software License, Version 2.0
 // Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 
@@ -80,4 +99,3 @@ END OF TERMS AND CONDITIONS
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-   

examples/README.md

@@ -25,13 +25,13 @@ All resources created by this example can be deleted by using the `terraform des
 > terraform init
 ```
 
-- Inspect what Terraform plans to do before actually doing it:
+- Inspect what Terraform plans to do for the next `apply`:
 
 ```bash
 > terraform plan
 ```
 
-- If proposed changes are what waas intended, apply the plan to Provision resources on OCI (if not abort the operation and review the configuration):
+- If proposed changes are what is intended, apply the current plan to Provision resources on OCI (if not, abort the operation and review the configuration):
 
 ```bash
 > terraform apply

examples/main.tf

@@ -39,9 +39,9 @@ provider "oci" {
  */
 
 module "iam_compartment" {
-
   source                  = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
-  version                 = "2.1.1"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid            = var.tenancy_ocid
   compartment_id          = var.tenancy_ocid # define the parent compartment. Creation at tenancy root if omitted
   compartment_name        = "tf_example_compartment"
@@ -52,7 +52,8 @@ module "iam_compartment" {
 
 module "iam_subcompartment1" {
   source                  = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
-  version                 = "2.1.1"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid            = var.tenancy_ocid
   compartment_id          = module.iam_compartment.compartment_id # define the parent compartment. Here we make reference to the previous module
   compartment_name        = "tf_example_subcompartment1"
@@ -63,7 +64,8 @@ module "iam_subcompartment1" {
 
 module "iam_subcompartment2" {
   source                  = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
-  version                 = "2.1.1"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid            = var.tenancy_ocid
   compartment_id          = module.iam_compartment.compartment_id # define the parent compartment. Here we make reference to the previous module
   compartment_name        = "tf_example_subcompartment2"
@@ -74,7 +76,8 @@ module "iam_subcompartment2" {
 
 module "iam_users" {
   source       = "oracle-terraform-modules/iam/oci//modules/iam-user"
-  version      = "2.1.1"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version       = "x.x.x"
   tenancy_ocid = var.tenancy_ocid
   users = [
     { # user1
@@ -97,7 +100,7 @@ module "iam_users" {
 
 module "iam_group" {
   source                = "oracle-terraform-modules/iam/oci//modules/iam-group"
-  version               = "2.1.1"
+  version               = "2.0.0"
   tenancy_ocid          = var.tenancy_ocid
   group_name            = "tf_example_group"
   group_description     = "an example group - terraformed"
@@ -112,8 +115,9 @@ module "iam_group" {
 }
 
 module "iam_dynamic_group" {
-  source                    = "oracle-terraform-modules/iam/oci//modules/iam-group"
-  version                   = "2.1.1"
+  source                    = "oracle-terraform-modules/iam/oci//modules/iam-dyanmic-group"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid              = var.tenancy_ocid
   dynamic_group_name        = "tf_example_dynamic_group"
   dynamic_group_description = "dynamic group created by terraform"

modules/iam-compartment/README.md

@@ -4,14 +4,18 @@ This [Terraform module](https://www.terraform.io/docs/modules/index.html) allows
 
 With the `enable_delete` argument (boolean: `true` or `false`), you can control the `terraform destroy` command behavior:
 
-- `true`: terraform will only remove the compartment from the configuration (the actual OCI resource is not deleted, only the terraform representation is deleted
-- `false`: terraform will actually delete the compartment from OCI.
+- `true`: terraform will actually delete the compartment from OCI.
+- `false`: terraform will only remove the compartment from the configuration (the actual OCI resource is not deleted, only the terraform representation is deleted
 
 Below is the typical module block you should add to your configuration to create a compartment with this module.
 
+**IMPORTANT:** There is no version pinning of modules in the examples to lower documentation maintenance when releasing new module versions. It is a good practice to pin the module version to the exact version you are using in your code so that your infrastructure remains stable and predictible.
+
 ```hcl
 module "iam_compartment" {
   source                  = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid            = var.tenancy_ocid
   compartment_id          = var.tenancy_ocid
   compartment_name        = "tf_example_compartment"
@@ -29,6 +33,8 @@ The argument `compartment_id` defines the parent compartment of the defined comp
 ```hcl
 module "iam_subcompartment" {
   source                  = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid            = var.tenancy_ocid
   compartment_id          = module.iam_compartment.compartment_id
   compartment_name        = "tf_example_subcompartment"

modules/iam-compartment/outputs.tf

@@ -1,19 +1,23 @@
 // Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 
 output "compartment_id" {
+  description = "Compartment ocid"
   // This allows the compartment ID to be retrieved from the resource if it exists, and if not to use the data source.
   value = var.compartment_create ? element(concat(oci_identity_compartment.this.*.id, list("")), 0) : lookup(local.compartment_ids[0], "id")
 }
 
 output "parent_compartment_id" {
+  description = "Parent Compartment ocid"
   // This allows the compartment ID to be retrieved from the resource if it exists, and if not to use the data source.
   value = var.compartment_create ? element(concat(oci_identity_compartment.this.*.compartment_id, list("")), 0) : lookup(local.parent_compartment_ids[0], "compartment_id")
 }
 
 output "compartment_name" {
+  description = "Compartment name"
   value = var.compartment_name
 }
 
 output "compartment_description" {
+  description = "Compartment description"
   value = var.compartment_description
 }

modules/iam-dynamic-group/README.md

@@ -4,9 +4,15 @@ This [Terraform module](https://www.terraform.io/docs/modules/index.html) define
 
 * add an OCI IAM policy for this dynamic group. [See How Policies Work](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policies.htm) and [Common Policies](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/commonpolicies.htm) for more information regarding the policy syntax.
 
+Below is the typical module block you should add to your configuration to create a compartment with this module.
+
+**IMPORTANT:** There is no version pinning of modules in the examples to lower documentation maintenance when releasing new module versions. It is a good practice to pin the module version to the exact version you are using in your code so that your infrastructure remains stable and predictible.
+
 ```hcl
 module "iam_dynamic_group" {
   source                    = "oracle-terraform-modules/iam/oci//modules/iam-dynamic-group"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid              = "${var.tenancy_ocid}"
   dynamic_group_name        = "tf_example_dynamic_group"
   dynamic_group_description = "dynamic group created by terraform"

modules/iam-dynamic-group/outputs.tf

@@ -1,17 +1,20 @@
 // Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 
 output "dynamic_group_id" {
+  description = "Dynamic Group ocid"
   value = var.dynamic_group_create ? element(concat(oci_identity_dynamic_group.this.*.id, list("")), 0) : lookup(local.dynamic_group_ids[0], "id")
 }
 
 output "dynamic_group_name" {
+  description = "Dynamic Group name"
   value = var.dynamic_group_name
 }
 
 output "name_ocid" {
   value       = zipmap(oci_identity_dynamic_group.this[*].name, oci_identity_dynamic_group.this[*].id)
-  description = "group name and associated OCID"
+  description = "Dynamic Group name and associated OCID"
 }
 output "dynamic_group_policy_name" {
+  description = "Dynamic Group policy name"
   value = var.policy_name
 }

modules/iam-group/README.md

@@ -5,12 +5,15 @@ This [Terraform module](https://www.terraform.io/docs/modules/index.html) define
 * add a list of users as member to the created group,
 * add an OCI IAM policy. [See How Policies Work](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policies.htm) and [Common Policies](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/commonpolicies.htm) for more information regarding the policy syntax.
 
-Below is the typical module block you should add to your configuration to create a group with this module.
+Below is the typical module block you should add to your configuration to create a compartment with this module.
+
+**IMPORTANT:** There is no version pinning of modules in the examples to lower documentation maintenance when releasing new module versions. It is a good practice to pin the module version to the exact version you are using in your code so that your infrastructure remains stable and predictible.
 
 ```hcl
 module "iam_group" {
   source                = "oracle-terraform-modules/iam/oci//modules/iam-group"
-  version         = "2.1.1"
+  # Pinning each module to a specific version is highly advisable. Please adjust and uncomment the line below
+  # version               = "x.x.x"
   tenancy_ocid          = var.tenancy_ocid # required
   group_name            = "tf_example_group"  # required
   group_description     = "an example group - terraformed"  # required

modules/iam-group/outputs.tf

@@ -1,10 +1,12 @@
 // Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 
 output "group_id" {
+  description = "Group ocid"
   value = var.group_create ? element(concat(oci_identity_group.this.*.id, list("")), 0) : lookup(local.group_ids[0], "id")
 }
 
 output "group_name" {
+  description = "Group name"
   value = var.group_name
 }
 
@@ -14,9 +16,11 @@ output "name_ocid" {
 }
 
 output "group_description" {
+  description = "Group description"
   value = var.group_description
 }
 
 output "group_policy_name" {
+  description = "Group policy name"
   value = var.policy_name
 }