Add OCI based deployment support for binding providers

Author: akclace

CHANGELOG.md

@@ -7,8 +7,12 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [v0.18.7] - 2026-07-20
+
 ### Added
 
+- Added out-of-process binding providers: new binding types (mongodb, redis/valkey, sqlserver, oracle) are built as standalone executables in the [openrundev/bindings](https://github.com/openrundev/bindings) repo and invoked by the server over gRPC using hashicorp/go-plugin, so adding a binding type no longer grows the openrun binary or its dependency tree. Providers are installed with the new `openrun provider install/uninstall/list` commands (`/_openrun/provider` APIs, gated by the new `provider:read` / `provider:manage` RBAC permissions); the install is recorded in the metadata database with pinned sha256 checksums, so it survives restarts and propagates to all server replicas — each replica materializes the verified binaries into the `bindings.cache_dir` local cache at startup, before serving traffic, making installs work on Kubernetes multi-replica deployments.
+- Added the OCI image distribution path for binding providers: each provider release also publishes a minimal `FROM scratch` image (`ghcr.io/openrundev/openrun-binding-<name>`), and the Helm chart's `bindings.images` values render one init container per provider which copies the binary (via the provider binary's new `export` subcommand) into a shared volume. The server registers pre-placed provider executables from the new `bindings.preinstalled_dir` config at startup, with no downloads and no database registration — integrity comes from the image digests, and the sha256 computed at discovery is verified on every provider launch. The new `bindings.disable_install` config (chart value `bindings.disableInstall`) rejects the imperative `openrun provider install/uninstall` API/CLI, for deployments where providers are managed only declaratively.
 - Add agent builder support using ACP integration
 - Added the `builtin` app auth type: username/password authentication (HTTP Basic) against `[builtin_auth.<username>]` config entries, each with a bcrypt `password` hash and a `groups` list used for RBAC `group:` matching (user id is `builtin:<username>` in grants). Users can be defined statically in `openrun.toml` or managed dynamically with the new `openrun user add/update/delete/list` commands (`/_openrun/user` APIs), which take effect immediately without a server restart and shadow static entries of the same name. Useful for small deployments and for testing RBAC policies with multiple users and groups without setting up OAuth/SAML.
 - Added the global CLI flag `--as <provider>:<username>` (e.g. `openrun --as builtin:user1 app list`): the management API call runs as the given user with RBAC enforcement (permission checks, list filtering, the owner rule, audit attribution) instead of as the trusted administrator. Supported over the unix domain socket only and requires RBAC to be enabled; for `builtin:` users the entry must exist and its groups feed `group:` grant matching, other provider ids (e.g. `github:user`) are taken literally with no groups so grants for SSO identities can be tested without creating them. Useful for testing RBAC policies from the CLI without going through an app.

Makefile

@@ -55,7 +55,7 @@ endif
 .RECIPEPREFIX = >
 TAG := 
 
-.PHONY: help test unit int testui covtest covunit covint release int_single lint verify build-linux image tags docs-screenshots
+.PHONY: help test unit int testui covtest covunit covint release fullrelease int_single lint verify build-linux image tags docs-screenshots
 
 help: ## Display this help section
 > @awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z0-9_-]+:.*?## / {printf "\033[36m%-38s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
@@ -151,6 +151,62 @@ release: ## Tag and push a release; args: <app_version> <helm_version>
 > echo "Run above command to push the Helm chart after the OpenRun release job is done"
 > @cd - > /dev/null
 
