Document the "host" block type in CLI configuration

[Packetslave]

Problem: We run an internal module registry to serve modules to our users. We want them to be able to use a short easily-remembered domain when specifying these modules, but (because $REASONS) it's non-trivial for us to setup service discovery on that domain.

After doing some spelunking through the terraform code, we discovered that you can override service discovery using host entries in terraformrc:

host "fb.com" {
  services = {
    "providers.v1" = "https://tf-registry-vip.internal/",
    "modules.v1" = "https://tf-registry-vip.internal/",
  }
}

However, this seems to be undocumented (and presumably unsupported). Is it possible to change this? This seems like it would fit our use case nicely, but we don't want to rely on undocumented functionality.

[apparentlymart]

Hi @Packetslave,

We have this here primarily as a development tool to allow us to mock out the "real" services when testing things, but indeed I suppose in a pinch you could use it "in production" if you know you'll only ever be running Terraform in a fixed set of locations where you can pre-configure this block.

I think it's mainly undocumented just because it didn't seem important enough to spend time writing the docs for it. I don't see any reason why it shouldn't be documented, because we don't have any intent to break or remove it.

Given that it should be a pretty rarely-used mechanism, I think I'd lean towards having the main documentation about it live in a new section at the end of the page about Remote Service Discovery Protocol, since it's an additional detail of what's already described there in "Discovery Process", and then we can link to that from the list under "Available Settings" on the CLI configuration page, so it's discoverable as part of that file format without adding a bunch more text to a page that is already arguably a bit too long. 😀

I'll try to get that updated next time I'm in the neighborhood of service-discovery-related documentation. In the mean time, feel free to use host blocks for any hostname that's under your control, where you'll therefore know if the encoded service endpoint URLs need to change and can make it so.

For completeness, in case someone else sees this and has some other related ideas, I just want to note that using it for other people's hostnames, especially the common ones registry.terraform.io and app.terraform.io, would likely be a mistake because you'd freeze in place the current endpoint URLs. The primary purpose of this service discovery mechanism is to allow the specific service endpoint URLs to change over time as implementation details change, and so the discovery documents on other people's hostnames are subject to change at any time, without any explicit notice.