DOCSEARCHbyAlgolia
Submit Docs

tfupdate

repository·master·Indexed 20 days ago

https://github.com/minamijoyo/tfupdate

A utility for managing and automating version updates for Terraform and OpenTofu configurations. It automates updating version constraints for core versions, providers, and modules, and can update dependency lock files (.terraform.lock.hcl) without requiring the Terraform or OpenTofu CLI. It supports recursive updates, fetches latest releases from GitHub, GitLab, and the Terraform/OpenTofu Registries, and integrates with CI/CD pipelines.

Tokens
7.3K
Snippets
26
Records
32
Agent score
71%

What's inside tfupdate

  1. Overview of tfupdate

    master

    tfupdate is a tool designed to automate the updating of version constraints for Terraform core, OpenTofu core, providers, and modules. It can also update dependency lock files (.terraform.lock.hcl) without requiring the Terraform or OpenTofu CLI to be installed.

    Key capabilities include:

    • Recursive updates of configurations and lock files under a specified directory.
    • Fetching the latest release versions from GitHub, GitLab, the Terraform Registry, or the OpenTofu Registry.
    • Support for Terraform v0.12+ and OpenTofu v1.6+.
    • Integration with CI/CD pipelines to automate daily version checks and Pull Request creation.

  6. Automate dependency updates in CI

    master

    You can integrate tfupdate with CI/CD pipelines or job schedulers to automatically check for the latest releases daily and create Pull Requests.

    For CircleCI users, there are pre-built integration patterns available:

    • A standalone CircleCI example: https://github.com/minamijoyo/tfupdate-circleci-example
    • A dedicated CircleCI orb: https://github.com/masutaka/circleci-tfupdate-orb

  7. Configure environment variables for release and lock commands

    master

    Certain commands require environment variables to access private repositories or specific registries:

    VariablePurposeDefault / Example
    GITHUB_TOKENAccess private GitHub repositoriesYour GitHub PAT
    GITLAB_TOKENAccess private GitLab repositoriesYour GitLab API token
    GITLAB_BASE_URLCustom GitLab instance URLhttps://gitlab.com/api/v4/
    TFREGISTRY_BASE_URLUse the public OpenTofu registryhttps://registry.opentofu.org/

  8. Use the API interface for testing

    master
    The API interface defines the contract for interacting with the Terraform Registry. It embeds ModuleV1API and ProviderV1API. Because the Client implements this interface, you can use the API type in your own code to allow for easy mocking during unit tests.

  9. Configure the TFRegistry Client

    master

    The Config struct allows you to customize the behavior of the Client:

    • HTTPClient (*http.Client): An optional HTTP client used for API communication. If nil, a default &http.Client{} is used.
    • BaseURL (string): The base URL for Terraform Registry API requests. Defaults to https://registry.terraform.io/. Ensure the URL ends with a trailing slash.
    tfregistry.Config{
    HTTPClient: nil, // uses default
    BaseURL:    "https://registry.terraform.io/",
}

  10. Configure tfupdate via Docker Compose

    master

    When running tfupdate using the provided Docker Compose setup, you can customize the build environment and runtime behavior using environment variables and build arguments.

    Build Arguments

    During the build process, you can specify the versions of Terraform or OpenTofu to be included in the image:

    • TERRAFORM_VERSION: The version of Terraform to install. Defaults to latest if not provided.
    • OPENTOFU_VERSION: The version of OpenTofu to install. Defaults to 1 if not provided.

    Runtime Environment Variables

    The following environment variables are exposed to the tfupdate service:

    • TFUPDATE_EXEC_PATH: Sets the path to the tfupdate executable.
    • TFREGISTRY_BASE_URL: Sets the base URL for the Terraform registry.
    • CGO_ENABLED: Set to 0 by default to disable CGO for Go testing purposes.
    services:
  tfupdate:
    build:
      context: .
      dockerfile: ./Dockerfile.dev
      args:
        TERRAFORM_VERSION: ${TERRAFORM_VERSION:-latest}
        OPENTOFU_VERSION: ${OPENTOFU_VERSION:-1}
    environment:
      CGO_ENABLED: 0
      TFUPDATE_EXEC_PATH:
      TFREGISTRY_BASE_URL:

  11. Examples of `tfupdate provider` usage

    master

    Here are common ways to use the provider command:

    Update a provider to the latest version in a specific file:

    tfupdate provider aws main.tf

    Update a provider to a specific version in a directory recursively:

    tfupdate provider aws ./modules -v 5.0.0 -r

    Update a namespaced provider while ignoring specific paths:

    tfupdate provider integrations/github ./ -v 6.0.0 -i "test/" -i "vendor/"
    # Update aws provider to latest in main.tf
tfupdate provider aws main.tf

# Update aws provider to version 5.0.0 recursively in ./modules
tfupdate provider aws ./modules --version 5.0.0 --recursive

# Update namespaced provider and ignore multiple paths
tfupdate provider integrations/github ./ --version 6.0.0 --ignore-path "test/" --ignore-path "vendor/"

  12. Update Terraform version constraints

    master

    Use the terraform command to update the required_version in your Terraform configuration files. You can specify a specific version or a version constraint (e.g., ~> 1.0). If the -v flag is omitted, tfupdate will automatically check for and set the latest version.

    Options:

    • -v, --version: The new version constraint (string literal or constraint).
    • -r, --recursive: Check a directory and its subdirectories recursively.
    • -i, --ignore-path: A regular expression for paths to ignore. Use this flag multiple times to ignore multiple patterns.
    # Update a specific file to a specific version
tfupdate terraform -v 0.12.16 main.tf

# Update using a version constraint
tfupdate terraform -v "~> 1.0" main.tf

# Recursively update all configurations in a directory
tfupdate terraform -v 0.12.16 -r ./

# Recursively update while ignoring specific directories
tfupdate terraform -v 0.12.16 -i modules/ -r ./

# Automatically update to the latest version recursively
tfupdate terraform -r ./