Orca - ORigin CAche

.github/workflows/ci.yaml

@@ -128,6 +128,34 @@ jobs:
           retention-days: 7
           if-no-files-found: ignore
 
+  # ---------- Orca Integration Tests ----------
+  # Spins up LocalStack and Azurite via testcontainers-go and runs the
+  # orca in-process integration suite (internal/orca/inttest). Docker
+  # is preinstalled on GitHub-hosted Ubuntu runners; no extra services:
+  # block is required.
+  orca-inttest:
+    name: Orca Integration Tests
+    needs: [frontend]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Download frontend dist
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: frontend-dist
+          path: internal/net/html/dist
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: go.mod
+          cache-dependency-path: go.sum
+
+      - name: Run orca-inttest
+        run: make orca-inttest
+
   # ---------- Build ----------
   build:
     name: Build

Makefile

@@ -74,6 +74,14 @@ STAMP_LDFLAGS=-X github.com/Azure/unbounded/internal/version.Version=$(VERSION)
 
 METALMAN_IMAGE=$(CONTAINER_REGISTRY)/metalman:$(VERSION)
 
+# Orca configuration
+ORCA_BIN=bin/orca
+ORCA_CMD=./cmd/orca
+ORCA_IMAGE ?= $(CONTAINER_REGISTRY)/orca:$(VERSION)
+ORCA_NAMESPACE ?= unbounded-kube
+ORCA_MANIFEST_TEMPLATES_DIR := deploy/orca
+ORCA_MANIFEST_RENDERED_DIR  := deploy/orca/rendered
+
 # kubectl-unbounded also stamps the metalman image reference.
 KUBECTL_UNBOUNDED_LDFLAGS=$(STAMP_LDFLAGS) -X github.com/Azure/unbounded/cmd/kubectl-unbounded/app.MetalmanImage=$(METALMAN_IMAGE)
 
@@ -112,6 +120,7 @@ REACT_DEV ?= false
 .PHONY: all help fmt lint test build vulncheck check-deps kubectl-unbounded kubectl-unbounded-build install-tools install-protoc generate kubectl-unbounded forge unbounded-agent machina machina-build machina-oci machina-oci-push machina-manifests machine-ops-controller machine-ops-controller-build machine-ops-controller-oci machine-ops-controller-oci-push machine-ops-manifests metalman metalman-build metalman-oci metalman-oci-push gomod docs-serve unbounded-net-controller unbounded-net-node unbounded-net-routeplan-debug unping unroute notice notice-check
 .PHONY: net-frontend net-frontend-clean net-build-ebpf net-manifests release-manifests
 .PHONY: image-machina-local image-machine-ops-controller-local image-metalman-local image-net-controller-local image-net-node-local images-local
+.PHONY: orca orca-build orca-manifests orca-oci orca-oci-push orca-up orca-down orca-reset orca-inttest image-orca-local
 
 ##@ General
 
@@ -176,6 +185,8 @@ help: ## Show this help
 	@echo "  machina-oci-push                 Build machina image and push"
 	@echo "  machine-ops-controller-oci-push  Build machine-ops-controller image and push"
 	@echo "  metalman-oci-push                Build metalman image and push"
+	@echo "  image-orca-local                 Build orca image"
+	@echo "  orca-oci-push                    Build orca image and push"
 	@echo ""
 	@echo "Net Frontend:"
 	@echo "  net-frontend                     Build frontend into \$$(NET_FRONTEND_DIST_DIR) (cached)"
@@ -188,10 +199,19 @@ help: ## Show this help
 	@echo "  machina-manifests                Render machina manifests into deploy/machina/rendered"
 	@echo "  machine-ops-manifests            Render machine-ops manifests into deploy/machine-ops/rendered"
 	@echo "  net-manifests                    Render net manifests into \$$(NET_MANIFEST_RENDERED_DIR)"
+	@echo "  orca-manifests                   Render orca manifests into deploy/orca/rendered"
 	@echo ""
 	@echo "Net Kubernetes (apply to current kubectl context):"
 	@echo "  See \`make -C hack/net help\` for cluster deploy/undeploy targets."
 	@echo ""
+	@echo "Orca Dev Harness (Kind cluster):"
+	@echo "  orca | orca-build                Build orca binary (with/without lint/test)"
+	@echo "  orca-up                          Bring up Orca dev harness in Kind"
+	@echo "  orca-down                        Tear down Orca dev harness Kind cluster"
+	@echo "  orca-reset                       Rebuild image and rollout-restart deployment"
+	@echo "  orca-inttest                     Run orca integration tests (Docker required)"
+	@echo "  See \`make -C hack/orca help\` for full list."
+	@echo ""
 	@echo "Documentation:"
 	@echo "  docs-serve                       Start local Hugo dev server"
 	@echo ""
