| 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 |
``` |