.terraform-docs.yml

formatter: "markdown"

# Tested with this version
# As Majorversion is 0 any change may break
version: ">=0.16.0"

sections:
  hide:
    - header
    - providers

output:
  file: "README.md"
  mode: inject

sort:
  enabled: true
  by: required

content: |-
  {{- define "setDict" -}}
    {{- $resource := list -}}
    {{- if hasKey .Dict .Key -}}
      {{- $resource = get .Dict .Key -}}
    {{- else -}}
       {{- $resource = list -}}
    {{- end -}}
    {{- $resource := append $resource .Resource -}}
    {{- $_ := set .Dict .Key $resource -}}
  {{- end -}}
  
  {{- $filesResources := dict -}}
  {{- $resourceTypes := dict -}}
  {{- range .Module.Resources -}}
    {{- template "setDict" dict "Dict" $filesResources "Key" .Position.Filename "Resource" . -}}
    {{- $isResource := eq "resource" (printf "%s" .GetMode) -}}
    {{- if $isResource -}}
      {{- template "setDict" dict "Dict" $resourceTypes "Key" (printf "%s_%s" .ProviderName .Type) "Resource" . -}}
    {{- end -}}
  {{- end -}}
  
  # Project Module

  This module implements the creation and management of one GCP project including IAM, organization policies, Shared VPC host or service attachment, service API activation, and tag attachment.
  It also offers a convenient way to refer to managed service identities (aka robot service accounts) for APIs.

  ## Examples

  ### Basic

  This Module creates a GCP Project
  ```hcl
  {{ include "examples/basic/main.tf" }}
  {{ include "examples/basic/variables.tf" }}
  ```

  ### Cloud KMS encryption keys

  The module offers a simple, centralized way to assign `roles/cloudkms.cryptoKeyEncrypterDecrypter` to service identities.
  ```hcl
  {{ include "examples/crypto/main.tf" }}
  {{ include "examples/crypto/variables.tf" }}
  ```
  ### IAM

  IAM is managed via several variables that implement different levels of control:

  - `group_iam` and `iam` configure authoritative bindings that manage individual roles exclusively, mapping to the [`google_project_iam_binding`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_project_iam#google_project_iam_binding) resource
  - `iam_additive` and `iam_additive_members` configure additive bindings that only manage individual role/member pairs, mapping to the [`google_project_iam_member`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_project_iam#google_project_iam_member) resource

  Be mindful about service identity roles when using authoritative IAM, as you might inadvertently remove a role from a [service identity](https://cloud.google.com/iam/docs/service-accounts#google-managed) or default service account. For example, using `roles/editor` with `iam` or `group_iam` will remove the default permissions for the Cloud Services identity. A simple workaround for these scenarios is described below.
  ```hcl
  {{ include "examples/iam/main.tf" }}
  {{ include "examples/iam/variables.tf" }}
  ```

  ### Organization policies

  To manage organization policies, the `orgpolicy.googleapis.com` service should be enabled in the quota project.
  To use yaml config, it is required to create a yaml file with your configuration and add the org_policies_data_path variable.

  `configs/boolean.yaml`
  
  ```yaml
  {{ include "examples/organization_policies/configs/boolean.yaml" }}
  ``` 

  ```hcl
  {{ include "examples/organization_policies/main.tf" }}
  {{ include "examples/organization_policies/variables.tf" }}
  ```
  
  

  ### Shared VPC service

  The module allows managing Shared VPC status for both hosts and service projects, and includes a simple way of assigning Shared VPC roles to service identities.
  ```hcl
  {{ include "examples/shared_vpc/main.tf" }}
  {{ include "examples/shared_vpc/variables.tf" }}
  ```

  ### Logging Sinks

  This Module creates a GCP Project with sink for logging
  ```hcl
  {{ include "examples/sinks/main.tf" }}
  {{ include "examples/sinks/variables.tf" }}
  ```

  ### Tags

  Refer to the [Creating and managing tags](https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing) documentation for details on usage.
  ```hcl
  {{ include "examples/tags/main.tf" }}
  {{ include "examples/tags/variables.tf" }}
  ```

  {{ .Requirements }}
  {{ .Providers }}
  {{ .Inputs }}
  {{ .Outputs }}
  {{ if .Config.Sections.Resources -}}
    {{- if not (keys $resourceTypes) -}}
        {{- if not .Config.Settings.HideEmpty -}}
            {{- indent 0 "#" }} Resource types
            No resources.
        {{ end }}
      {{ else }}
        {{ indent 0 "#" }} Resource types
        | Type | Used |
        |------|-------|
        {{- range $type,$resources := $resourceTypes }}
          {{- $url := (first $resources).URL -}}
          {{- $type = ternary $url (printf "[%s](%s)" $type $url) $type }}
          | {{ $type }} | {{ len $resources }} |
        {{- end }}
        **`Used` only includes resource blocks.** `for_each` and `count` meta arguments, as well as resource blocks of modules are not considered.
      {{ end }}
  {{ end -}}
  {{ .Modules }}
  {{ if or .Config.Sections.Resources .Config.Sections.DataSources -}}
      {{- if not (keys $filesResources) -}}
          {{- if not .Config.Settings.HideEmpty -}}
              {{ indent 0 "#" }} Resources by Files
              No resources.
          {{ end }}
      {{ else }}
          {{ indent 0 "#" }} Resources by Files
          {{- range $fileName,$resources := $filesResources }}
              {{ indent 1 "#" }} {{ $fileName }}
              | Name | Type |
              |------|------|
              
              {{- range $resources -}}
                {{- $isResource := and $.Config.Sections.Resources ( eq "resource" (printf "%s" .GetMode)) }}
                {{- $isDataResource := and $.Config.Sections.DataSources ( eq "data source" (printf "%s" .GetMode)) }}
                {{- if or $isResource $isDataResource }}
                    {{- $fullspec := ternary .URL (printf "[%s](%s)" .Spec .URL) .Spec }}
                    | {{ $fullspec }} | {{ .GetMode }} |
                {{- end }}
              {{- end -}}
          {{- end }}
      {{ end }}
  {{- end -}}

  ## Contribute

  This module is derived from [google cloud foundation fabric module `project` v19](https://github.com/GoogleCloudPlatform/cloud-foundation-fabric/tree/v19.0.0/modules/project).
  Refer to [guide in `terraform-google-landing-zone` repository](https://github.com/qbeyond/terraform-google-landing-zone/tree/main#updating-a-repository) for information on integrating changes.