github.com/terraform-linters/tflint@v0.51.2-0.20240520175844-3750771571b6/docs/user-guide/plugins.md (about)

     1  # Configuring Plugins
     2  
     3  You can extend TFLint by installing any plugin. Declare plugins you want to use in the config file as follows:
     4  
     5  ```hcl
     6  plugin "foo" {
     7    enabled = true
     8    version = "0.1.0"
     9    source  = "github.com/org/tflint-ruleset-foo"
    10  
    11    signing_key = <<-KEY
    12    -----BEGIN PGP PUBLIC KEY BLOCK-----
    13  
    14    mQINBFzpPOMBEADOat4P4z0jvXaYdhfy+UcGivb2XYgGSPQycTgeW1YuGLYdfrwz
    15    9okJj9pMMWgt/HpW8WrJOLv7fGecFT3eIVGDOzyT8j2GIRJdXjv8ZbZIn1Q+1V72
    16    AkqlyThflWOZf8GFrOw+UAR1OASzR00EDxC9BqWtW5YZYfwFUQnmhxU+9Cd92e6i
    17    ...
    18    KEY
    19  }
    20  ```
    21  
    22  After declaring the `version` and `source`, `tflint --init` can automatically install the plugin.
    23  
    24  ```console
    25  $ tflint --init
    26  Installing "foo" plugin...
    27  Installed "foo" (source: github.com/org/tflint-ruleset-foo, version: 0.1.0)
    28  $ tflint -v
    29  TFLint version 0.28.1
    30  + ruleset.foo (0.1.0)
    31  ```
    32  
    33  See also [Configuring TFLint](config.md) for the config file schema.
    34  
    35  ## Attributes
    36  
    37  This section describes the attributes reserved by TFLint. Except for these, each plugin can extend the schema by defining any attributes/blocks. See the documentation for each plugin for details.
    38  
    39  ### `enabled` (required)
    40  
    41  Enable the plugin. If set to false, the rules will not be used even if the plugin is installed.
    42  
    43  ### `source`
    44  
    45  The source URL to install the plugin. Must be in the format `github.com/org/repo`.
    46  
    47  ### `version`
    48  
    49  Plugin version. Do not prefix with "v". This attribute cannot be omitted when the `source` is set. Version constraints (like `>= 0.3`) are not supported.
    50  
    51  ### `signing_key`
    52  
    53  Plugin developer's PGP public signing key. When this attribute is set, TFLint will automatically verify the signature of the checksum file downloaded from GitHub. It is recommended to set it to prevent supply chain attacks.
    54  
    55  Plugins under the terraform-linters organization (AWS/GCP/Azure ruleset plugins) can use the built-in signing key, so this attribute can be omitted.
    56  
    57  ## Plugin directory
    58  
    59  Plugins are usually installed under `~/.tflint.d/plugins`. Exceptionally, if you already have `./.tflint.d/plugins` in your working directory, it will be installed there.
    60  
    61  The automatically installed plugins are placed as `[plugin dir]/[source]/[version]/tflint-ruleset-[name]`. (`tflint-ruleset-[name].exe` in Windows).
    62  
    63  If you want to change the plugin directory, you can change this with the [`plugin_dir`](config.md#plugin_dir) or `TFLINT_PLUGIN_DIR` environment variable.
    64  
    65  ## Avoiding rate limiting
    66  
    67  When you install plugins with `tflint --init`, TFLint calls the GitHub API to get release metadata. By default, this is an unauthenticated request, subject to a rate limit of 60 requests per hour _per IP address_.
    68  
    69  **Background:** [GitHub REST API: Rate Limiting](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
    70  
    71  If you fetch plugins frequently in CI, you may hit this rate limit. If you run TFLint in a shared CI environment such as GitHub Actions, you will share this quota with other tenants and may encounter rate limiting errors regardless of how often you run TFLint. 
    72  
    73  To increase the rate limit, you can send an authenticated request by authenticating your requests with an access token, by setting the `GITHUB_TOKEN` environment variable. In GitHub Actions, you can pass the built-in `GITHUB_TOKEN` that is injected into each job.
    74  
    75  It's also a good idea to cache the plugin directory, as TFLint will only send requests if plugins aren't installed. The [setup-tflint action](https://github.com/terraform-linters/setup-tflint#usage) includes an example of caching in GitHub Actions.
    76  
    77  If you host your plugins on GitHub Enterprise Server (GHES), you may need to use a different token than on GitHub.com. In this case, you can use a host-specific token like `GITHUB_TOKEN_example_com`. The hostname must be normalized with Punycode. Use "_" instead of "." and "__" instead of "-".
    78  
    79  ```hcl
    80  # GITHUB_TOKEN will be used
    81  plugin "foo" {
    82    source = "github.com/org/tflint-ruleset-foo"
    83  }
    84  
    85  # GITHUB_TOKEN_example_com will be used preferentially and will fall back to GITHUB_TOKEN if not set.
    86  plugin "bar" {
    87    source = "example.com/org/tflint-ruleset-bar"
    88  }
    89  ```
    90  
    91  ## Keeping plugins up to date
    92  
    93  We recommend using automatic updates to keep your plugin version up-to-date. [Renovate supports TFLint plugins](https://docs.renovatebot.com/modules/manager/tflint-plugin/) to easily set up automated update workflows.
    94  
    95  ## Manual installation
    96  
    97  You can also install the plugin manually. This is mainly useful for plugin development and for plugins that are not published on GitHub. In that case, omit the `source` and `version` attributes.
    98  
    99  ```hcl
   100  plugin "foo" {
   101    enabled = true
   102  }
   103  ```
   104  
   105  When the plugin is enabled, TFLint invokes the `tflint-ruleset-[name]` (`tflint-ruleset-[name].exe` on Windows) binary in the plugin directory (For instance, `~/.tflint.d/plugins/tflint-ruleset-[name]`). So you should move the binary into the directory in advance.
   106  
   107  ## Bundled plugin
   108  
   109  [TFLint Ruleset for Terraform Language](https://github.com/terraform-linters/tflint-ruleset-terraform) is built directly into TFLint binary. This is called a bundled plugin. Unlike other plugins, bundled plugins can be used without installation.
   110  
   111  A bundled plugin is enabled by default without a plugin block declaration. The default config is below:
   112  
   113  ```hcl
   114  plugin "terraform" {
   115    enabled = true
   116    preset  = "recommended"
   117  }
   118  ```
   119  
   120  You can also change the behavior of the bundled plugin by explicitly declaring a plugin block.
   121  
   122  If you want to use a different version of tflint-ruleset-terraform instead of the bundled plugin, you can install it with `tflint --init` by specifying the `version` and `source`. In this case the bundled plugin will not be automatically enabled.
   123  
   124  ```hcl
   125  plugin "terraform" {
   126    enabled = true
   127    preset  = "recommended"
   128  
   129    version = "0.1.0"
   130    source  = "github.com/terraform-linters/tflint-ruleset-terraform"
   131  }
   132  ```
   133  
   134  If you have tflint-ruleset-terraform manually installed, the bundled plugin will not be automatically enabled. In this case the manually installed version takes precedence.