fremforge-provideren for Terraform og OpenTofu

fremforge-provideren administrerer organisasjonens fremforge-innstillinger fra OpenTofu eller HashiCorp Terraform: autentiserings- og tilgangspolicy, tillatelseslisten for IP-adresser, skanne- og skannerpolicy, uforanderlige utgivelser, signaturregler for imager og pakker, avhengighetsproxyen, pakketilgang og registerroboter.

Repositoryer, team og regler for branchbeskyttelse er Forgejo-objekter og blir værende hos fellesskapets provider svalabs/forgejo, slik det er beskrevet i Konfigurasjon som kode. De to providerne fungerer side om side i samme konfigurasjon.

Installasjon

Provideren er publisert på selve frem.sh, så begge CLI-ene installerer den uten ekstra oppsett:

terraform {
  required_providers {
    fremforge = {
      source  = "frem.sh/fremforge/fremforge"
      version = "~> 0.1"
    }
  }
}

tofu init (eller terraform init) finner registeret på https://frem.sh/.well-known/terraform.json, laster ned zip-filen for plattformen din fra cli.frem.sh og sjekker den mot SHA256SUMS, der OpenPGP-signaturen verifiseres med fremforges utgivelsesnøkkel. Det finnes bygg for Linux og macOS (amd64, arm64) og Windows (amd64).

Utgivelsesnøkkelen:

Den private nøkkelen forlater aldri fremforge-plattformen: hver utgivelse signeres av plattformen, og bare for providerens utgivelsesbygg.

Konfigurasjon

provider "fremforge" {
  # endpoint = "https://frem.sh/_app/api/v1"   # the default
}

Provideren leser tokenet sitt fra FREMFORGE_TOKEN. Bruk et API-token for organisasjonen du administrerer, opprettet under Organisasjonsadministrasjon → API-tokener (frem.sh/<org>/_admin/api-tokens), med de scopene ressursene dine trenger. Ha et skrivebeskyttet token for plan og skrivescopet for jobben som kjører apply:

Ressurser

Organisasjonsinnstillinger er singletons: hver organisasjon har dem alltid, og API-et har ingen sletting. Alle argumenter er valgfrie. Bare argumentene du setter, skrives; de andre leses tilbake i state og blir stående urørt, så en endring noen gjør i konsollen på en innstilling du ikke administrerer, er ikke et avvik. Importer en singleton med organisasjonens slug.

Hver singleton er også en datakilde med samme navn.

Samlinger har ekte opprettelse og sletting:

Et pakkenavn kan inneholde / (et npm-scope, en containersti), og derfor står det sist i import-ID-ene.

Eksempel

resource "fremforge_auth_policy" "this" {
  org                   = "acme"
  max_pat_lifetime_days = 30
  allow_user_pats       = false
  ssh_disabled          = true
}

resource "fremforge_ssh_ca" "this" {
  org          = "acme"
  ca_keys      = [file("ssh-ca.pub")]
  require_cert = true
}

resource "fremforge_scan_policy" "images" {
  org            = "acme"
  scanner        = "image_scan"
  mode           = "enforce"
  block_severity = "high"
}

Fjernede innstillinger

To innstillinger ble fjernet fra fremforge 2026-10-14, fordi de ble lagret, men aldri tatt i bruk: principal_policy på fremforge_ssh_ca og default_template_repo på fremforge_branch_protection_defaults. Fra og med provider 0.1.1 er begge attributtene utfaset: provideren sender og leser dem ikke lenger, så en konfigurasjon som fortsatt setter dem, virker videre og planlegger uten endringer, og tofu plan skriver ut en advarsel om utfasing. Fjern dem fra konfigurasjonen din; ingenting endres når du gjør det. Se Branchbeskyttelse og SSH-sertifikatutsteder.

Scoped CI-secrets: verdien havner aldri i state

fremforge_ci_secret (fra provider 0.9.0) styrer én scoped CI-secret. Verdien er et write-only-argument, value_wo: den sendes når secreten opprettes og ved hver endring (API-et erstatter verdi og scope samlet), og den leses aldri tilbake og lagres aldri i plan eller state. Write-only-argumenter krever OpenTofu 1.11 eller Terraform 1.11 eller nyere. Utelat repository_id for hele organisasjonen; øk value_wo_version for å skrive en ny verdi.

