terraform-provider-bahriya

The official Terraform provider for Bahriya — manage every Bahriya resource declaratively.

Status: pre-release. Not yet published to the Terraform registry. Track progress on Nextcloud Deck card #928.

Table of contents

• Installation
• Quickstart
• Provider configuration
• Authentication
• Resources
• Data sources
• Important behaviours
• Examples
• Building from source
• Local development
• Architecture
• Repository layout
• Testing

Installation

Once published (target state)

terraform {
  required_providers {
    bahriya = {
      source  = "bahriya-cloud/bahriya"
      version = "~> 0.1"
    }
  }
}

Currently — from source

See Building from source and Local development below.

Quickstart

terraform {
  required_providers {
    bahriya = { source = "bahriya-cloud/bahriya" }
  }
}

provider "bahriya" {}

data "bahriya_regions" "active" {
  status_filter = "active"
}

resource "bahriya_project" "web" {
  handle  = "web-prod"
  name    = "Web Production"
  regions = [data.bahriya_regions.active.regions[0].id]
}

resource "bahriya_registry" "ghcr" {
  handle   = "ghcr"
  name     = "GitHub Container Registry"
  server   = "ghcr.io"
  username = var.ghcr_username
  password = var.ghcr_token
}

resource "bahriya_secret" "db_password" {
  handle = "db-password"
  name   = "Database Password"
  value  = var.db_password
}

resource "bahriya_container" "api" {
  handle    = "api"
  name      = "API Server"
  image     = "ghcr.io/myorg/api:1.2.3"

  # Required for HTTP containers — deploy will fail without these
  containerport   = "3000"
  healthcheckpath = "/healthz"

  mincpu    = "250"
  minmemory = "256"

  autoscalingminreplicas = "2"
  activeregions          = [data.bahriya_regions.active.regions[0].id]
  project                = bahriya_project.web.id
  registry               = bahriya_registry.ghcr.handle

  secretsenvvar {
    secret = bahriya_secret.db_password.handle
    name   = "DATABASE_PASSWORD"
  }

  hostnames {
    hostname = "api.example.com"
  }
}

Provider configuration

Attributes on the provider block override env vars. For multi-org setups, use alias:

provider "bahriya" {
  alias           = "prod"
  organisation_id = var.prod_org_id
}

provider "bahriya" {
  alias           = "staging"
  organisation_id = var.staging_org_id
}

Authentication

The provider uses Bahriya personal access tokens (PATs):

1. Sign in to the console at https://app.bahriya.cloud.
2. Open your profile, then Tokens.
3. Click Create token, copy the pat_... value.

export BAHRIYA_TOKEN="pat_..."
export BAHRIYA_ORGANISATION_ID="65cc42f1-..."

Resources

Each vault/config item also has a corresponding bahriya_project_<type>_attachment resource that binds an item to a project. Once attached, the item can be referenced from a bahriya_container block to mount it inside the container.

All resource schemas are code-generated from the OpenAPI specs at packages/bahriya-openapi/specs/v1/.

The bahriya_organisation and bahriya_regions data sources are also E2E verified.

End-to-end coverage

examples/e2e-vault-configs/ is the comprehensive E2E: in a single apply/destroy it exercises every resource above plus both data sources — registry + secret and all vault/config items with their project attachments, a network policy, memcached, and HTTP + worker + cronjob containers wired to the full set of mounts, env vars, secret env vars, persistent storage and path rules. Run ./gen-fixtures.sh (once) to mint crypto fixtures and a fresh handle suffix, then terraform apply.

Secret-sync timing. A container that consumes a secret (via secretsenvvar) or an env file (via envfiles/envFrom) will only reach running once the project's bahriya-secrets bundle has synced into the namespace. On a brand-new project the first container deploy can lose that race and land in error; re-running the apply (once the sync has completed) brings it to running. This is a platform deploy-pipeline ordering concern, not a provider behaviour — the provider creates and attaches the secret and orders the container after it.

Minimum required fields

These are the fields you must set for a successful deploy. Omitting any of these will cause errors (API rejection or runtime health-check failures).

bahriya_container (HTTP)

bahriya_container (worker / cronjob)

Same as HTTP except containerport and healthcheckpath are not required (workers have no ingress).

bahriya_memcached

bahriya_project

bahriya_registry

bahriya_secret

Vault items

All vault types require handle and name plus the content fields below. Handles are immutable. Items are soft-deleted (handle burned).

The API parses content on create / rotate — invalid material is rejected.

Config items

Networking

Project attachments

Each vault/config type has a corresponding attachment resource (bahriya_project_tls_bundle_attachment, etc.). All take exactly two required fields:

Both attributes force replacement on change. Attachment is also blocked at the API if a container in the project still references the item.

Data sources

Important behaviours

Handles cannot be reused (soft-delete)

For projects, containers, and memcached, deleting in Terraform does not free up the handle. These resources are soft-deleted for billing and audit reasons.

• Use distinct handles per environment (api-prod, api-staging).
• Treat handles as permanent identifiers.

For registries and secrets, handles are released on delete and can be reused.

Async termination

Destroying a bahriya_container or bahriya_memcached triggers async termination. The provider polls until the resource reaches terminated status (default timeout: 10 minutes).

