Terraform Provider for MinIO

Manage MinIO and S3-compatible object storage as code

Docs  ·  Examples  ·  Roadmap  ·  Discussions  ·  Security

Provision and manage MinIO with the same Terraform workflow you already use for the rest of your infrastructure. Define buckets, IAM users and policies, lifecycle and replication rules, encryption, and server configuration in HCL, then plan and apply. The provider talks to the MinIO S3 and Admin APIs directly and also drives other S3-compatible backends through a single compatibility switch.

Highlights

• Broad coverage: resources and data sources spanning buckets and objects, IAM, ILM, replication, encryption, notifications, and server and cluster configuration.
• Proven in production: over 18 million downloads on the Terraform Registry, with frequent releases.
• Flexible auth: static keys, environment variables, STS AssumeRole, OIDC web identity (passwordless CI/CD), and mTLS.
• Works beyond MinIO: set s3_compat_mode = true to target Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Hetzner Object Storage, and other S3-compatible stores.
• Import everywhere: every resource supports terraform import, so you can bring existing infrastructure under management.
• AI-agent ready: ships a Claude Code skill and an AGENTS.md so coding agents produce correct configuration out of the box.

Quick start

Pin the provider and describe what you want. The example below creates a bucket, a user, a policy scoped to that bucket, and attaches the two:

terraform {
  required_providers {
    minio = {
      source  = "aminueza/minio"
      version = "~> 3.0"
    }
  }
}
provider "minio" {
  minio_server   = "localhost:9000"
  minio_user     = "minio"
  minio_password = "minio123"
}
resource "minio_s3_bucket" "app" {
  bucket = "app-data"
  acl    = "private"
}
resource "minio_iam_user" "app" {
  name = "app"
}
resource "minio_iam_policy" "app" {
  name   = "app-read-write"
  policy = <<-EOT
  {
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": ["${minio_s3_bucket.app.arn}/*"]
    }]
  }
  EOT
}
resource "minio_iam_user_policy_attachment" "app" {
  user_name   = minio_iam_user.app.name
  policy_name = minio_iam_policy.app.name
}

terraform init
terraform apply

Credentials can also come from MINIO_ENDPOINT, MINIO_USER, and MINIO_PASSWORD instead of the provider block. See the provider configuration for every argument, and the examples directory for buckets, groups, service accounts, LDAP, and more.

What you can manage

| Area | Resources include | |------|-------------------| | Buckets & objects | s3_bucket, s3_object, versioning, lifecycle, replication, CORS, quota, object lock, retention, tags, notifications, anonymous access | | IAM | users, groups, policies, service accounts, group and policy attachments, LDAP and OpenID identity providers | | Encryption & KMS | server-side encryption, kms_key | | Lifecycle (ILM) | ilm_policy, ilm_tier | | Notifications & audit | AMQP, Kafka, MQTT, MySQL, NATS, NSQ, Postgres, Redis, Elasticsearch, and webhook targets; audit and logger webhooks | | Server & cluster | API, region, scanner, storage class, and heal config; site replication; pool decommission and rebalance; batch jobs |

Every area is mirrored by read-only data sources. Browse the full list in the Terraform Registry documentation.

S3-compatible backends

The provider is built for MinIO but works with other S3-compatible stores. Set s3_compat_mode = true and the provider gracefully skips features a backend does not implement (notifications, CORS, object lock, lifecycle) instead of failing:

provider "minio" {
  minio_server   = "fsn1.your-objectstorage.com"
  minio_user     = var.access_key
  minio_password = var.secret_key
  minio_ssl      = true
  s3_compat_mode = true
}

Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Hetzner Object Storage, and Versity Gateway are tested. The provider docs carry the per-backend support matrix and notes on region signing.

Use with AI coding agents

This repository ships a Claude Code skill in skills/terraform-minio that turns natural-language requests (for example, "give this app a read-only key for the backups bucket") into correct aminueza/minio HCL and drives Terraform through a safe plan → confirm → apply workflow. Read operations run freely; mutating operations are gated behind a reviewed plan and explicit confirmation.

# Available in every project:
cp -R skills/terraform-minio ~/.claude/skills/
Or scoped to this repo:
mkdir -p .claude/skills && cp -R skills/terraform-minio .claude/skills/

An AGENTS.md at the repository root gives any agent the conventions, argument names, and error-handling patterns it needs to contribute here.

Installing

Released builds are published to the Terraform Registry; the required_providers block above is all you need. Prebuilt binaries are also on the Releases page.

To build and install from source, install Task and run:

task install

The plugin is placed in the correct local plugins directory for your operating system automatically.

Development

task build          # compile the provider
task lint           # run golangci-lint
task test           # run acceptance tests (Docker required)
task generate-docs  # regenerate docs/ from templates/ and schema

Acceptance tests run against real MinIO instances via Docker Compose:

docker compose run --rm test
Run a subset by name:
TEST_PATTERN=TestAccMinioS3Bucket_basic docker compose run --rm test
Pull the MinIO images from somewhere else, for a mirror or another release.
This replaces the image for every MinIO service at once:
MINIO_IMAGE=minio/minio:RELEASE.2025-09-07T16-13-09Z task test

The images come from quay.io/minio/minio. Docker Hub stopped serving minio/minio to anonymous clients, including GitHub Actions runners, so MINIO_IMAGE is there to point the suite at any registry you can reach.

Full setup, project layout, and the MinIO consoles used during testing are covered in CONTRIBUTING.md.

Community & support

| What | Where | |--|--| | Documentation | Terraform Registry | | Issues | Report a bug or request a feature | | Discussions | Ask questions and share ideas | | Security | Report a vulnerability |

Contributing

Contributions are welcome, from bug reports and feature requests to documentation and new resources. Start with CONTRIBUTING.md for the development setup and conventions, and see GOVERNANCE.md for how decisions are made.

License

Versions from v2.0.0 onward are distributed under the GNU AGPL-3.0 license. You are free to use, modify, and self-host the provider; if you distribute a modified version or offer it as a network service, you must make your source available under the same license.

See LICENSE for the full text.

Acknowledgments

• Every contributor who has shaped this project.
• Built with the Terraform Plugin SDKv2.
• Powered by MinIO high-performance object storage.