Dependencies and Modules

6 minute read

Dependencies Overview

Go modules are the standard dependency management system for Go projects. Understanding how to manage dependencies correctly is crucial for provider development.

In this chapter, you’ll learn about go.mod files, version management, and specific requirements for the Terraform Plugin Framework.

What are Go Modules?

Go modules provide:

  • ✅ Dependency versioning
  • ✅ Reproducible builds
  • ✅ Semantic versioning support
  • ✅ Module proxies for reliability
  • ✅ Checksums for security

Introduced in Go 1.11, modules became the default in Go 1.13 and are now the only supported way to manage dependencies.

Understanding go.mod

The go.mod file defines your module and its dependencies.

Example go.mod

module github.com/YOUR_USERNAME/terraform-provider-mycloud

go 1.22

require (
    github.com/hashicorp/terraform-plugin-framework v1.5.0
    github.com/hashicorp/terraform-plugin-go v0.21.0
    github.com/hashicorp/terraform-plugin-log v0.9.0
)

require (
    github.com/fatih/color v1.16.0 // indirect
    github.com/google/go-cmp v0.6.0 // indirect
    github.com/hashicorp/go-hclog v1.6.2 // indirect
    github.com/mattn/go-colorable v0.1.13 // indirect
    github.com/mitchellh/go-testing-interface v1.14.1 // indirect
    github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
)

Anatomy of go.mod

Line 1: Module path

module github.com/YOUR_USERNAME/terraform-provider-mycloud
  • Your module’s import path
  • Must be unique
  • Should match repository URL

Line 3: Go version

go 1.22
  • Minimum Go version required
  • Provider development needs 1.21+
  • Controls language feature availability

Lines 5-9: Direct dependencies

require (
    github.com/hashicorp/terraform-plugin-framework v1.5.0
    github.com/hashicorp/terraform-plugin-go v0.21.0
    github.com/hashicorp/terraform-plugin-log v0.9.0
)
  • Dependencies your code directly imports
  • Explicit versions
  • Major dependencies

Lines 11-18: Indirect dependencies

require (
    github.com/fatih/color v1.16.0 // indirect
    // ...
)
  • Dependencies of your dependencies
  • Marked with // indirect
  • Managed automatically

Understanding go.sum

The go.sum file contains cryptographic checksums of module contents.

Example go.sum

github.com/hashicorp/terraform-plugin-framework v1.5.0 h1:P1tz...
github.com/hashicorp/terraform-plugin-framework v1.5.0/go.mod h1:O5l...
github.com/hashicorp/terraform-plugin-go v0.21.0 h1:f7Q...
github.com/hashicorp/terraform-plugin-go v0.21.0/go.mod h1:H6l...

Purpose:

  • Verify module integrity
  • Prevent tampering
  • Ensure reproducible builds
  • Security validation

⚠️ Never edit go.sum manually!

Core Provider Dependencies

Plugin Framework

Latest version: 1.5.0+ (as of 2024)

require github.com/hashicorp/terraform-plugin-framework v1.5.0

What it provides:

  • Type-safe schema definition
  • Automatic validation
  • State management
  • Plan modification
  • Modern architecture

Plugin Go

Latest version: 0.21.0+

require github.com/hashicorp/terraform-plugin-go v0.21.0

What it provides:

  • GRPC protocol implementation
  • Low-level plugin communication
  • Terraform Core integration

Note: Usually transitive, but sometimes needed directly

Plugin Log

Latest version: 0.9.0+

require github.com/hashicorp/terraform-plugin-log v0.9.0

What it provides:

  • Structured logging
  • Context-aware logs
  • Multiple log levels
  • Terraform-compatible output

Adding Dependencies

Using go get

# Add latest version
go get github.com/google/uuid

# Add specific version
go get github.com/google/uuid@v1.6.0

# Add specific commit
go get github.com/google/uuid@abc123

# Add latest major version 2
go get github.com/your/package/v2@latest

After adding:

go mod tidy

This removes unused dependencies and adds missing ones.

Manual Addition

Edit go.mod directly:

require (
    github.com/hashicorp/terraform-plugin-framework v1.5.0
    github.com/google/uuid v1.6.0  // Add this line
)

Then run:

go mod download
go mod tidy

Version Constraints

Semantic Versioning

Go modules use semantic versioning (semver):

v1.2.3
│ │ │
│ │ └─ PATCH: Bug fixes
│ └─── MINOR: New features (backward compatible)
└───── MAJOR: Breaking changes

Version Selection

# Latest version
go get github.com/some/package@latest

# Specific version
go get github.com/some/package@v1.2.3

# Version range (via go.mod)
go get github.com/some/package@v1.2

Minimum Version Selection (MVS)

Go uses Minimum Version Selection:

  • Always uses the minimum required version
  • Not the latest compatible version
  • Ensures reproducibility
  • Prevents unexpected updates

Example:

Your code requires: v1.2.0
Dependency A requires: v1.1.0
Dependency B requires: v1.3.0

Go selects: v1.3.0 (minimum that satisfies all)

Updating Dependencies

Update Single Dependency

# Update to latest minor/patch
go get -u=patch github.com/hashicorp/terraform-plugin-framework

# Update to latest (including minor versions)
go get -u github.com/hashicorp/terraform-plugin-framework

# Update to specific version
go get github.com/hashicorp/terraform-plugin-framework@v1.5.1

Update All Dependencies

# Update all to latest minor/patch
go get -u=patch ./...

# Update all (including minor versions)
go get -u ./...

# Clean up
go mod tidy

Check for Updates

# List available updates
go list -u -m all

# Check specific module
go list -u -m github.com/hashicorp/terraform-plugin-framework

Plugin Framework Versions

Version History

Version Released Features
v0.x 2022 Beta releases
v1.0.0 Dec 2022 Production ready
v1.1.0 Feb 2023 Nested attributes
v1.2.0 Apr 2023 Default values
v1.3.0 Jun 2023 Plan modifiers
v1.4.0 Oct 2023 Validators
v1.5.0 Jan 2024 Dynamic types

Choosing a Version

For new providers:

require github.com/hashicorp/terraform-plugin-framework v1.5.0

Use the latest stable version.

For existing providers:

  • Review CHANGELOG
  • Test thoroughly
  • Update incrementally
  • Watch for breaking changes

Breaking Changes

Major version changes (e.g., v1 → v2) may include:

  • API changes
  • Removed functions
  • Schema changes
  • New requirements

Always check:

go mod Commands

Essential Commands

# Initialize new module
go mod init github.com/YOUR_USERNAME/terraform-provider-mycloud

# Add missing dependencies
go mod tidy

# Download dependencies
go mod download

# Verify dependencies
go mod verify

# List all dependencies
go list -m all

# Show dependency graph
go mod graph

# Explain why a dependency is needed
go mod why github.com/some/package

# Vendor dependencies (copy to vendor/)
go mod vendor

go mod tidy

What it does:

  • Adds missing dependencies
  • Removes unused dependencies
  • Updates go.sum
  • Organizes require statements

Run after:

  • Adding imports
  • Removing code
  • Changing dependencies
  • Pulling code changes
go mod tidy

go mod download

What it does:

  • Downloads all dependencies
  • Populates module cache
  • Doesn’t modify go.mod
# Download all
go mod download

# Download specific module
go mod download github.com/hashicorp/terraform-plugin-framework

go mod verify

What it does:

  • Checks downloaded modules against go.sum
  • Detects corruption
  • Validates integrity
go mod verify

Expected output:

all modules verified

Vendoring (Optional)

Vendoring copies dependencies into your project.

Why Vendor?

Pros:

  • Offline builds
  • Guaranteed availability
  • Corporate policies

Cons:

  • Larger repository
  • More merge conflicts
  • Extra maintenance

Using Vendor

# Create vendor directory
go mod vendor

# Build using vendor
go build -mod=vendor

# Remove vendor
rm -rf vendor/

Add to .gitignore:

vendor/

Or commit vendor/ if required by your organization.