@@ -570,6 +590,58 @@ metalman-oci: image-metalman-local ## Alias for image-metalman-local
 metalman-oci-push: metalman-oci ## Build and push the metalman container image
 	$(CONTAINER_ENGINE) push $(METALMAN_IMAGE)
 
+##@ Orca
+
+orca-build: ## Build the orca binary (no lint/test)
+	$(GOBUILD) -ldflags '$(STAMP_LDFLAGS)' -o $(ORCA_BIN) $(ORCA_CMD)/main.go
+
+orca: test orca-build ## Build the orca binary (implies test)
+
+orca-manifests: ## Render orca deployment manifests into deploy/orca/rendered
+	@mkdir -p $(ORCA_MANIFEST_RENDERED_DIR)
+	@find $(ORCA_MANIFEST_RENDERED_DIR) -mindepth 1 -not -name .gitignore -delete 2>/dev/null || true
+	$(GOCMD) run ./hack/cmd/render-manifests \
+		--templates-dir $(ORCA_MANIFEST_TEMPLATES_DIR) \
+		--output-dir $(ORCA_MANIFEST_RENDERED_DIR) \
+		--set Namespace=$(ORCA_NAMESPACE) \
+		--set Image=$(ORCA_IMAGE)
+	@echo "Rendered orca manifests into $(ORCA_MANIFEST_RENDERED_DIR) (image: $(ORCA_IMAGE))"
+
+image-orca-local: ## Build the orca container image locally (single-arch)
+	$(CONTAINER_ENGINE) build \
+		--build-arg VERSION=$(VERSION) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg BUILD_TIME=$(BUILD_TIME) \
+		-t orca:$(VERSION) -t $(ORCA_IMAGE) \
+		-f ./images/orca/Containerfile .
+
+orca-oci: image-orca-local ## Alias for image-orca-local
+
+orca-oci-push: orca-oci ## Build and push the orca container image
+	$(CONTAINER_ENGINE) push $(ORCA_IMAGE)
+
+# Dev-cluster proxy targets. The actual implementations live in
+# hack/orca/Makefile (see AGENTS.md convention; mirrors hack/net/).
+orca-up: ## Bring up the Orca dev harness in a Kind cluster
+	$(MAKE) -C hack/orca up
+
+orca-down: ## Tear down the Orca dev harness Kind cluster
+	$(MAKE) -C hack/orca down
+
+orca-reset: ## Rebuild orca image and rolling-restart the dev deployment
+	$(MAKE) -C hack/orca reset
+
+# orca-inttest mirrors the test/test-race pattern: race detector in CI
+# (ubuntu-latest has gcc), no -race locally so developers without a C
+# toolchain can still run integration tests.
+ifdef CI
+orca-inttest: ## Run orca integration tests (LocalStack + Azurite via testcontainers; requires Docker)
+	$(GOTEST) -tags=integrationtest -race -timeout 15m ./internal/orca/inttest/...
+else
+orca-inttest: ## Run orca integration tests (LocalStack + Azurite via testcontainers; requires Docker)
+	$(GOTEST) -tags=integrationtest -timeout 15m ./internal/orca/inttest/...
+endif
+
 image-net-controller-local: net-frontend resources/cni-plugins-linux-$(HOST_GOARCH)-$(CNI_PLUGINS_VERSION).tgz ## Build the unbounded-net-controller image locally (single-arch)
 	$(CONTAINER_ENGINE) build \
 		--target controller \

cmd/orca/main.go

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package main
+
+import "github.com/Azure/unbounded/cmd/orca/orca"
+
+func main() {
+	orca.Run()
+}

cmd/orca/orca/orca.go

