Merge pull request #9 from terraform-google-modules/ludo-fabric-outputs

Adopt the same output strategy as for the GCS and SA modules

Author: ludoo

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [2.0.0] - 2019-08-16
+
+### Changed
+- Deprecate the `parent_id` and `parent_type` variables in favor of a single `parent` variable [#8]
+- Change outputs to follow the same conventions used in the `cloud-storage` and `service-accounts` modules ([migration instructions](docs/upgrading_to_folders_v2.0.md)) [#9]
+  - Rename map outputs dropping the `names_and_` prefix
+  - Add resource outputs
+  - Add single use outputs
+  - Add list-style outputs
+  
 ## [1.0.0] - 2019-07-26
 
 ### Changed

README.md

@@ -66,8 +66,14 @@ Functional examples are included in the
 
 | Name | Description |
 |------|-------------|
-| names\_and\_display\_names | Map of name => folder resource name. |
-| names\_and\_ids | Map of name => folder resource id. |
+| folder | Folder resource (for single use). |
+| folders | Folder resources. |
+| id | Folder id (for single use). |
+| ids | Folder ids. |
+| ids\_list | List of folder ids. |
+| name | Folder name (for single use). |
+| names | Folder names. |
+| names\_list | List of folder names. |
 
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 

docs/upgrading_to_folders_v2.0.md

@@ -0,0 +1,53 @@
+# Upgrading to Folders v2.0 (from v1.X)
+
+The v2.0 release of the Folders module is a backwards incompatible release, with two important sets of changes:
+
+- the `parent_id` and `parent_type` variables have now been combined into a single `parent` variable
+- module outputs have changed to bring them in line with other modules
+
+## Migration Instructions
+
+### Single parent variable
+
+The folder parent is now specificied using a single `parent` variable, that uses the full resource id path.
+
+To create folders at the organization level, prefix the organization id with `organizations/`:
+
+`parent = "organizations/0123456789"`
+
+To create folders under an existing folder, prefix the existing folder id with `folders/`:
+
+`parent = "folders/0123456789"`
+
+### Rename map-style outputs
+
+The `names_and_display_names` and `names_and_ids` outputs have been deprecated, and new ones are available in their place that expose the same data:
+
+- `names_and_display_names` is now `names`
+- `names_and_ids` is now `ids`
+
+### Leverage new output types
+
+New output types have also been added that leverage new Terraform 0.12 features or facilitate specific use cases. They are describe below.
+
+#### Folder resources
+
+Terraform 0.12 makes it possible to expose complete resources alongside their attributes, so two new outputs have been added:
+
+- `folder` is the first folder resource for single folder creation use cases
+- `folders` are all the folder resources as a list
+
+#### Single folder use
+
+When managing a single folder per module invocation, new outputs are available that directly expose its attributes:
+
+- `folder` is the complete folder resource described above
+- `name` is a string output containing the display name of the folder, eg `"Test"`
+- `id` is a string output containing the numeric id of the folder, eg `"folders/12345"`
+
+#### Lists
+
+New list outputs have been added to expose folder attributes and preserve the ordering of the `names` variable, as maps reorder keys lexically and might introduce subtle bugs when used as lists through `values`:
+
+- `names_list` is the list of folder display names as strings
+- `ids_list` is the list of folder ids as strings

examples/simple_example/README.md

@@ -17,7 +17,9 @@ This example illustrates how to use the `folders` module.
 
 | Name | Description |
 |------|-------------|
-| names\_and\_ids | Map of name => folder resource id. |
+| ids | Folder ids. |
+| ids\_list | List of folder ids. |
+| names | Folder names. |
 
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 

examples/simple_example/outputs.tf

@@ -14,8 +14,17 @@
  * limitations under the License.
  */
 
-output "names_and_ids" {
-  description = "Map of name => folder resource id."
-  value       = module.folders.names_and_ids
+output "ids" {
+  description = "Folder ids."
+  value       = module.folders.ids
 }
 
+output "names" {
+  description = "Folder names."
+  value       = module.folders.names
+}
+
+output "ids_list" {
+  description = "List of folder ids."
+  value       = module.folders.ids_list
+}

outputs.tf

@@ -14,13 +14,42 @@
  * limitations under the License.
  */
 
-output "names_and_display_names" {
-  description = "Map of name => folder resource name."
-  value       = zipmap(var.names, google_folder.folders.*.display_name)
+output "folder" {
+  description = "Folder resource (for single use)."
+  value       = google_folder.folders[0]
 }
 
-output "names_and_ids" {
-  description = "Map of name => folder resource id."
-  value       = zipmap(var.names, google_folder.folders.*.name)
+output "id" {
+  description = "Folder id (for single use)."
+  value       = google_folder.folders[0].name
 }
 
+output "name" {
+  description = "Folder name (for single use)."
+  value       = google_folder.folders[0].display_name
+}
+
+output "folders" {
+  description = "Folder resources."
+  value       = google_folder.folders
+}
+
+output "ids" {
+  description = "Folder ids."
+  value       = zipmap(var.names, google_folder.folders[*].name)
+}
+
+output "names" {
+  description = "Folder names."
+  value       = zipmap(var.names, google_folder.folders[*].display_name)
+}
+
+output "ids_list" {
+  description = "List of folder ids."
+  value       = google_folder.folders[*].name
+}
+
+output "names_list" {
+  description = "List of folder names."
+  value       = google_folder.folders[*].display_name
+}

test/fixtures/simple_example/outputs.tf

@@ -14,9 +14,14 @@
  * limitations under the License.
  */
 
-output "names_and_ids" {
-  description = "Map of name => folder resource id."
-  value       = module.example.names_and_ids
+output "names" {
+  description = "Folder names."
+  value       = module.example.names
+}
+
+output "ids_list" {
+  description = "List of folder ids."
+  value       = module.example.ids_list
 }
 
 output "parent_id" {
@@ -29,11 +34,6 @@ output "parent_type" {
   value       = var.parent_type
 }
 
-output "names" {
-  description = "Folder names."
-  value       = var.names
-}
-
 output "per_folder_admins" {
   description = "List of IAM-style members per folder who will get extended permissions."
   value       = var.per_folder_admins

test/integration/simple_example/controls/gcloud.rb

@@ -18,38 +18,21 @@
   describe command("gcloud resource-manager folders list --folder=#{attribute("parent_id")}") do
     its(:exit_status) { should eq 0 }
     its(:stderr) { should eq "" }
-    its(:stdout) { should include "#{attribute("names")[0]}" }
-    its(:stdout) { should include "#{attribute("names")[1]}" }
-    its(:stdout) { should include "#{attribute("names")[2]}" }
+    its(:stdout) { should include "#{attribute("names").values[0]}" }
+    its(:stdout) { should include "#{attribute("names").values[1]}" }
+    its(:stdout) { should include "#{attribute("names").values[2]}" }
   end
 
   folder_names = attribute("names")
-  folder_names_and_ids   = attribute("names_and_ids")
+  folder_ids = attribute("ids_list")
   per_folder_admins = attribute("per_folder_admins")
 
-  folder_id = folder_names_and_ids[folder_names[0]]
-  folder_admin = per_folder_admins[0]
-  describe command("gcloud alpha resource-manager folders get-iam-policy #{folder_id}") do
-    its(:exit_status) { should eq 0 }
-    its(:stderr) { should eq "" }
-    its(:stdout) { should include "#{attribute("per_folder_admins")[0]}" }
-  end
-
-
-  folder_id = folder_names_and_ids[folder_names[1]]
-  folder_admin = per_folder_admins[1]
-  describe command("gcloud alpha resource-manager folders get-iam-policy #{folder_id}") do
-    its(:exit_status) { should eq 0 }
-    its(:stderr) { should eq "" }
-    its(:stdout) { should include "#{attribute("per_folder_admins")[1]}" }
-  end
-
-  folder_id = folder_names_and_ids[folder_names[2]]
-  folder_admin = per_folder_admins[2]
-  describe command("gcloud alpha resource-manager folders get-iam-policy #{folder_id}") do
-    its(:exit_status) { should eq 0 }
-    its(:stderr) { should eq "" }
-    its(:stdout) { should include "#{attribute("per_folder_admins")[2]}" }
+  (0..2).each do |i|
+    describe command("gcloud alpha resource-manager folders get-iam-policy #{folder_ids[i]}") do
+      its(:exit_status) { should eq 0 }
+      its(:stderr) { should eq "" }
+      its(:stdout) { should include per_folder_admins[i] }
+    end
   end
 
 end

test/integration/simple_example/inspec.yml

@@ -8,11 +8,14 @@ attributes:
     required: true
     type: string
   - name: names
+    required: true
+    type: hash
+  - name: ids_list
     required: true
     type: array
-  - name: names_and_ids
+  - name: per_folder_admins
     required: true
-    type: hash
+    type: array
   - name: per_folder_admins
     required: true
-    type: array
+    type: array