Common Dependency Issues

Issue: Cannot Find Module

Error:

go: github.com/YOUR_USERNAME/terraform-provider-mycloud@v0.1.0: 
reading github.com/YOUR_USERNAME/terraform-provider-mycloud/go.mod at revision v0.1.0: 
unknown revision v0.1.0

Solutions:

  1. Tag doesn’t exist — create it: 
    git tag v0.1.0
git push origin v0.1.0
  2. Private repository — configure auth: 
    git config --global url."https://YOUR_TOKEN@github.com/".insteadOf "https://github.com/"
  3. Module path mismatch — verify go.mod path

Issue: Checksum Mismatch

Error:

verifying github.com/hashicorp/terraform-plugin-framework@v1.5.0: 
checksum mismatch

Solutions:

# Clear module cache
go clean -modcache

# Re-download
go mod download

# Verify
go mod verify

Issue: Incompatible Versions

Error:

github.com/hashicorp/terraform-plugin-framework v1.5.0 requires 
github.com/hashicorp/terraform-plugin-go v0.21.0, but you have v0.15.0

Solutions:

# Update dependency
go get github.com/hashicorp/terraform-plugin-go@v0.21.0

# Or update all
go get -u ./...
go mod tidy

Issue: Import Cycle

Error:

import cycle not allowed
package github.com/YOUR_USERNAME/terraform-provider-mycloud/internal/provider
    imports github.com/YOUR_USERNAME/terraform-provider-mycloud/internal/client
    imports github.com/YOUR_USERNAME/terraform-provider-mycloud/internal/provider

Solution: Refactor to break cycle:

  • Extract shared code to new package
  • Use interfaces
  • Restructure dependencies

Module Proxies

Default Proxy

Go uses proxy.golang.org by default:

  • Caches modules
  • Improves reliability
  • Faster downloads

Custom Proxy

# Use custom proxy
export GOPROXY=https://goproxy.io,direct

# Use direct (no proxy)
export GOPROXY=direct

# Multiple proxies (fallback)
export GOPROXY=https://proxy1.com,https://proxy2.com,direct

Private Modules

# Skip proxy for private repos
export GOPRIVATE=github.com/YOUR_COMPANY/*

# Or specific repos
export GOPRIVATE=github.com/YOUR_COMPANY/repo1,github.com/YOUR_COMPANY/repo2

Best Practices

1. Pin Exact Versions

// GOOD: Exact version
require github.com/hashicorp/terraform-plugin-framework v1.5.0

// AVOID: Vague version
require github.com/hashicorp/terraform-plugin-framework v1

2. Regular Updates

# Monthly check
go list -u -m all
go get -u=patch ./...
go mod tidy

3. Verify After Changes

go mod verify
go test ./...

4. Commit go.sum

Always commit go.sum with go.mod:

git add go.mod go.sum
git commit -m "Update dependencies"

5. Review Dependency Licenses

# Install go-licenses
go install github.com/google/go-licenses@latest

# Check licenses
go-licenses check ./...

Security Considerations

Check for Vulnerabilities

# Install govulncheck
go install golang.org/x/vuln/cmd/govulncheck@latest

# Check your code
govulncheck ./...

Update Security Patches

# Update patch versions (security fixes)
go get -u=patch ./...

Review Dependencies

  • Use only necessary dependencies
  • Prefer well-maintained modules
  • Check last update date
  • Review GitHub activity

Key Takeaways

  • ✅ Go modules are the standard for dependency management
  • ✅ go.mod defines your module and dependencies
  • ✅ go.sum ensures integrity and reproducibility
  • ✅ Use Plugin Framework 1.5.0+ for new providers
  • ✅ Run go mod tidy frequently
  • ✅ Pin exact versions for reproducibility
  • ✅ Update dependencies regularly
  • ✅ Always commit go.sum with go.mod

What’s Next?

Time to put everything together in a hands-on lab where you’ll build your first provider!

Next: Hands-On Lab →

Previous: ← Project Structure

Last updated: June 30, 2026

Updated:

You may also enjoy