Renaming a handle is destroy + recreate

Handles are immutable. Changing the handle attribute forces Terraform to destroy and recreate the resource.

Imports use UUIDs

terraform import bahriya_container.api 065df92e-4e46-436a-a0a0-aaaaaaaaaaaa

Sensitive fields

Registry password and secret value are marked sensitive. The API returns masked sentinels on read; the provider preserves the real value from your Terraform state.

Vault item content fields (bahriya_tls_bundle.key, bahriya_gpg_keypair.private_key / .public_key, bahriya_ssh_keypair.private_key / .public_key, bahriya_encryption_key.key) are also sensitive and follow the same masking pattern.

Removing a nested attachment block must be explicit

Container nested-list attributes (tls_bundles, x509_certs, gpg_keypairs, ssh_keypairs, encryption_keys, env_files, yaml_configs, json_configs, plain_configs, persistentvolumes, hostnames, initjobs, secretsenvvar, newenvvar) are Optional+Computed with the UseStateForUnknown plan modifier — needed for stable plans against the API's PUT-replace semantics. As a consequence, omitting a block in your .tf does NOT remove the attachment; the prior state value is re-injected silently.

To remove a vault/config attachment from a container, set the block to an explicit empty list:

resource "bahriya_container" "api" {
  # ...
  json_configs = []   # explicit removal — works
  # plain_configs    # omitting — does NOT remove; prior list is preserved
}

Detach guard

Attempting to detach a vault/config item from a project while a container in that project still references it returns 409 CONFLICT with the offending container's handle. Update the container to remove the reference first.

Container Update waits for status

After a terraform apply that modifies a container, the provider waits for the container to reach running (or terminal error) before completing the apply. This avoids "inconsistent result after apply" errors when the post-PUT fetch would otherwise race the helm rollout.

Common pitfalls

Examples

Runnable configs live under examples/:

Building from source

Requires Go 1.23+.

git clone <repo-url>
cd terraform-provider-bahriya
make build        # builds ./bin/terraform-provider-bahriya
make test         # runs all 63 unit tests
make generate     # regenerates resource code from OpenAPI specs
make verify       # generate + git diff (CI gate)

Local development

Add a dev_overrides block to ~/.terraformrc:

provider_installation {
  dev_overrides {
    "bahriya-cloud/bahriya" = "/path/to/terraform-provider-bahriya/bin"
  }
  direct {}
}

Then just make build and run terraform plan/apply — no terraform init needed between rebuilds.

Set credentials via environment variables:

export BAHRIYA_TOKEN="pat_..."
export BAHRIYA_ORGANISATION_ID="..."
# Optional: override API URL for dev
export BAHRIYA_API_URL="http://localhost:8080/console/v1"

Architecture

This is a code-generated provider. The OpenAPI specs at packages/bahriya-openapi/specs/v1/ are the source of truth. A Go generator reads those specs and emits Terraform resources with full CRUD, ImportState, diff short-circuit, and status polling.

What's generated

• All 5 resource files (internal/resources/*_resource.go) — ~3,800 LOC total
• Resource registry (internal/resources/registry.go)
• Terraform schemas with nested attributes for complex types (Container has 6 nested object types)
• Plan modifiers (RequiresReplace for handles, UseStateForUnknown for computed fields)
• Sensitive field preservation (password, value)

What's hand-written

• Provider scaffold (internal/provider/) — schema, Configure, env-var fallbacks
• HTTP client (internal/client/) — PAT auth, retries, typed errors
• Data sources (internal/datasources/) — organisation, region, regions
• Transforms (internal/transforms/) — envvar/secret dict-to-array, x-implies
• Lifecycle (internal/lifecycle/) — WaitForStatus with backoff
• Helpers (internal/resources/helpers.go) — small utilities for generated code
• Code generator (cmd/generator/) — parser, model, renderer, template

Generated files are committed to git. make verify fails CI if they drift.

Releasing

The source of truth is on 1x.ax (origin). GitHub (github) is a mirror that feeds the Terraform Registry. Push to both:

# Push code
git push origin && git push github

# Push tags (triggers the GitHub Actions release workflow)
git push origin --tags && git push github --tags

To cut a release:

git tag v0.1.0
git push origin && git push origin --tags && git push github && git push github --tags

The GitHub Actions workflow runs GoReleaser, builds cross-platform binaries, signs the checksums with GPG, and publishes the release. The Terraform Registry picks it up automatically.

Repository layout

terraform-provider-bahriya/
├── cmd/
│   ├── terraform-provider-bahriya/   # plugin entrypoint
│   └── generator/                    # codegen tool
│       ├── templates/                # text/template for resources
│       └── parser_test.go            # generator unit tests
├── internal/
│   ├── client/       # HTTP client + tests
│   ├── provider/     # provider block + tests
│   ├── resources/    # GENERATED — do not edit by hand
│   ├── datasources/  # data sources + tests
│   ├── transforms/   # envvar, secret, implies + tests
│   └── lifecycle/    # WaitForStatus + tests
├── examples/         # 6 runnable Terraform configs
├── Makefile
├── go.mod
└── .gitignore

Testing

63 unit tests across all packages:

make test           # runs go test ./internal/... and cmd/generator