unkin-agent
c69c3d9f74
The provider exposed mirrorlist but not mirror_strategy, so the API's mirror load-balancing strategy (round_robin/least_conn) was unreachable via Terraform. Add mirror_strategy the same way mirrorlist was added, scoped to rpm/deb/alpine remotes. - schema: optional string mirror_strategy on the remote resource - ValidateConfig: reject on non-rpm/deb/alpine types and validate the round_robin/least_conn enum at plan time - wire model + modelToAPI/apiToModel (empty->null to avoid perpetual diff) - datasource (computed) + README + rpm example - unit tests: modelToAPI/apiToModel round-trip and ValidateConfig matrix
276 lines
10 KiB
Markdown
276 lines
10 KiB
Markdown
# terraform-provider-artifactapi
|
|
|
|
Terraform provider for managing [ArtifactAPI](https://git.unkin.net/unkin/artifactapi) remotes and virtual repositories.
|
|
|
|
## Requirements
|
|
|
|
- Go >= 1.23
|
|
- Terraform >= 1.0
|
|
|
|
## Building
|
|
|
|
```sh
|
|
make build
|
|
```
|
|
|
|
## Installation
|
|
|
|
Install the provider to your local Terraform plugin directory:
|
|
|
|
```sh
|
|
make install
|
|
```
|
|
|
|
This places the binary at `~/.terraform.d/plugins/git.unkin.net/unkin/artifactapi/<version>/<os_arch>/`.
|
|
|
|
## Provider Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
required_providers {
|
|
artifactapi = {
|
|
source = "git.unkin.net/unkin/artifactapi"
|
|
version = "0.0.1"
|
|
}
|
|
}
|
|
}
|
|
|
|
provider "artifactapi" {
|
|
endpoint = "https://artifactapi.example.com"
|
|
}
|
|
```
|
|
|
|
| Attribute | Required | Description |
|
|
|------------|----------|--------------------------------------|
|
|
| `endpoint` | Yes | ArtifactAPI server endpoint URL |
|
|
|
|
## Resources
|
|
|
|
### Remote Resources
|
|
|
|
Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
|
|
|
|
Available resource types:
|
|
|
|
- `artifactapi_remote_generic`
|
|
- `artifactapi_remote_docker`
|
|
- `artifactapi_remote_helm`
|
|
- `artifactapi_remote_pypi`
|
|
- `artifactapi_remote_npm`
|
|
- `artifactapi_remote_rpm`
|
|
- `artifactapi_remote_deb`
|
|
- `artifactapi_remote_alpine`
|
|
- `artifactapi_remote_puppet`
|
|
- `artifactapi_remote_terraform`
|
|
- `artifactapi_remote_goproxy`
|
|
- `artifactapi_remote_github_rpm`
|
|
- `artifactapi_remote_github_deb`
|
|
- `artifactapi_remote_github_alpine`
|
|
|
|
#### Common Attributes
|
|
|
|
| Attribute | Required | Default | Description |
|
|
|----------------------|----------|---------|-------------------------------------------------------------------|
|
|
| `name` | Yes | | Unique name (forces replacement on change) |
|
|
| `base_url` | Yes | | Upstream repository URL |
|
|
| `description` | No | `""` | Human-readable description |
|
|
| `username` | No | `""` | Upstream auth username (sensitive) |
|
|
| `password` | No | `""` | Upstream auth password (sensitive) |
|
|
| `immutable_ttl` | No | `0` | TTL in seconds for immutable artifacts (0 = cache forever) |
|
|
| `mutable_ttl` | No | `3600` | TTL in seconds for mutable artifacts |
|
|
| `check_mutable` | No | `true` | Enable conditional revalidation for mutable artifacts |
|
|
| `patterns` | No | | Allowlist of path patterns to proxy (empty = all) |
|
|
| `blocklist` | No | | Paths to always deny (checked before patterns) |
|
|
| `mutable_patterns` | No | | Override: treat matching paths as mutable |
|
|
| `immutable_patterns` | No | | Override: treat matching paths as immutable |
|
|
| `quarantine_enabled` | No | `false` | Enable quarantine for new artifacts |
|
|
| `quarantine_days` | No | `3` | Days to quarantine new artifacts |
|
|
| `stale_on_error` | No | `true` | Serve stale cache when upstream is unreachable |
|
|
| `upstream_dial_timeout` | No | `0` | Upstream TCP connect timeout in seconds (0 = server default) |
|
|
| `upstream_tls_timeout` | No | `0` | Upstream TLS handshake timeout in seconds (0 = server default) |
|
|
| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
|
|
|
|
#### rpm / deb / alpine-specific Attributes
|
|
|
|
| Attribute | Default | Description |
|
|
|-------------------|---------------|-------------------------------------------------------------------------------------------------|
|
|
| `mirrorlist` | | Extra upstream mirror base URLs. Requests are load-balanced with failover across `base_url` + `mirrorlist`. |
|
|
| `mirror_strategy` | `round_robin` | Mirror load-balancing strategy across `base_url` + `mirrorlist`. One of `round_robin` or `least_conn`. |
|
|
|
|
Only valid on the `artifactapi_remote_rpm`, `artifactapi_remote_deb`, and
|
|
`artifactapi_remote_alpine` resources. Setting either on any other remote type is
|
|
rejected at plan time.
|
|
|
|
```hcl
|
|
resource "artifactapi_remote_rpm" "epel" {
|
|
name = "epel-9"
|
|
base_url = "https://download.example.com/pub/epel/9/Everything/x86_64"
|
|
mirrorlist = [
|
|
"https://mirror-a.example.net/epel/9/Everything/x86_64",
|
|
"https://mirror-b.example.org/epel/9/Everything/x86_64",
|
|
]
|
|
mirror_strategy = "least_conn"
|
|
}
|
|
```
|
|
|
|
#### Docker-specific Attributes
|
|
|
|
| Attribute | Default | Description |
|
|
|--------------------|---------|----------------------------|
|
|
| `ban_tags_enabled` | `false` | Enable tag banning |
|
|
| `ban_tags` | | List of tags to ban |
|
|
|
|
#### Terraform / github_rpm / github_deb / github_alpine-specific Attributes
|
|
|
|
| Attribute | Default | Description |
|
|
|-------------------|---------|----------------------------------------------------------|
|
|
| `releases_remote` | `""` | Name of a backend remote that serves the download bytes. Terraform uses it for download URL rewriting; `github_rpm`/`github_deb`/`github_alpine` 302-redirect `.rpm`/`.deb`/`.apk` downloads to it. |
|
|
|
|
#### github_rpm-specific notes
|
|
|
|
`artifactapi_remote_github_rpm` exposes a GitHub repo's releases as a `dnf`/`yum`
|
|
repository without precaching packages. Set `base_url` to the releases API root
|
|
(`https://api.github.com/repos/{owner}/{repo}`) and `releases_remote` to a
|
|
generic `github.com` remote that streams the `.rpm` bytes. `patterns` filters
|
|
which release assets become packages (regex on asset filename). `password` may
|
|
hold a token for private repos or higher API rate limits. See
|
|
`examples/resources/artifactapi_remote_github_rpm/main.tf`.
|
|
|
|
#### github_deb-specific notes
|
|
|
|
`artifactapi_remote_github_deb` is the Debian/apt analog of `github_rpm`: it
|
|
exposes a GitHub repo's release `.deb` assets as an `apt` repository, synthesizing
|
|
the apt index (`Packages`/`Release`) from release metadata without precaching
|
|
packages. Set `base_url` to the releases API root
|
|
(`https://api.github.com/repos/{owner}/{repo}`) and `releases_remote` to a
|
|
generic `github.com` remote that streams the `.deb` bytes; `.deb` downloads
|
|
302-redirect there. `patterns` filters which release assets become packages
|
|
(regex on asset filename). `password` may hold a token for private repos or
|
|
higher API rate limits. See
|
|
`examples/resources/artifactapi_remote_github_deb/main.tf`.
|
|
|
|
#### github_alpine-specific notes
|
|
|
|
`artifactapi_remote_github_alpine` is the Alpine/apk analog of `github_rpm`: it
|
|
exposes a GitHub repo's release `.apk` assets as an `apk` repository, synthesizing
|
|
the apk index (`APKINDEX.tar.gz`) from release metadata without precaching
|
|
packages. Set `base_url` to the releases API root
|
|
(`https://api.github.com/repos/{owner}/{repo}`) and `releases_remote` to a
|
|
generic `github.com` remote that streams the `.apk` bytes; `.apk` downloads
|
|
302-redirect there. `patterns` filters which release assets become packages
|
|
(regex on asset filename). `password` may hold a token for private repos or
|
|
higher API rate limits. See
|
|
`examples/resources/artifactapi_remote_github_alpine/main.tf`.
|
|
|
|
#### Example
|
|
|
|
```hcl
|
|
resource "artifactapi_remote_docker" "dockerhub" {
|
|
name = "dockerhub"
|
|
base_url = "https://registry-1.docker.io"
|
|
|
|
immutable_ttl = 0
|
|
mutable_ttl = 300
|
|
ban_tags_enabled = true
|
|
ban_tags = ["latest"]
|
|
|
|
patterns = [
|
|
"^library/postgres",
|
|
"^library/redis",
|
|
]
|
|
}
|
|
```
|
|
|
|
### Local Resources
|
|
|
|
Local resources manage repositories that ArtifactAPI hosts directly (rather than
|
|
proxying an upstream) — each is a real registry for its package type.
|
|
|
|
Available resource types:
|
|
|
|
- `artifactapi_local_docker` — a container registry (Docker Registry HTTP API V2, push and pull)
|
|
- `artifactapi_local_pypi`
|
|
- `artifactapi_local_rpm`
|
|
- `artifactapi_local_deb`
|
|
- `artifactapi_local_alpine`
|
|
- `artifactapi_local_terraform`
|
|
|
|
Each takes just `name` (required, forces replacement) and an optional
|
|
`description`.
|
|
|
|
```hcl
|
|
resource "artifactapi_local_docker" "internal" {
|
|
name = "docker-internal"
|
|
description = "Internal container image registry"
|
|
}
|
|
```
|
|
|
|
Images push and pull against `<endpoint>/<name>/<image>:<tag>`, e.g.
|
|
`docker push artifactapi.example.com/docker-internal/myapp:latest`.
|
|
|
|
### Virtual Resources
|
|
|
|
Virtual repositories merge multiple remotes of the same package type into a single endpoint.
|
|
|
|
```hcl
|
|
resource "artifactapi_virtual" "helm" {
|
|
name = "helm"
|
|
package_type = "helm"
|
|
description = "All helm repos merged"
|
|
|
|
members = [
|
|
artifactapi_remote_helm.jetstack.name,
|
|
artifactapi_remote_helm.hashicorp_helm.name,
|
|
]
|
|
}
|
|
```
|
|
|
|
| Attribute | Required | Description |
|
|
|----------------|----------|-------------------------------------------|
|
|
| `name` | Yes | Unique name (forces replacement on change)|
|
|
| `package_type` | Yes | Package type of member remotes |
|
|
| `description` | No | Human-readable description |
|
|
| `members` | Yes | List of remote names to include |
|
|
|
|
## Data Sources
|
|
|
|
### `artifactapi_remote`
|
|
|
|
Read an existing remote's configuration.
|
|
|
|
```hcl
|
|
data "artifactapi_remote" "dockerhub" {
|
|
name = "dockerhub"
|
|
}
|
|
```
|
|
|
|
### `artifactapi_virtual`
|
|
|
|
Read an existing virtual repository's configuration.
|
|
|
|
```hcl
|
|
data "artifactapi_virtual" "helm" {
|
|
name = "helm"
|
|
}
|
|
```
|
|
|
|
## Import
|
|
|
|
Resources can be imported by name:
|
|
|
|
```sh
|
|
terraform import artifactapi_remote_docker.dockerhub dockerhub
|
|
terraform import artifactapi_virtual.helm helm
|
|
```
|
|
|
|
## Development
|
|
|
|
```sh
|
|
make build # Build the provider binary
|
|
make install # Install to local plugin directory
|
|
make test # Run tests
|
|
make lint # Run go vet
|
|
make fmt # Format code
|
|
make clean # Remove binary
|
|
```
|