github.com/hugorut/terraform@v1.1.3/website/docs/internals/remote-service-discovery.mdx (about)

     1  ---
     2  page_title: 'Internals: Remote Service Discovery'
     3  description: |-
     4    Remote service discovery is a protocol used to locate Terraform-native
     5    services provided at a user-friendly hostname.
     6  ---
     7  
     8  # Remote Service Discovery
     9  
    10  Terraform implements much of its functionality in terms of remote services.
    11  While in many cases these are generic third-party services that are useful
    12  to many applications, some of these services are tailored specifically to
    13  Terraform's needs. We call these _Terraform-native services_, and Terraform
    14  interacts with them via the remote service discovery protocol described below.
    15  
    16  ## User-facing Hostname
    17  
    18  Terraform-native services are provided, from a user's perspective, at a
    19  user-facing "friendly hostname" which serves as the key for configuration and
    20  for any authentication credentials required.
    21  
    22  The discovery protocol's purpose is to map from a user-provided hostname to
    23  the base URL of a particular service. Each host can provide different
    24  combinations of services -- or no services at all! -- and so the discovery
    25  protocol has a secondary purpose of allowing Terraform to identify _which_
    26  services are valid for a given hostname.
    27  
    28  For example, module source strings can include a module registry hostname
    29  as their first segment, like `example.com/namespace/name/provider`, and
    30  Terraform uses service discovery to determine whether `example.com` _has_
    31  a module registry, and if so where its API is available.
    32  
    33  A user-facing hostname is a fully-specified
    34  [internationalized domain name](https://en.wikipedia.org/wiki/Internationalized_domain_name)
    35  expressed in its Unicode form (the corresponding "punycode" form is not allowed)
    36  which must be resolvable in DNS to an address that has an HTTPS server running
    37  on port 443.
    38  
    39  User-facing hostnames are normalized for internal comparison using the
    40  standard Unicode [Nameprep](https://en.wikipedia.org/wiki/Nameprep) algorithm,
    41  which includes converting all letters to lowercase, normalizing combining
    42  diacritics to precomposed form where possible, and various other normalization
    43  steps.
    44  
    45  ## Discovery Process
    46  
    47  Given a hostname, discovery begins by forming an initial discovery URL
    48  using that hostname with the `https:` scheme and the fixed path
    49  `/.well-known/terraform.json`.
    50  
    51  For example, given the hostname `example.com` the initial discovery URL
    52  would be `https://example.com/.well-known/terraform.json`.
    53  
    54  Terraform then sends a `GET` request to this discovery URL and expects a
    55  JSON response. If the response does not have status 200, does not have a media
    56  type of `application/json` or, if the body cannot be parsed as a JSON object,
    57  then discovery fails and Terraform considers the host to not support _any_
    58  Terraform-native services.
    59  
    60  If the response is an HTTP redirect then Terraform repeats this step with the
    61  new location as its discovery URL. Terraform is guaranteed to follow at least
    62  one redirect, but nested redirects are not guaranteed nor recommended.
    63  
    64  If the response is a valid JSON object then its keys are Terraform native
    65  service identifiers, consisting of a service type name and a version string
    66  separated by a period. For example, the service identifier for version 1 of
    67  the module registry protocol is `modules.v1`.
    68  
    69  The value of each object element is the base URL for the service in question.
    70  This URL may be either absolute or relative, and if relative it is resolved
    71  against the final discovery URL (_after_ following redirects).
    72  
    73  The following is an example discovery document declaring support for
    74  version 1 of the module registry protocol:
    75  
    76  ```json
    77  {
    78    "modules.v1": "https://modules.example.com/v1/"
    79  }
    80  ```
    81  
    82  ## Supported Services
    83  
    84  At present, the following service identifiers are in use:
    85  
    86  * `login.v1`: [login protocol version 1](/cli/commands/login)
    87  * `modules.v1`: [module registry API version 1](/internals/module-registry-protocol)
    88  * `providers.v1`: [provider registry API version 1](/internals/provider-registry-protocol)
    89  
    90  ## Authentication
    91  
    92  If credentials for the given hostname are available in
    93  [the CLI config](/cli/config/config-file) then they will be included
    94  in the request for the discovery document.
    95  
    96  The credentials may also be provided to endpoints declared in the discovery
    97  document, depending on the requirements of the service in question.
    98  
    99  ## Non-standard Ports in User-facing Hostnames
   100  
   101  It is strongly recommended to provide the discovery document for a hostname
   102  on the standard HTTPS port 443. However, in development environments this is
   103  not always possible or convenient, so Terraform allows a hostname to end
   104  with a port specification consisting of a colon followed by one or more
   105  decimal digits.
   106  
   107  When a custom port number is present, the service on that port is expected to
   108  implement HTTPS and respond to the same fixed discovery path.
   109  
   110  For day-to-day use it is strongly recommended _not_ to rely on this mechanism
   111  and to instead provide the discovery document on the standard port, since this
   112  allows use of the most user-friendly hostname form.