RunR v0.7.5

Documentation

runr_runtime_source (Resource)

A runtime source (runtime sources): an OCI catalog of signed manifests (kind = "oci-catalog") or a Git repository with <path>/<id>/runtime.yaml (kind = "git"), public or private, that RunR reads runtimes from — when it is connected or changed, every interval_minutes and when sync_trigger changes. A platform source (a token with runtimes.manage) gives every organization its runtimes; a source of the organization (runtimes.use_custom, while the platform allows custom runtimes) only its members.

A read that fails (status unreachable, not_found, auth_failed, invalid_signature, invalid_catalog) leaves the source's runtimes as they were and is a warning, not an error: the source is connected. A runtime manifest with problems is refused (status = "partial", problems with file and JSON path), the others are read. Check the read with a postcondition on status where it must succeed.

The credentials are write-only: RunR never returns them (credentials says which are set). Terraform keeps what it set (git_token, ssh_private_key, registry_password, sensitive), or with the _wo attributes (Terraform 1.11 and later) nothing — change credentials_wo_version to write new ones. Credentials changed or removed outside Terraform are written again. Destroying the source deletes its runtimes no project uses; the others stay, orphaned, until their sunset. RunR's own catalog (the default source) is the installation's: read it with data.runr_runtime_source. Import with the source's id or name (the credentials are not imported).

Example Usage#

# A private Git repository of runtimes (runtimes/<id>/runtime.yaml on the main branch), read
# with an access token Terraform never stores (write-only, Terraform 1.11 and later).
variable "runtimes_token" {
  type      = string
  sensitive = true
  ephemeral = true
}

resource "runr_runtime_source" "acme" {
  name                   = "acme-runtimes"
  kind                   = "git"
  url                    = "https://gitlab.example.com/acme/runtimes.git"
  ref                    = "main"
  git_token_wo           = var.runtimes_token
  credentials_wo_version = "2026-11" # change it to write a rotated token
  interval_minutes       = 30

  # Read the repository now when a new runtimes release is tagged.
  sync_trigger = "v1.4.0"

  lifecycle {
    postcondition {
      condition     = self.status == "ok"
      error_message = "RunR could not read every runtime of acme-runtimes (${self.status}): ${coalesce(self.error, "see problems")}"
    }
  }
}

# A signed OCI catalog in a private registry, with its patch feed.
resource "runr_runtime_source" "catalog" {
  name              = "acme-catalog"
  kind              = "oci-catalog"
  url               = "registry.example.com/acme/runtimes:catalog"
  public_key        = file("${path.module}/cosign.pub")
  patch_feed        = "registry.example.com/acme/runtimes:patches"
  registry_username = "runr"
  registry_password = var.registry_password
}

variable "registry_password" {
  type      = string
  sensitive = true
}

# Projects use a runtime of a source by its id.
resource "runr_project" "script" {
  name      = "nightly-report"
  type      = "xaas"
  runtime   = "bash"
  region_id = data.runr_region.eu.id

  depends_on = [runr_runtime_source.acme]
}

Schema#

Required#

  • kind (String) git (a repository of <path>/<id>/runtime.yaml) or oci-catalog (a signed catalog of manifests).
  • name (String) Name, unique in its scope (at most 64 characters).
  • url (String) The repository (https://… or git@host:owner/repo.git) or the catalog's OCI reference (registry/repo:tag).

Optional#

NOTE: Write-only arguments are supported in Terraform 1.11 and later.

  • credentials_wo_version (String) Any string; a change writes the _wo credentials again (for example a rotation date).
  • enabled (Boolean) Whether RunR reads the source on its interval (default true); off, its runtimes stay as last read.
  • git_token (String, Sensitive) git over HTTPS: access token (sensitive). One of git_token, git_token_wo, ssh_private_key and ssh_private_key_wo at most.
  • git_token_wo (String, Sensitive, Write-only) git_token that Terraform never stores (write-only, Terraform 1.11 and later); change credentials_wo_version to write a new one.
  • git_username (String) git over HTTPS: user name of the token (default x-access-token).
  • interval_minutes (Number) Minutes between reads: at least the platform's minimum (5 unless configured otherwise), at most a week. Left out: 60 for a new source, an existing one keeps its interval.
  • patch_feed (String) OCI reference of the source's signed runtime patch feed (needs public_key).
  • path (String) git: directory of the runtimes (default runtimes).
  • public_key (String) cosign public key (PEM) the catalog and the patch feed must verify with, e.g. file("cosign.pub").
  • ref (String) git: branch, tag or commit (default the repository's default branch).
  • registry_host (String) Registry the registry credentials are for (ghcr.io, registry.example.com:5000); required with registry credentials of a git source (the registry of its runtime images).
  • registry_password (String, Sensitive) Registry password or token (sensitive).
  • registry_password_wo (String, Sensitive, Write-only) registry_password that Terraform never stores (write-only, Terraform 1.11 and later); change credentials_wo_version to write a new one.
  • registry_username (String) Registry user for a private catalog, patch feed or runtime images (with registry_password or registry_password_wo).
  • ssh_known_hosts (String) git over SSH: known_hosts of the host; without it the host key is accepted on first use.
  • ssh_private_key (String, Sensitive) git over SSH (git@… URL): the deploy key (sensitive), e.g. file("deploy_key").
  • ssh_private_key_wo (String, Sensitive, Write-only) ssh_private_key that Terraform never stores (write-only, Terraform 1.11 and later); change credentials_wo_version to write a new one.
  • sync_trigger (String) Any string; a change reads the source now (for example the tag or commit runtimes were released with). Every other change reads it as well.

Read-Only#

  • checked_at (String) When RunR last read the source.
  • credentials (Attributes) Which credentials the source has, as RunR reports them (never a value). (see below for nested schema)
  • error (String) Why the last read failed.
  • id (String) Source id.
  • problems (Attributes List) The problems of the last read: file, runtime, path (JSON path in the manifest), message. (see below for nested schema)
  • revision (String) Catalog digest or commit of the last good read.
  • runtimes_count (Number) Runtimes the source gives.
  • scope (String) platform (connected with runtimes.manage: every organization) or organization.
  • signature_verified (Boolean) The last read's catalog verified with public_key.
  • status (String) The last read: never, ok, partial (some manifests refused: problems), unreachable, not_found, auth_failed, invalid_signature, invalid_catalog or disabled.
  • synced_at (String) When the last good read was.

Nested Schema for credentials#

Read-Only:

  • git (String) token (HTTPS), ssh (a deploy key) or null.
  • git_token_hint (String) The token's last four characters behind a mask (tokens longer than eight characters).
  • git_username (String) User name of the Git token (null: x-access-token).
  • known_hosts_set (Boolean) known_hosts is set (without it the host key is accepted on first use).
  • registry_password_set (Boolean) A registry password is set.
  • registry_username (String) The registry user.
  • ssh_key_set (Boolean) A deploy key is set.

Nested Schema for problems#

Read-Only:

  • file (String) The file (a Git source's <path>/<id>/runtime.yaml).
  • message (String) The problem.
  • path (String) JSON path in the manifest.
  • runtime (String) The runtime id or directory.

Import#

Import is supported using the following syntax:

The terraform import command can be used, for example:

# <source id or name>. The credentials are not imported: the next apply writes the configured
# ones (with the _wo attributes, set credentials_wo_version). RunR's catalog cannot be imported.
terraform import runr_runtime_source.acme acme-runtimes

RunR v0.7.5 · MIT License