+fullrelease: ## Tag+push openrun, pkg/binding and all bindings under one version; stage (not push) the Helm chart; args: <version>
+> @version="$(INPUT)"
+> version="$${version#v}"
+> if [[ -z "$$version" ]]; then
+>   echo "Usage: make fullrelease <version>, e.g. make fullrelease 0.19.0"
+>   exit 1
+> fi
+> if ! [[ "$$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$$ ]]; then
+>   echo "Error: version '$$version' does not look like a semver version"
+>   exit 1
+> fi
+> # Everything is tagged from the current checkouts: all three repos must be
+> # clean, and nothing may be tagged/pushed if any tag already exists
+> for repo in . ../bindings ../openrun-helm-charts; do
+>   if [[ -n "$$(git -C $$repo status --porcelain)" ]]; then
+>     echo "Error: working tree $$repo is not clean, commit or stash changes first"
+>     exit 1
+>   fi
+> done
+> for tag in "v$$version" "pkg/binding/v$$version"; do
+>   if git rev-parse -q --verify "refs/tags/$$tag" > /dev/null; then
+>     echo "Error: tag $$tag already exists"
+>     exit 1
+>   fi
+> done
+> if [[ -n "$$(git -C ../bindings tag -l "*/v$$version")" ]]; then
+>   echo "Error: bindings tags for v$$version already exist:" $$(git -C ../bindings tag -l "*/v$$version")
+>   exit 1
+> fi
+> # openrun server + pkg/binding SDK: tag and push. The SDK tag must be on the
+> # remote before the bindings release, whose go mod tidy resolves it.
+> git tag -a "v$$version" -m "Release v$$version"
+> git tag -a "pkg/binding/v$$version" -m "Release pkg/binding/v$$version"
+> git push origin "v$$version" "pkg/binding/v$$version"
+> # Bindings: update every provider module to the new SDK version, tag each
+> # module and push; the bindings release workflow builds and publishes each
+> # provider (binaries + OCI image) from its pushed tag
+> $(MAKE) -C ../bindings release INPUT="v$$version" INPUT2="v$$version" PUSH=1
+> # Helm chart: stage the release commit only. It is pushed manually after the
+> # OpenRun release job has published the v$$version images, since the chart's
+> # appVersion is the server image tag.
+> cd ../openrun-helm-charts/
+> sed -i.bak -E "s/^([[:space:]]*version:[[:space:]]*)[^#[:space:]]+/\1$$version/" charts/openrun/Chart.yaml
+> rm -f charts/openrun/Chart.yaml.bak
+> sed -i.bak -E "s/^([[:space:]]*appVersion:[[:space:]]*)[^#[:space:]]+/\1$$version/" charts/openrun/Chart.yaml
+> rm -f charts/openrun/Chart.yaml.bak
+> git add charts/openrun/Chart.yaml
+> git commit -m "Updated Helm chart to $$version, app version to $$version"
+> cd - > /dev/null
+> echo "**************************************************"
+> echo " Tagged and pushed: v$$version, pkg/binding/v$$version, bindings */v$$version"
+> echo " Helm chart commit staged in ../openrun-helm-charts (not pushed)"
+> echo " After the OpenRun release job for v$$version is done, run:"
+> echo "   cd ../openrun-helm-charts/ && git push"
+> echo "**************************************************"
+
 # Swallow extra command-line words (e.g. `make int_single test_reload.yaml`)
 # so make doesn't also try to build them as targets; $(INPUT)/$(INPUT2) above
 # already pick them up positionally.

deploy/terraform/README.md

@@ -105,6 +105,19 @@ Wait for DNS to propagate before completing TLS issuance.
 
 Set `openrun_auth_mode` to `oidc` or `saml` and provide the matching variables. Outputs include the callback/ACS URLs.
 
+## Binding providers (optional)
+
+Out-of-process [binding providers](https://github.com/openrundev/bindings) (mongodb, redis, sqlserver, oracle) can be installed declaratively:
+
+```hcl
+openrun_binding_providers = {
+  redis   = "v0.1.0"
+  mongodb = "v0.1.0"
+}
+```
+
+Every OpenRun replica downloads, verifies and registers the declared providers at startup; their service types become available for `openrun service create`. Upgrading a provider is a version change followed by `terraform apply` (which rolls out the deployment). Append `@sha256:<hex>` to a version to pin the binary digest. Set `openrun_bindings_release_url_template` to download from an internal mirror when the cluster restricts egress.
+
 ## Security summary
 
 - EKS worker nodes are private and egress via NAT.

deploy/terraform/openrun.tf

@@ -107,6 +107,10 @@ locals {
     }
     auth = local.openrun_oidc_values
     saml = local.openrun_saml_values
+    bindings = {
+      install            = var.openrun_binding_providers
+      releaseUrlTemplate = var.openrun_bindings_release_url_template
+    }
   }
 }
 

deploy/terraform/tfvars.sample

@@ -32,11 +32,24 @@ openrun_chart_version = ""
 openrun_default_domain = ""
 
 # Email for Let's Encrypt certificate registration. Required for Let's Encrypt certificate issuance.
-openrun_lets_encrypt_email = "
+openrun_lets_encrypt_email = ""
 
 # Use Let's Encrypt staging environment (set to true for testing to avoid rate limits)
 openrun_lets_encrypt_use_staging = false
 
+# Out-of-process binding providers (https://github.com/openrundev/bindings) installed
+# at server startup, provider name to version. Append @sha256:<hex> to a version to
+# pin the binary digest (comma-separated digests for multi-arch node groups).
+# openrun_binding_providers = {
+#   redis   = "v0.1.0"
+#   mongodb = "v0.1.0"
+# }
+
+# Mirror url template for provider downloads when the cluster restricts egress.
+# {provider}, {version}, {os} and {arch} are replaced. Leave empty to download
+# from the openrundev/bindings GitHub releases.
+# openrun_bindings_release_url_template = ""
+
 # -----------------------------------------------------------------------------
 # EKS Cluster Configuration
 # -----------------------------------------------------------------------------

deploy/terraform/variables.tf

@@ -249,6 +249,18 @@ variable "openrun_enable_nlb_eips" {
   default     = true
 }
 
+variable "openrun_binding_providers" {
+  description = "Out-of-process binding providers installed at server startup, provider name to version (e.g. { redis = \"v0.1.0\" }). Append @sha256:<hex> to a version to pin the binary digest (comma-separated digests for multi-arch). Providers declared here cannot be modified with the openrun provider CLI."
+  type        = map(string)
+  default     = {}
+}
+
+variable "openrun_bindings_release_url_template" {
+  description = "Optional mirror url template for downloading binding provider binaries ({provider}, {version}, {os}, {arch} are replaced). Leave empty to download from the openrundev/bindings GitHub releases."
+  type        = string
+  default     = ""
+}
+
 variable "openrun_auth_mode" {
   description = "Authentication mode for OpenRun: none, oidc, or saml."
   type        = string

docs/content/docs/Container/Kubernetes.md

@@ -103,7 +103,28 @@ OpenRun service and Kaniko jobs run in the main namespace (default `openrun`). A
 
 Out-of-process [binding providers](https://github.com/openrundev/bindings) (mongodb, redis, sqlserver, oracle) work on Kubernetes without any special setup: installed providers are registered in the metadata database (Postgres, required for Kubernetes installs), which is the source of truth. Each server replica materializes the provider executables into a node-local cache directory at startup, before serving traffic, and re-downloads them (with checksum verification) whenever a pod starts on a fresh node. Installs and uninstalls propagate to all replicas through Postgres notifications, so `openrun provider install` works on multi-replica deployments exactly as on a single server.
 
-For declarative, config-managed deployments, declare the providers in the server config instead of using the CLI:
+For declarative, config-managed deployments, declare the providers in the Helm values instead of using the CLI:
+
+```yaml {filename="values.yaml"}
+bindings:
+  install:
+    redis: v0.1.0
+    mongodb: v0.1.0
+  # Optional mirror for clusters with restricted egress; {provider}, {version},
+  # {os} and {arch} are replaced.
+  # releaseUrlTemplate: "https://mirror.internal/{provider}/{version}/openrun-binding-{provider}-{os}-{arch}"
+```
+
+or with `--set bindings.install.redis=v0.1.0` on the Helm command line. For Terraform-managed EKS installs, set the `openrun_binding_providers` variable in `terraform.tfvars`:
+
+```hcl {filename="terraform.tfvars"}
+openrun_binding_providers = {
+  redis   = "v0.1.0"
+  mongodb = "v0.1.0"
+}
+```
+
+The chart renders these into the `[bindings.install]` section of the generated server config:
 
 ```toml {filename="openrun.toml"}
 [bindings.install]
@@ -117,6 +138,21 @@ A replica that misses an install notification (for example after a transient dat
 
 The provider processes run inside the OpenRun server pod, so a provider binary must run in the server container image; the published providers are static pure-Go binaries and need nothing beyond the stock image. Provider startup materialization completes before the server starts serving, so binding operations never race provider registration during a rollout.
 
+### OCI image install
+
+Providers are also published as minimal OCI images (`ghcr.io/openrundev/openrun-binding-<provider>`, a `FROM scratch` image holding the provider binary). For clusters where binaries must come through image provenance policies, or where the server pods have no egress at all, declare the providers as images instead of versions:
+
+```yaml {filename="values.yaml"}
+bindings:
+  images:
+    redis: ghcr.io/openrundev/openrun-binding-redis:v0.1.0
+    mongodb: ghcr.io/openrundev/openrun-binding-mongodb@sha256:8f4e...
+```
+
+The Helm chart renders one init container per provider, which copies the binary from its image into a shared volume (`export` subcommand of the provider binary); the server registers the pre-placed providers at startup, with no downloads and no database registration. Integrity comes from the image digests that placed the binaries — reference images by digest where policy requires it — and the server pins the discovered binary's checksum so every provider launch verifies the file has not changed. Images are pulled by the container runtime, so `imagePullSecrets` and registry mirrors apply as for any other image.
+
+With either declarative path, `bindings.disableInstall: true` additionally rejects the imperative `openrun provider install`/`uninstall` CLI on the deployment, making the chart values the only way providers are added.
+
 ## Architecture
 
 OpenRun is installed as a Kubernetes Deployment, with a Service for routing API calls. For each containerized app installed on OpenRun, a ClusterIP Service is created for app traffic. API calls to the OpenRun API Server are routed to the app-specific Service using its cluster IP.

internal/server/provider.go

@@ -244,6 +244,20 @@ func (s *Server) isConfigManagedProvider(name string) bool {
 	return ok
 }
 
+// providerModifyError returns the error rejecting an imperative provider
+// install/uninstall when the deployment manages providers declaratively:
+// either globally (bindings.disable_install) or for one config-declared
+// provider. operation is "install" or "uninstall", for the error text.
+func (s *Server) providerModifyError(name, operation string) error {
+	if s.staticConfig.Bindings.DisableInstall {
+		return fmt.Errorf("provider %s is disabled on this server (bindings.disable_install), providers are managed through the server config", operation)
+	}
+	if s.isConfigManagedProvider(name) {
+		return fmt.Errorf("provider %s is managed through the [bindings.install] server config, update the config instead", name)
+	}
+	return nil
+}
+
 // InstallProvider installs or updates an out-of-process binding provider: the
 // binary is fetched, verified, registered in the metadata database (the source
 // of truth) and materialized into the local cache dir. Other replicas
@@ -252,8 +266,8 @@ func (s *Server) InstallProvider(ctx context.Context, request *types.ProviderIns
 	if err := s.enforceGlobalPerm(ctx, types.PermissionProviderManage, ""); err != nil {
 		return nil, err
 	}
-	if s.isConfigManagedProvider(request.Name) {
-		return nil, fmt.Errorf("provider %s is managed through the [bindings.install] server config, update the config instead", request.Name)
+	if err := s.providerModifyError(request.Name, "install"); err != nil {
+		return nil, err
 	}
 	return s.installProvider(ctx, request, system.GetContextUserId(ctx))
 }
@@ -401,8 +415,8 @@ func (s *Server) UninstallProvider(ctx context.Context, name string, force bool)
 	if err := s.enforceGlobalPerm(ctx, types.PermissionProviderManage, ""); err != nil {
 		return err
 	}
-	if s.isConfigManagedProvider(name) {
-		return fmt.Errorf("provider %s is managed through the [bindings.install] server config, remove it from the config instead", name)
+	if err := s.providerModifyError(name, "uninstall"); err != nil {
+		return err
 	}
 	s.providerMutex.Lock()
 	defer s.providerMutex.Unlock()
@@ -504,6 +518,8 @@ func (s *Server) setupBindingProviders(ctx context.Context) {
 			Msg("Registered DEV binding provider from local path, checksum verification is disabled")
 	}
 
+	s.registerPreinstalledProviders(ctx)
+
 	// Install providers declared in the config: the declarative path for
 	// config-managed (Kubernetes/Helm) deployments, where every replica runs
 	// this on startup. The install is skipped when the database row already
@@ -534,6 +550,59 @@ func (s *Server) setupBindingProviders(ctx context.Context) {
 	}
 }
 
+// registerPreinstalledProviders discovers provider executables pre-placed in
+// bindings.preinstalled_dir and registers their service types, without
+// database registration or downloads. This is the Kubernetes OCI image
+// distribution path: init containers copy each provider binary from its
+// per-provider image into a shared volume before the server starts, so
+// integrity comes from the image digests that placed the files. The sha256
+// computed here is still pinned in the registration, so every launch verifies
+// the file has not changed since discovery. Preinstalled providers register
+// before database reconcile: a database-installed provider claiming the same
+// service types fails reconcile with a logged conflict.
+func (s *Server) registerPreinstalledProviders(ctx context.Context) {
+	dir := os.ExpandEnv(s.staticConfig.Bindings.PreinstalledDir)
+	if dir == "" {
+		return
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		s.Error().Err(err).Str("dir", dir).Msg("error reading preinstalled bindings dir")
+		return
+	}
+	for _, entry := range entries {
+		name, found := strings.CutPrefix(entry.Name(), "openrun-binding-")
+		name = strings.TrimSuffix(name, ".exe")
+		if !found || name == "" || entry.IsDir() {
+			continue
+		}
+		execPath := filepath.Join(dir, entry.Name())
+		data, err := os.ReadFile(execPath)
+		if err != nil {
+			s.Error().Err(err).Str("path", execPath).Msg("error reading preinstalled binding provider")
+			continue
+		}
+		sum := sha256.Sum256(data)
+		checksum := hex.EncodeToString(sum[:])
+
+		version, serviceTypes, err := s.describeProvider(ctx, execPath, checksum)
+		if err != nil {
+			s.Error().Err(err).Str("provider", name).Str("path", execPath).Msg("error describing preinstalled binding provider")
+			continue
+		}
+		typeNames := make([]string, 0, len(serviceTypes))
+		for _, t := range serviceTypes {
+			typeNames = append(typeNames, t.ServiceType)
+		}
+		if err := bindings.ReplaceProviderBindings("preinstalled:"+name, typeNames, execPath, checksum); err != nil {
+			s.Error().Err(err).Str("provider", name).Msg("error registering preinstalled binding provider")
+			continue
+		}
+		s.Info().Str("provider", name).Str("path", execPath).Str("version", version).Strs("service_types", typeNames).
+			Msg("Registered preinstalled binding provider")
+	}
+}
+
 // ensureConfigProvider installs one [bindings.install] entry if the database
 // does not already have it at the declared version. The following reconcile
 // pass materializes the binary into the local cache when needed.