@@ -0,0 +1,134 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+// Package orca wires the Orca cache binary together. It is invoked by
+// cmd/orca/main.go and is responsible for parsing flags, loading the
+// YAML config, and delegating to internal/orca/app for actual runtime
+// wiring.
+package orca
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/Azure/unbounded/internal/orca/app"
+	"github.com/Azure/unbounded/internal/orca/config"
+)
+
+// Run is the entrypoint invoked by cmd/orca/main.go.
+func Run() {
+	root := &cobra.Command{
+		Use:   "orca",
+		Short: "Orca origin cache - S3-compatible read-only cache fronting Azure / S3 origins",
+	}
+	root.AddCommand(newServeCmd())
+
+	if err := root.Execute(); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func newServeCmd() *cobra.Command {
+	var configPath string
+
+	cmd := &cobra.Command{
+		Use:   "serve",
+		Short: "Run the Orca cache server",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return serve(cmd.Context(), configPath)
+		},
+	}
+	cmd.Flags().StringVarP(&configPath, "config", "c", "/etc/orca/config.yaml",
+		"path to YAML config file")
+
+	return cmd
+}
+
+func serve(parent context.Context, configPath string) error {
+	cfg, err := config.Load(configPath)
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+
+	level, err := resolveLogLevel(cfg.Logging.Level)
+	if err != nil {
+		return err
+	}
+
+	levelVar := new(slog.LevelVar)
+	levelVar.Set(level)
+
+	log := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+		Level:     levelVar,
+		AddSource: true,
+	}))
+	slog.SetDefault(log)
+
+	log.Info("orca starting",
+		"config_path", configPath,
+		"log_level", level.String(),
+	)
+
+	log.Info("config loaded",
+		"origin_id", cfg.Origin.ID,
+		"replicas_target", cfg.Cluster.TargetReplicas,
+		"target_global", cfg.Origin.TargetGlobal,
+		"internal_tls", cfg.Cluster.InternalTLS.Enabled,
+		"client_auth", cfg.Server.Auth.Enabled,
+	)
+
+	ctx, cancel := signal.NotifyContext(parent, os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+
+	a, err := app.Start(ctx, cfg, app.WithLogger(log))
+	if err != nil {
+		return err
+	}
+
+	if waitErr := a.Wait(ctx); waitErr != nil {
+		log.Error("listener exited with error", "err", waitErr)
+		cancel()
+	} else {
+		log.Info("shutdown signal received")
+	}
+
+	shutdownCtx, shCancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer shCancel()
+
+	// Propagate Shutdown errors to the process exit code so that
+	// failed-shutdown signals (kubelet probes, init systems) match
+	// reality. App.Shutdown also logs each individual error
+	// internally, so this only governs the exit-code semantics.
+	shutdownErr := a.Shutdown(shutdownCtx)
+
+	log.Info("orca stopped")
+
+	return shutdownErr
+}
+
+// resolveLogLevel determines the effective slog.Level by consulting
+// the ORCA_LOG_LEVEL environment variable first; if unset or empty,
+// falls back to the YAML-configured value. An unrecognised value
+// (from either source) returns a parse error so misconfiguration is
+// surfaced at startup rather than silently degrading to info.
+func resolveLogLevel(yamlLevel string) (slog.Level, error) {
+	if env := strings.TrimSpace(os.Getenv("ORCA_LOG_LEVEL")); env != "" {
+		level, err := config.ParseLogLevel(env)
+		if err != nil {
+			return 0, fmt.Errorf("ORCA_LOG_LEVEL: %w", err)
+		}
+
+		return level, nil
+	}
+
+	return config.ParseLogLevel(yamlLevel)
+}

cmd/orca/orca/orca_test.go

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package orca
+
+import (
+	"log/slog"
+	"testing"
+)
+
+// TestResolveLogLevel_PrecedenceAndDefault covers the resolution
+// order documented on resolveLogLevel: ORCA_LOG_LEVEL wins when
+// set and non-empty (after trim), otherwise the YAML-configured
+// value is used, otherwise the empty string defaults through
+// config.ParseLogLevel to info.
+func TestResolveLogLevel_PrecedenceAndDefault(t *testing.T) {
+	tests := []struct {
+		name      string
+		yamlLevel string
+		envLevel  string // "" -> simulate unset via Setenv with ""
+		want      slog.Level
+		wantErr   bool
+	}{
+		{"empty yaml, no env -> info", "", "", slog.LevelInfo, false},
+		{"yaml info, no env", "info", "", slog.LevelInfo, false},
+		{"yaml debug, no env", "debug", "", slog.LevelDebug, false},
+		{"yaml info overridden by env debug", "info", "debug", slog.LevelDebug, false},
+		{"yaml debug overridden by env warn", "debug", "warn", slog.LevelWarn, false},
+		{"whitespace env falls back to yaml", "warn", "   ", slog.LevelWarn, false},
+		{"invalid yaml fails", "trace", "", 0, true},
+		{"invalid env fails even when yaml valid", "info", "trace", 0, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv("ORCA_LOG_LEVEL", tt.envLevel)
+
+			got, err := resolveLogLevel(tt.yamlLevel)
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("resolveLogLevel(%q) = %v, want error", tt.yamlLevel, got)
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Errorf("resolveLogLevel(%q) unexpected err: %v", tt.yamlLevel, err)
+				return
+			}
+
+			if got != tt.want {
+				t.Errorf("resolveLogLevel(yaml=%q, env=%q) = %v, want %v",
+					tt.yamlLevel, tt.envLevel, got, tt.want)
+			}
+		})
+	}
+}

deploy/orca/01-namespace.yaml.tmpl

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {{ default "unbounded-kube" .Namespace }}
+  labels:
+    app.kubernetes.io/name: orca

deploy/orca/02-rbac.yaml.tmpl

@@ -0,0 +1,8 @@
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: orca
+  namespace: {{ default "unbounded-kube" .Namespace }}
+  labels:
+    app.kubernetes.io/name: orca