variable "deploy_key" {
  type      = string
  sensitive = true
  ephemeral = true
}

resource "fremforge_ci_secret" "deploy" {
  org              = "acme"
  name             = "DEPLOY_KEY"
  repository_id    = 42
  value_wo         = var.deploy_key
  value_wo_version = 1
  workflows        = ["deploy.yaml"]
  refs             = ["refs/heads/main"]
  events           = ["push", "workflow_dispatch"]
  environment      = "production"
}

• Rotasjon: fremforge kan ikke vise verdien, så en ny value_wo alene er ingen endring. Øk value_wo_version for å skrive den.
• Drift: en endring av scope eller beskrivelse gjort utenfor konfigurasjonen din vises i planen; en endring av verdien gjør ikke det.
• Oppretting tar aldri over: finnes det allerede en secret med det navnet og repositoryet, feiler apply og ber deg importere den.
• Import: <org>/<NAME> for en secret for hele organisasjonen, <org>/<repository id>/<NAME> for en som er bundet til et repository. Sett value_wo i konfigurasjonen før neste apply.
• Token-scopes: providerens token trenger ci-secrets:read og ci-secrets:write.

Scope-argumentene avvises før noen forespørsel sendes når de kunne utvide leveringen: en tom oppføring, et reservert navn (FORGEJO_, GITHUB_, GITEA_) eller en repository-id som ikke er et positivt tall.

Tokener for registerroboter havner aldri i state

Tokenet til en registerrobot vises av API-et én gang, når det utstedes. Provideren lagrer det aldri i state, i noe attributt. Den skriver tokenet én gang, når API-et utsteder det (ved opprettelse, og hver gang du endrer rotation), til filen du oppgir i token_file, med modus 0600, og overskriver aldri en eksisterende fil:

resource "fremforge_registry_robot" "ci" {
  org        = "acme"
  name       = "ci-pull"
  access     = "read"
  token_file = "${path.module}/.robot-ci.token"
  rotation   = "2026-10"   # change to issue a new token; the old one is revoked at once
}

Uten token_file blir tokenet forkastet. Flytt filen bort før du roterer igjen.

Avvik, import og destroy

• Avvik: plan -detailed-exitcode avslutter med 2 når en innstilling du administrerer, er endret utenfor konfigurasjonen din; apply setter den tilbake.
• Import: import { to = fremforge_auth_policy.this; id = "acme" }, og deretter skriver tofu plan -generate-config-out=generated.tf konfigurasjonen for deg.
• Destroy: for en singleton fjerner destroy den bare fra state og endrer ingenting i organisasjonen: å skrive standardverdier ville i det stille svekket en sikkerhetsinnstilling. Samlinger slettes. fremforge_package_access fjerner pakkens innstillinger og alle tildelinger på den.

Flytte fra modulen

Modulen forblir dokumentert mens du flytter. For hver innstilling legger du til providerressursen, importerer den med organisasjonens slug, sjekker at plan ikke viser noen endringer, og fjerner deretter modulens argument og kjører tofu state rm på dens restful_resource.

Slik tester vi den

Hver ressurs og datakilde kjøres gjennom den ekte OpenTofu-CLI-en mot et innspilt fremforge-API ved hver endring: bare argumentene du setter, skrives, endringer som ikke administreres, ignoreres, avvik i det som administreres, planlegges, import leser tilbake samme state, og destroy oppfører seg som beskrevet over.

Innstillingene som er trygge å endre i en delt organisasjon, kjøres også live mot en testorganisasjon hver natt: apply, en ren plan, en endring gjort via API-et, en plan som viser den, apply, import til ny state, en ren plan, destroy, en tilbakelesing, og den opprinnelige verdien gjenopprettet. Det gjelder autentiseringspolicyen, SSH-CA-en, SLA-policyen og metadatafilteret i avhengighetsproxyen; pakketilgang, beskyttelsesregler og registerroboter ble kjørt live på samme måte før utgivelsen. Tillatelseslisten for IP-adresser og signaturpolicyene testes bare mot det innspilte API-et, fordi endringer i dem i en delt organisasjon ville forstyrret andre tester.