Debian Codegraph @

README.md

raw
1 # terraform-registry-address
2
3 This module enables parsing, comparison and canonical representation of
4 [Terraform Registry](https://registry.terraform.io/) **provider** addresses
5 (such as `registry.terraform.io/grafana/grafana` or `hashicorp/aws`)
6 and **module** addresses (such as `hashicorp/subnets/cidr`).
7
8 **Provider** addresses can be found in
9
10 - [`terraform show -json <FILE>`](https://www.terraform.io/internals/json-format#configuration-representation) (`full_name`)
11 - [`terraform version -json`](https://www.terraform.io/cli/commands/version#example) (`provider_selections`)
12 - [`terraform providers schema -json`](https://www.terraform.io/cli/commands/providers/schema#providers-schema-representation) (keys of `provider_schemas`)
13 - within `required_providers` block in Terraform configuration (`*.tf`)
14 - Terraform [CLI configuration file](https://www.terraform.io/cli/config/config-file#provider-installation)
15 - Plugin [reattach configurations](https://www.terraform.io/plugin/debugging#running-terraform-with-a-provider-in-debug-mode)
16
17 **Module** addresses can be found within `source` argument
18 of `module` block in Terraform configuration (`*.tf`)
19 and parts of the address (namespace and name) in the Registry API.
20
21 ## Compatibility
22
23 The module assumes compatibility with Terraform v0.12 and later,
24 which have the mentioned JSON output produced by corresponding CLI flags.
25
26 We recommend carefully reading the [ambigouous provider addresses](#Ambiguous-Provider-Addresses)
27 section below which may impact versions `0.12` and `0.13`.
28
29 ## Related Libraries
30
31 Other libraries which may help with consuming most of the above Terraform
32 outputs in automation:
33
34 - [`hashicorp/terraform-exec`](https://github.com/hashicorp/terraform-exec)
35 - [`hashicorp/terraform-json`](https://github.com/hashicorp/terraform-json)
36
37 ## Usage
38
39 ### Provider
40
41 ```go
42 pAddr, err := ParseProviderSource("hashicorp/aws")
43 if err != nil {
44 // deal with error
45 }
46
47 // pAddr == Provider{
48 // Type: "aws",
49 // Namespace: "hashicorp",
50 // Hostname: DefaultProviderRegistryHost,
51 // }
52 ```
53
54 ### Module
55
56 ```go
57 mAddr, err := ParseModuleSource("hashicorp/consul/aws//modules/consul-cluster")
58 if err != nil {
59 // deal with error
60 }
61
62 // mAddr == Module{
63 // Package: ModulePackage{
64 // Host: DefaultProviderRegistryHost,
65 // Namespace: "hashicorp",
66 // Name: "consul",
67 // TargetSystem: "aws",
68 // },
69 // Subdir: "modules/consul-cluster",
70 // },
71 ```
72
73 ## Other Module Address Formats
74
75 Modules can also be sourced from [other sources](https://www.terraform.io/language/modules/sources)
76 and these other sources (outside of Terraform Registry)
77 have different address formats, such as `./local` or
78 `github.com/hashicorp/example`.
79
80 This library does _not_ recognize such other address formats
81 and it will return error upon parsing these.
82
83 ## Ambiguous Provider Addresses
84
85 Qualified addresses with namespace (such as `hashicorp/aws`)
86 are used exclusively in all recent versions (`0.14+`) of Terraform.
87 If you only work with Terraform `v0.14.0+` configuration/output, you may
88 safely ignore the rest of this section and related part of the API.
89
90 There are a few types of ambiguous addresses you may comes accross:
91
92 - Terraform `v0.12` uses "namespace-less address", such as `aws`.
93 - Terraform `v0.13` may use `-` as a placeholder for the unknown namespace,
94 resulting in address such as `-/aws`.
95 - Terraform `v0.14+` _configuration_ still allows ambiguous providers
96 through `provider "<NAME>" {}` block _without_ corresponding
97 entry inside `required_providers`, but these providers are always
98 resolved as `hashicorp/<NAME>` and all JSON outputs only use that
99 resolved address.
100
101 Both ambiguous address formats are accepted by `ParseProviderSource()`
102
103 ```go
104 pAddr, err := ParseProviderSource("aws")
105 if err != nil {
106 // deal with error
107 }
108
109 // pAddr == Provider{
110 // Type: "aws",
111 // Namespace: UnknownProviderNamespace, // "?"
112 // Hostname: DefaultProviderRegistryHost, // "registry.terraform.io"
113 // }
114 pAddr.HasKnownNamespace() // == false
115 pAddr.IsLegacy() // == false
116 ```
117 ```go
118 pAddr, err := ParseProviderSource("-/aws")
119 if err != nil {
120 // deal with error
121 }
122
123 // pAddr == Provider{
124 // Type: "aws",
125 // Namespace: LegacyProviderNamespace, // "-"
126 // Hostname: DefaultProviderRegistryHost, // "registry.terraform.io"
127 // }
128 pAddr.HasKnownNamespace() // == true
129 pAddr.IsLegacy() // == true
130 ```
131
132 However `NewProvider()` will panic if you pass an empty namespace
133 or any placeholder indicating unknown namespace.
134
135 ```go
136 NewProvider(DefaultProviderRegistryHost, "", "aws") // panic
137 NewProvider(DefaultProviderRegistryHost, "-", "aws") // panic
138 NewProvider(DefaultProviderRegistryHost, "?", "aws") // panic
139 ```
140
141 If you come across an ambiguous address, you should resolve
142 it to a fully qualified one and use that one instead.
143
144 ### Resolving Ambiguous Address
145
146 The Registry API provides the safest way of resolving an ambiguous address.
147
148 ```sh
149 # grafana (redirected to its own namespace)
150 $ curl -s https://registry.terraform.io/v1/providers/-/grafana/versions | jq '(.id, .moved_to)'
151 "terraform-providers/grafana"
152 "grafana/grafana"
153
154 # aws (provider without redirection)
155 $ curl -s https://registry.terraform.io/v1/providers/-/aws/versions | jq '(.id, .moved_to)'
156 "hashicorp/aws"
157 null
158 ```
159
160 When you cache results, ensure you have invalidation
161 mechanism in place as target (migrated) namespace may change.
162
163 #### `terraform` provider
164
165 Like any other legacy address `terraform` is also ambiguous. Such address may
166 (most unlikely) represent a custom-built provider called `terraform`,
167 or the now archived [`hashicorp/terraform` provider in the registry](https://registry.terraform.io/providers/hashicorp/terraform/latest),
168 or (most likely) the `terraform` provider built into 0.11+, which is
169 represented via a dedicated FQN of `terraform.io/builtin/terraform` in 0.13+.
170
171 You may be able to differentiate between these different providers if you
172 know the version of Terraform.
173
174 Alternatively you may just treat the address as the builtin provider,
175 i.e. assume all of its logic including schema is contained within
176 Terraform Core.
177
178 In such case you should construct the address in the following way
179 ```go
180 pAddr := NewProvider(BuiltInProviderHost, BuiltInProviderNamespace, "terraform")
181 ```