Skip to content

Instantly share code, notes, and snippets.

@pkolyvas

pkolyvas/installer.md

Forked from mildwonkey/installer.md
Created May 15, 2020 20:40
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save pkolyvas/1a49a402f152156060877077289950a2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save pkolyvas/1a49a402f152156060877077289950a2 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @mildwonkey mildwonkey revised this gist May 15, 2020. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -52,6 +52,7 @@ A major implication of the provider source work is that terraform can no longer
    #### Filesystem search paths

    Default:
    * `.terraform.d/plugins` relative to the CLI configuration directory (configurable, defaults to `$HOME/`)
    * `terraform.d/plugins` in the current working directory (documented in `terraform-bundle` as a place to put plugins as a way to include them in bundles uploaded to Terraform Cloud)
    * `.terraform/plugins` relative to configuration for any already-installed plugins

  2. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 4 additions and 1 deletion.
    5 changes: 4 additions & 1 deletion installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -4,6 +4,9 @@
    Terraform 0.13 has an entirely new provider installer that allows for greater control over individual provider installation methods. The breaking change is a new, *required*, subdirectory hierarchy for provider binaries.

    ## Terraform v0.12
    <details>
    <summary>Terraform v0.12 Provider Installer </summary>

    The key differences between Terraform v0.12 and v0.13 are the directory hierarchy. Terraform v0.12 would look for a provider binary under the following directories:

    ### Search
    @@ -33,7 +36,7 @@ Default:
    Options:
    - `-plugin-cache-dir`: does not change search paths; installs providers into the specified directory

    Install from registry if not found
    </details>

    ## Terraform v0.13

  3. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -70,7 +70,7 @@ OS-specific paths:

    #### Registry lookup
    Same use-facing behavior as 0.12: terraform queries the registry to find providers.
    If a provider is found in one of the search paths, terraform will **not** query the registry for that provider (TODO: check that `-upgrade` overrides that as expected).
    If a provider is found in one of the search paths, terraform will **not** query the registry for that provider (unless the `-upgrade` command line flag is used).


    ### CLI configuration settings
  4. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 22 additions and 10 deletions.
    32 changes: 22 additions & 10 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -6,15 +6,25 @@ Terraform 0.13 has an entirely new provider installer that allows for greater co
    ## Terraform v0.12
    The key differences between Terraform v0.12 and v0.13 are the directory hierarchy. Terraform v0.12 would look for a provider binary under the following directories:

    ### Search
    ### Search
    1. Filesystem
    1. Terraform Registry

    #### Filesystem search paths
    - **Windows**: `%APPDATA%\terraform.d\plugins`
    - **All others**: `~/.terraform.d/plugins`
    - Location of the terraform binary (/usr/local/bin, for example)
    - `terraform.d/plugins/<OS>_<ARCH>` For airgapped installations; see `terraform-bundle`
    - Registry lookup (tf does not query the registry for providers found locally unless `-upgrade` flag is true)

    The following command-line option is available to override the default search location:
    #### Registry lookup
    Terraform queries the Registry for providers:
    - if a compatible provider is *not* found locally
    - unless the `-upgrade` flag is set

    #### Configuration Options
    - `-plugin-dir`: disables registry lookup; only search that directory (note: still searches `.terraform/plugins` for already-installed providers)
    - `plugin-cache-dir`: search and install providers to the configured directory. Terraform will search other locations, including the registry, as usual.
    - `-upgrade`: query the registry for all providers required by the local configuration and install the latest matching version.

    ### Installation
    Default:
    @@ -53,20 +63,22 @@ OS-specific paths:
    will use `~/.local/share/terraform/plugins`,
    `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`.

    Options:
    - `-plugin-dir` command-line flag: *only* that directory will be searched (no registry lookup). Command-line options override any CLI configuration file options.
    #### Configuration Options
    - `-plugin-dir` command-line flag: *only* that directory will be searched (no registry lookup). Command-line options override CLI configuration file options.
    - `plugin-cache-dir`: search and install providers to the configured directory. Terraform will search other locations, including the registry, as usual.
    - `-upgrade`: query the registry for all providers required by the local configuration and install the latest matching version.

    #### Registry lookup
    Same use-facing behavior as 0.12: terraform queries the registry to find providers.
    If a provider is found in one of the search paths, terraform will **not** query the registry for that provider (TODO: check that `-upgrade` overrides that as expected).


    ### Cli config options
    We've added a CLI configuration setting to let users declare plugin search locations for all configurations on a given workstation. These settings override the default behavior.
    ### CLI configuration settings
    We've added a CLI configuration setting, `provider_installtion`, to let users declare plugin search locations for all configurations on a given workstation. This setting overrides the default behavior.

    1. `filesystem_mirror`: used to declare custom local filesystems
    1. `direct`: used to configure the registry provider search behavior
    1. `network_mirror`: used to declare custom network filesystems [targeting future 0.13.* release]
    * `filesystem_mirror`: used to declare custom local filesystems
    * `direct`: used to configure the registry provider search behavior
    * `network_mirror`: used to declare custom network filesystems [targeting future 0.13.* release]

    ## Installation
    Default:
  5. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 1 addition and 3 deletions.
    4 changes: 1 addition & 3 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -54,9 +54,7 @@ OS-specific paths:
    `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`.

    Options:
    - `-plugin-dir` command-line flag: *only* that directory will be searched (no registry lookup)

    Q: does this override CLI config?
    - `-plugin-dir` command-line flag: *only* that directory will be searched (no registry lookup). Command-line options override any CLI configuration file options.

    #### Registry lookup
    Same use-facing behavior as 0.12: terraform queries the registry to find providers.
  6. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 4 additions and 4 deletions.
    8 changes: 4 additions & 4 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -64,11 +64,11 @@ If a provider is found in one of the search paths, terraform will **not** query


    ### Cli config options
    We've added a CLI configuration setting to let users declare plugin search locations for all configurations on a given workstation.
    We've added a CLI configuration setting to let users declare plugin search locations for all configurations on a given workstation. These settings override the default behavior.

    1. `filesystem_mirror`
    1. `direct`
    1. `network_mirror` [targeting future 0.13.* release]
    1. `filesystem_mirror`: used to declare custom local filesystems
    1. `direct`: used to configure the registry provider search behavior
    1. `network_mirror`: used to declare custom network filesystems [targeting future 0.13.* release]

    ## Installation
    Default:
  7. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -14,7 +14,7 @@ The key differences between Terraform v0.12 and v0.13 are the directory hierarch
    - Registry lookup (tf does not query the registry for providers found locally unless `-upgrade` flag is true)

    The following command-line option is available to override the default search location:
    - `-plugin-dir`: disables registry lookup; only search that directory
    - `-plugin-dir`: disables registry lookup; only search that directory (note: still searches `.terraform/plugins` for already-installed providers)

    ### Installation
    Default:
  8. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 22 additions and 11 deletions.
    33 changes: 22 additions & 11 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -7,12 +7,20 @@ Terraform 0.13 has an entirely new provider installer that allows for greater co
    The key differences between Terraform v0.12 and v0.13 are the directory hierarchy. Terraform v0.12 would look for a provider binary under the following directories:

    ### Search
    - $PATH/wherever the terraform executable lives
    - **Windows**: `%APPDATA%\terraform.d\plugins`
    - **All others**: `~/.terraform.d/plugins`
    - Location of the terraform binary (/usr/local/bin, for example)
    - `terraform.d/plugins/<OS>_<ARCH>` For airgapped installations; see `terraform-bundle`
    - Registry lookup (tf does not query the registry for providers found locally unless `-upgrade` flag is true)

    The following command-line options are available to override the default search and installation behavior:
    The following command-line option is available to override the default search location:
    - `-plugin-dir`: disables registry lookup; only search that directory

    ### Installation
    Default:
    - `.terraform/plugins`

    Options:
    - `-plugin-cache-dir`: does not change search paths; installs providers into the specified directory

    Install from registry if not found
    @@ -30,7 +38,9 @@ A major implication of the provider source work is that terraform can no longer

    #### Filesystem search paths

    Default:
    * `terraform.d/plugins` in the current working directory (documented in `terraform-bundle` as a place to put plugins as a way to include them in bundles uploaded to Terraform Cloud)
    * `.terraform/plugins` relative to configuration for any already-installed plugins

    OS-specific paths:
    * **Windows:** `%APPDATA%/HashiCorp/Terraform/plugins`
    @@ -43,26 +53,27 @@ OS-specific paths:
    will use `~/.local/share/terraform/plugins`,
    `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`.

    Maybe `$HOME/.terraform.d/plugins`?
    Options:
    - `-plugin-dir` command-line flag: *only* that directory will be searched (no registry lookup)

    Q: does this override CLI config?

    #### Registry lookup
    Same use-facing behavior as 0.12: terraform queries the registry to find providers.
    If a provider is found in one of the search paths, terraform will **not** query the registry for that provider (TODO: check that `-upgrade` overrides that as expected).

    ### Command-line options
    -plugin-dir: *only* that directory will be searched (no registry lookup)
    Q: does this override CLI config?


    ### Cli config options
    We've added a CLI configuration setting to let users declare plugin search locations for all configurations on a given workstation.

    1. filesystem_mirror
    1. direct
    1. network_mirror [targeting future release]
    1. `filesystem_mirror`
    1. `direct`
    1. `network_mirror` [targeting future 0.13.* release]

    ## Installation
    Default: `.terraform/plugins/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/`
    Default:
    `.terraform/plugins/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/`

    Options:
    * `-plugin-cache-dir` command-line flag: does not change search behavior, just install: plugins will be downloaded into, and installed from, the cache dir
    * `plugin_cache_dir` CLI config setting: same as above.
  9. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 14 additions and 4 deletions.
    18 changes: 14 additions & 4 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -5,9 +5,15 @@ Terraform 0.13 has an entirely new provider installer that allows for greater co

    ## Terraform v0.12
    The key differences between Terraform v0.12 and v0.13 are the directory hierarchy. Terraform v0.12 would look for a provider binary under the following directories:

    ### Search
    - $PATH/wherever the terraform executable lives
    - plugin-dir
    - plugin-cache-dir

    The following command-line options are available to override the default search and installation behavior:
    - `-plugin-dir`: disables registry lookup; only search that directory

    ### Installation
    - `-plugin-cache-dir`: does not change search paths; installs providers into the specified directory

    Install from registry if not found

    @@ -18,7 +24,7 @@ A major implication of the provider source work is that terraform can no longer

    `$BASEDIR/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/`

    ### Default search locations
    ### Search
    1. Filesystem
    1. Terraform Registry

    @@ -47,7 +53,6 @@ If a provider is found in one of the search paths, terraform will **not** query
    -plugin-dir: *only* that directory will be searched (no registry lookup)
    Q: does this override CLI config?

    -plugin-cache-dir: does not change search behavior, just install: plugins will be downloaded into, and installed from, the cache dir

    ### Cli config options
    We've added a CLI configuration setting to let users declare plugin search locations for all configurations on a given workstation.
    @@ -56,3 +61,8 @@ We've added a CLI configuration setting to let users declare plugin search locat
    1. direct
    1. network_mirror [targeting future release]

    ## Installation
    Default: `.terraform/plugins/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/`
    Options:
    * `-plugin-cache-dir` command-line flag: does not change search behavior, just install: plugins will be downloaded into, and installed from, the cache dir
    * `plugin_cache_dir` CLI config setting: same as above.
  10. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 8 additions and 8 deletions.
    16 changes: 8 additions & 8 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,14 +1,15 @@
    # Provider Installation

    ## Overview
    Terraform 0.13 has an entirely new provider installer that allows for greater control over individual provider installation methods.
    Terraform 0.13 has an entirely new provider installer that allows for greater control over individual provider installation methods. The breaking change is a new, *required*, subdirectory hierarchy for provider binaries.

    ## Terraform v0.12
    - flat directories
    - plugin-dir
    - plugin-cache-dir
    The key differences between Terraform v0.12 and v0.13 are the directory hierarchy. Terraform v0.12 would look for a provider binary under the following directories:
    - $PATH/wherever the terraform executable lives
    - registry
    - plugin-dir
    - plugin-cache-dir

    Install from registry if not found

    ## Terraform v0.13

    @@ -23,8 +24,7 @@ A major implication of the provider source work is that terraform can no longer

    #### Filesystem search paths


    * `terraform.d/plugins` in the current working directory (not documented, it's historically documented as a place to put plugins as a way to include them in bundles uploaded to Terraform Cloud)
    * `terraform.d/plugins` in the current working directory (documented in `terraform-bundle` as a place to put plugins as a way to include them in bundles uploaded to Terraform Cloud)

    OS-specific paths:
    * **Windows:** `%APPDATA%/HashiCorp/Terraform/plugins`
    @@ -44,7 +44,7 @@ Same use-facing behavior as 0.12: terraform queries the registry to find provide
    If a provider is found in one of the search paths, terraform will **not** query the registry for that provider (TODO: check that `-upgrade` overrides that as expected).

    ### Command-line options
    -plugin-dir: *only* that directory will be searched
    -plugin-dir: *only* that directory will be searched (no registry lookup)
    Q: does this override CLI config?

    -plugin-cache-dir: does not change search behavior, just install: plugins will be downloaded into, and installed from, the cache dir
  11. @mildwonkey mildwonkey revised this gist May 12, 2020. 1 changed file with 4 additions and 0 deletions.
    4 changes: 4 additions & 0 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -23,6 +23,10 @@ A major implication of the provider source work is that terraform can no longer

    #### Filesystem search paths


    * `terraform.d/plugins` in the current working directory (not documented, it's historically documented as a place to put plugins as a way to include them in bundles uploaded to Terraform Cloud)

    OS-specific paths:
    * **Windows:** `%APPDATA%/HashiCorp/Terraform/plugins`
    * **Mac OS X:** `~/Library/Application Support/io.terraform/plugins` and
    `/Library/Application Support/io.terraform/plugins`
  12. @mildwonkey mildwonkey created this gist May 12, 2020.
    54 changes: 54 additions & 0 deletions installer.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,54 @@
    # Provider Installation

    ## Overview
    Terraform 0.13 has an entirely new provider installer that allows for greater control over individual provider installation methods.

    ## Terraform v0.12
    - flat directories
    - plugin-dir
    - plugin-cache-dir
    - $PATH/wherever the terraform executable lives
    - registry

    ## Terraform v0.13

    ### New Directory layout
    A major implication of the provider source work is that terraform can no longer assume that provider types are unique: a user could have multiple provides with the same type in a given configuration. To support this, terraform now requires the all provider binaries are in a specific directory hierarchy corresponding with the source:

    `$BASEDIR/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/`

    ### Default search locations
    1. Filesystem
    1. Terraform Registry

    #### Filesystem search paths

    * **Windows:** `%APPDATA%/HashiCorp/Terraform/plugins`
    * **Mac OS X:** `~/Library/Application Support/io.terraform/plugins` and
    `/Library/Application Support/io.terraform/plugins`
    * **Linux and other Unix-like systems**: Terraform implements the
    [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
    specification and appends `terraform/plugins` to all of the specified
    data directories. Without any XDG environment variables set, Terraform
    will use `~/.local/share/terraform/plugins`,
    `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`.

    Maybe `$HOME/.terraform.d/plugins`?

    #### Registry lookup
    Same use-facing behavior as 0.12: terraform queries the registry to find providers.
    If a provider is found in one of the search paths, terraform will **not** query the registry for that provider (TODO: check that `-upgrade` overrides that as expected).

    ### Command-line options
    -plugin-dir: *only* that directory will be searched
    Q: does this override CLI config?

    -plugin-cache-dir: does not change search behavior, just install: plugins will be downloaded into, and installed from, the cache dir

    ### Cli config options
    We've added a CLI configuration setting to let users declare plugin search locations for all configurations on a given workstation.

    1. filesystem_mirror
    1. direct
    1. network_mirror [targeting future release]