From d74fc77eb113ba33c2f46c26a5cdffff65d1845a Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Fri, 21 Aug 2026 22:09:38 -0700 Subject: [PATCH] docs(terraform/provider): the provider now ships at the LiteLLM version (#37912) The provider is published in lockstep with LiteLLM: every dev, rc and stable release mirrors terraform/provider/ from the release commit and tags it with the LiteLLM version, alongside the aws/google modules. The 0.x line ends at 0.4.0, and the CHANGELOG headings no longer drive a release. RELEASING.md describes the new flow and how to recover a version whose goreleaser run failed; README gains a Versioning section with the re-pin note for anyone on `~> 0.4`; CHANGELOG records the change under Unreleased. goreleaser gets `prerelease: auto` so a v1.99.0-dev.1 / -rc.1 tag in the mirror is marked as a pre-release instead of becoming the repo's latest release. The registry ingests it either way. --- terraform/provider/.goreleaser.yml | 1 + terraform/provider/CHANGELOG.md | 15 +++- terraform/provider/README.md | 16 +++- terraform/provider/RELEASING.md | 139 ++++++----------------------- 4 files changed, 55 insertions(+), 116 deletions(-) diff --git a/terraform/provider/.goreleaser.yml b/terraform/provider/.goreleaser.yml index f41a29406b8..ba898ed9b2c 100644 --- a/terraform/provider/.goreleaser.yml +++ b/terraform/provider/.goreleaser.yml @@ -72,6 +72,7 @@ signs: - "--detach-sign" - "${artifact}" release: + prerelease: auto extra_files: - glob: 'terraform-registry-manifest.json' name_template: '{{ .ProjectName }}_{{ .Version }}_manifest.json' diff --git a/terraform/provider/CHANGELOG.md b/terraform/provider/CHANGELOG.md index 7c744f04064..ff2f3f817f9 100644 --- a/terraform/provider/CHANGELOG.md +++ b/terraform/provider/CHANGELOG.md @@ -2,11 +2,22 @@ All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +Up to `0.4.0` the provider had its own version line, cut from the headings in +this file. It now ships at the **LiteLLM version**, on every LiteLLM release +channel, built from the same commit as the proxy (see `RELEASING.md`). The +headings below no longer drive a release; they record what changed and which +LiteLLM line first carried it. A change that breaks existing configurations +or state must be called out loudly here, because the version number can no +longer signal it. ## [Unreleased] +### Changed + +- **Versioning**: the provider is now published at the LiteLLM version, from the same commit as the proxy, on every LiteLLM release (dev, rc, stable). The `0.x` line ends at `0.4.0`; a `~> 0.4` constraint will not receive further releases, so re-pin to the LiteLLM version your proxy runs (for example `~> 1.99.0`). Existing `0.x` versions remain in the registry and keep verifying + ## [0.4.0] - 2026-08-06 ### Fixed diff --git a/terraform/provider/README.md b/terraform/provider/README.md index 3b59edd97c6..fe67d6aa430 100644 --- a/terraform/provider/README.md +++ b/terraform/provider/README.md @@ -6,6 +6,18 @@ This Terraform provider allows you to manage LiteLLM resources through Infrastru This directory (`terraform/provider/` in [BerriAI/litellm](https://github.com/BerriAI/litellm)) is the source of truth for the provider. [BerriAI/terraform-provider-litellm](https://github.com/BerriAI/terraform-provider-litellm) is a thin release mirror that the public Terraform Registry ingests from; do not open PRs there. Changes land here, where CI builds the provider, runs its tests, and statically audits every endpoint the provider calls against the proxy's generated OpenAPI schema (`tools/endpointaudit/`), so the provider cannot drift from the LiteLLM API silently. Releases are published by mirroring this directory into the split repo and tagging it, which triggers the goreleaser workflow there (see `RELEASING.md`) +## Versioning + +The provider version **is the LiteLLM version**. Every LiteLLM release (dev, rc and stable) publishes the provider at the same version as the proxy, built from the same commit, so `1.99.0` of the provider is the one that shipped with `1.99.0` of the proxy and was audited against that proxy's API. Pin the provider to the line your proxy runs: + +```hcl +version = "~> 1.99.0" +``` + +Pre-release versions (`1.99.0-rc.1`, `1.99.0-dev.1`) are published too; Terraform only selects one when it is pinned exactly. + +Versions `0.1.0` through `0.4.0` predate this scheme and sit on their own line. They stay in the registry, but **a `~> 0.4` constraint will never pick up another release**: re-pin to the LiteLLM version to keep receiving updates. + ## Features - Manage LiteLLM model configurations @@ -32,7 +44,7 @@ terraform { required_providers { litellm = { source = "BerriAI/litellm" - version = "~> 0.1.1" #HERE UPDATE VERSION ACCORDINGLY + version = "~> 1.99.0" # the LiteLLM version your proxy runs } } } @@ -218,6 +230,6 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS - Always use environment variables or secure secret management solutions to handle sensitive information like API keys and AWS credentials. - Refer to the comprehensive documentation in the `docs/` directory for detailed usage examples and configuration options. -- Make sure to keep your provider version updated for the latest features and bug fixes. +- Keep the provider version in step with the LiteLLM version your proxy runs; see [Versioning](#versioning). - The provider now supports AWS cross-account access with `aws_session_name` and `aws_role_name` parameters in the model resource. - All example configurations have been consolidated into the documentation for better organization and maintenance. diff --git a/terraform/provider/RELEASING.md b/terraform/provider/RELEASING.md index 7b359047e2f..59f4c5f066c 100644 --- a/terraform/provider/RELEASING.md +++ b/terraform/provider/RELEASING.md @@ -4,7 +4,16 @@ This document describes the release process for the LiteLLM Terraform Provider. ## Overview -Releases are automated via GitHub Actions when a version tag is pushed. The workflow builds the provider for multiple platforms, signs the artifacts with GPG, and publishes them to GitHub Releases. +The provider is released **in lockstep with LiteLLM**: every LiteLLM release (dev, rc and stable) publishes the provider at the LiteLLM version, built from the same commit as the proxy. There is no separate provider release to cut. + +The flow, end to end: + +1. `BerriAI/project-releaser`'s release pipeline resolves the commit to release (`main` HEAD for dev; `main` HEAD or an operator-supplied SHA for rc/stable) and passes the release approval gate +2. Its componentized terraform job rsyncs `terraform/provider/` from that commit into `BerriAI/terraform-provider-litellm`, commits, and pushes the tag `v` (for example `v1.99.0`, `v1.99.0-rc.1`, `v1.99.0-dev.1`), alongside the `terraform-aws-litellm` / `terraform-google-litellm` module mirrors which get the same tag +3. The tag push triggers the mirror's own `Release` workflow (goreleaser): multi-platform build, GPG-signed checksums, GitHub release. It runs unattended; project-releaser does not wait for it +4. The public Terraform Registry ingests the GitHub release as provider version `` + +`terraform/provider/` only exists from LiteLLM ~1.95, so a stable patch cut from an older line skips the provider and publishes only the modules. ## Prerequisites @@ -68,113 +77,26 @@ Before publishing to the Terraform Registry: **Note**: The public key fingerprint must match the key used to sign the provider releases. -## Release Steps +## What a change needs -### 1. Prepare the Release +1. **Land it in `BerriAI/litellm`.** Open a PR against `litellm_internal_staging` with the source change and a `CHANGELOG.md` entry under `[Unreleased]`. CI runs `gofmt`, `go vet`, build, tests and the endpoint-drift audit. A change that breaks existing configurations or state must say so in the changelog: the version number cannot signal it any more +2. **Wait for the next LiteLLM release.** The nightly dev release carries it within a day; it reaches a stable version on the next stable cut +3. **Verify** (optional): the version appears at https://registry.terraform.io/providers/BerriAI/litellm and https://github.com/BerriAI/terraform-provider-litellm/releases. If the tag is on the mirror but there is no release, the goreleaser run failed: https://github.com/BerriAI/terraform-provider-litellm/actions -Before creating a release: +Locally, before opening the PR: -1. **Update CHANGELOG.md** - - Move items from `[Unreleased]` section to a new version section - - Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format - - Use [Semantic Versioning](https://semver.org/spec/v2.0.0.html) for version numbers - - Include all notable changes since the last release +```bash +make test +make build +``` - Example: - ```markdown - ## [0.1.2] - 2026-02-20 +## Out-of-band publish or recovery - ### Added - - New feature description +Dispatch `Build and Publish Componentized Images + Chart` in `BerriAI/project-releaser` by hand with only `publish_terraform` enabled and the `git_ref` / `tag` of the release to (re)publish. The run waits on project-releaser's release approval, then mirrors and tags exactly as the pipeline does. - ### Fixed - - Bug fix description +The mirror is push-only: do not commit or tag `BerriAI/terraform-provider-litellm` directly. The publish refuses to overwrite an existing tag; a version that failed in goreleaser is recovered by re-running the mirror's `Release` workflow for that tag, not by re-tagging. - ### Changed - - Changed behavior description - ``` - -2. **Verify tests pass** - ```bash - make test - ``` - -3. **Verify the build works locally** - ```bash - make build - ``` - -4. **Land the changes in BerriAI/litellm** - - Open a PR to `BerriAI/litellm` updating `terraform/provider/CHANGELOG.md` (and any source changes) and merge it - -### 2. Mirror and Tag via project-releaser - -The provider source lives at `terraform/provider/` in `BerriAI/litellm`; `BerriAI/terraform-provider-litellm` is a thin release mirror. Do not commit or tag the mirror directly - -Normally there is nothing to do here. `BerriAI/project-releaser`'s release pipeline runs the same check on every release except `adhoc`, nightly included: it reads the topmost released heading in `terraform/provider/CHANGELOG.md`, probes the mirror for `v`, and dispatches `Publish Terraform provider` only when the changelog has moved ahead of what the mirror carries. Cutting the version heading in step 1 is therefore what releases the provider, and the next release picks it up, so the wait is a day rather than a week - -Dispatch by hand only for an out-of-band release, or to recover a run that failed: - -1. Go to `BerriAI/project-releaser` > **Actions** > `Publish Terraform provider` -2. Click **Run workflow**: - - `git_ref`: full 40-char commit SHA from `BerriAI/litellm` to release from - - `provider_version`: the new version without the `v` prefix (e.g. `0.3.0`) - - `dry_run`: optional; validates without pushing - -Automatic or manual, the run waits on the `production-release` approval in `project-releaser`, then rsyncs `terraform/provider/` into the mirror repo, commits, and pushes tag `v`. That approval is the only one in the flow. The tag push triggers the mirror's `Release` workflow (goreleaser), which runs unattended - -**Important**: -- Tags must follow the format: `v..` (e.g., `v0.1.2`, `v1.0.0`) -- The workflow refuses to overwrite an existing tag; publish a new version instead - -### 3. Monitor the Release Workflow - -1. Go to: https://github.com/BerriAI/terraform-provider-litellm/actions -2. Find the "Release" workflow run for your tag -3. Monitor the progress and check for any errors - -The workflow will: -- Check out the code -- Set up Go -- Import the GPG key -- Run `go mod tidy` -- Build binaries for multiple platforms (Linux, macOS, Windows, FreeBSD) -- Create archives and checksums -- Sign the checksums with GPG -- Create a GitHub release -- Upload all artifacts - -### 4. Verify the Release - -After the workflow completes successfully: - -1. **Check the GitHub Release** - - Go to: https://github.com/BerriAI/terraform-provider-litellm/releases - - Verify the release was created with the correct version - - Confirm all artifacts are present: - - Binary archives for each platform - - SHA256SUMS file - - SHA256SUMS.sig (GPG signature) - - terraform-registry-manifest.json - -2. **Verify the signature** (optional) - ```bash - # Download the checksums and signature - wget https://github.com/BerriAI/terraform-provider-litellm/releases/download/v0.1.2/terraform-provider-litellm_0.1.2_SHA256SUMS - wget https://github.com/BerriAI/terraform-provider-litellm/releases/download/v0.1.2/terraform-provider-litellm_0.1.2_SHA256SUMS.sig - - # Verify the signature - gpg --verify terraform-provider-litellm_0.1.2_SHA256SUMS.sig terraform-provider-litellm_0.1.2_SHA256SUMS - ``` - -### 5. Publish to Terraform Registry (Optional) - -If this provider is published to the Terraform Registry: - -1. The registry should automatically detect the new release via the GitHub webhook -2. If not, you may need to manually trigger a sync on the Terraform Registry dashboard -3. Verify the new version appears at: https://registry.terraform.io/providers/BerriAI/litellm/latest +The mirror's `.github/` directory (the `Release` workflow) is the one thing the rsync preserves, so a change to the goreleaser *workflow* is a direct PR on the mirror; a change to `.goreleaser.yml` itself lands here like any other source change. ## Troubleshooting @@ -207,21 +129,15 @@ If this provider is published to the Terraform Registry: ### Tag Already Exists -**Error**: The publish workflow refuses to push because the tag already exists on the mirror +**Error**: The publish job refuses to push because the tag already exists on the mirror -**Solution**: Tags are immutable by design. Re-run the workflow with a new patch version instead of deleting or moving an existing tag +**Solution**: Tags are immutable by design and the version is the LiteLLM version, so this means the provider was already mirrored for this release. If the registry is missing the version, re-run the mirror's `Release` workflow for the existing tag rather than re-tagging ## Version Numbering -This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html): +The provider version is the LiteLLM version, verbatim: `X.Y.Z` for a stable release, `X.Y.Z-rc.N` for a release candidate and `X.Y.Z-dev.N` for a nightly. It says which proxy the provider shipped with and was audited against; it does not follow SemVer's break-signalling, so breaking changes are announced in `CHANGELOG.md` and the registry docs instead. -- **MAJOR** version (1.0.0): Incompatible API changes -- **MINOR** version (0.1.0): New functionality in a backward-compatible manner -- **PATCH** version (0.0.1): Backward-compatible bug fixes - -For pre-1.0 releases: -- Breaking changes may occur in minor versions -- Patch versions should only contain bug fixes +Versions `0.1.0` to `0.4.0` predate this and remain in the registry on their own line. A `~> 0.4` constraint never receives another release. ## Security Considerations @@ -237,5 +153,4 @@ For pre-1.0 releases: - [Terraform Provider Publishing](https://www.terraform.io/docs/registry/providers/publishing.html) - [HashiCorp GPG Signing Requirements](https://www.terraform.io/docs/registry/providers/publishing.html#signing-releases) - [GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) -- [Semantic Versioning](https://semver.org/) - [Keep a Changelog](https://keepachangelog.com/)