diff --git a/.gitignore b/.gitignore index 0948f0f5..4125a29e 100644 --- a/.gitignore +++ b/.gitignore @@ -32,4 +32,7 @@ DEPLOY.md node_modules/ # Added by ork doctor init .orkestra/bundle/ -.orkestra/ \ No newline at end of file +.orkestra/ + +# Local ork-registry (published as OCI artifacts) +ork-registry/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 233983be..2e31e81c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ ## Changelog – Orkestra v0.3.8 -### ork doctor + ork deploy — Local to production in minutes +### ork doctor + ork doctor deploy — Local to production in minutes Developers can now deploy any project to Kubernetes with three commands, no operator knowledge required. @@ -19,14 +19,14 @@ ork doctor init --name my-api --notify-me --add-ingress - `.orkestra/app.yaml` — the ConfigMap CR the developer owns - `.orkestra/values.yaml` — Helm values for the Orkestra operator -#### ork deploy +#### ork doctor deploy Builds the Docker image, pushes it, runs `ork kompose` to merge all registered katalogs, generates the cluster bundle, installs or verifies the Orkestra operator via Helm, patches the image in the CR, and watches the rollout. ```bash -ork deploy --registry ghcr.io/myorg -ork deploy --registry ghcr.io/myorg --dev # spins up a local kind cluster -ork deploy --registry ghcr.io/myorg --dry-run +ork doctor deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg --dev # spins up a local kind cluster +ork doctor deploy --registry ghcr.io/myorg --dry-run ``` Key behaviours: @@ -38,18 +38,18 @@ Key behaviours: - **Internal service URL checklist** printed after every deploy so developers can wire projects together (`export MY_API_URL=...`) - **Control Center fallback**: when `controlCenterHost` is empty, prints the `kubectl port-forward` command for local access -#### ork deploy rollback +#### ork doctor deploy rollback Restores the previous image by reading `~/.orkestra/deploy/state.json` (annotation fallback for backward compatibility). Swaps current and previous before patching so every rollback is reversible. ```bash -ork deploy rollback -ork deploy rollback --image ghcr.io/myorg/my-api:v1.2.0 +ork doctor deploy rollback +ork doctor deploy rollback --image ghcr.io/myorg/my-api:v1.2.0 ``` #### Out-of-the-box developer notifications -Every katalog generated by `ork doctor init` ships with a `notify:` block on the deployment readiness condition. When replicas are not ready within the notification interval (default 15 minutes), Orkestra sends the `developer` team the exact `kubectl logs` command and a `ork deploy rollback` hint. +Every katalog generated by `ork doctor init` ships with a `notify:` block on the deployment readiness condition. When replicas are not ready within the notification interval (default 15 minutes), Orkestra sends the `developer` team the exact `kubectl logs` command and a `ork doctor deploy rollback` hint. Wire the `developer` team with `ork doctor init --notify-me`: - Reads the developer's Git author email from `git log -1` diff --git a/Makefile b/Makefile index 15465d4d..93203498 100644 --- a/Makefile +++ b/Makefile @@ -164,6 +164,31 @@ runtime-reload: docker @echo "✔ Runtime updated to image: $(ORK_IMAGE)-$(RUNTIME_TAG)" +CONTROL_CENTER_DEPLOYMENT ?= orkestra-cc +CONTROL_CENTER_CONTAINER_NAME ?= controlcenter +CONTROL_CENTER_NAMESPACE ?= orkestra-system + +controlcenter-reload: docker-cc + @echo "Generating unique tag..." + $(eval CC_TAG := $(shell date +%s)) + @echo "Tag: $(CC_TAG)" + + @echo "Retagging image..." + docker tag $(ORK_CC_IMAGE) $(ORK_CC_IMAGE)-$(CC_TAG) + + @echo "Loading image into kind cluster: $(KIND_CLUSTER)" + kind load docker-image $(ORK_CC_IMAGE)-$(CC_TAG) --name $(KIND_CLUSTER) + @echo "✔ Image loaded" + + @echo "Updating deployment $(CONTROL_CENTER_DEPLOYMENT) in namespace $(CONTROL_CENTER_NAMESPACE)..." + kubectl -n $(CONTROL_CENTER_NAMESPACE) set image deploy/$(CONTROL_CENTER_DEPLOYMENT) \ + $(CONTROL_CENTER_CONTAINER_NAME)=$(ORK_CC_IMAGE)-$(CC_TAG) + + @echo "✔ Control Center updated to image: $(ORK_CC_IMAGE)-$(CC_TAG)" + +orkestra-reload: runtime-reload controlcenter-reload + @echo "✔ Orkestra runtime and Control Center reloaded successfully" + # ── Primary targets ─────────────────────────────────────────────────────────── # Default: vet + unit tests. Fast, no external dependencies. diff --git a/README.md b/README.md index a5386f1b..d7343045 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ Every CRD declared in a Katalog becomes a complete, isolated operator: | **Workqueue** | Per-CRD. Rate-limited. Deduplicated. Isolated from every other CRD. | | **Worker pool** | Configurable. A panic in one CRD does not affect any other. | | **Drift correction** | `reconcile: true` — desired state is enforced on every cycle. | +| **Safe reconcile** | Failures in one operatroBox is contained, logged and does not affect the runtime or other CRDs. | | **Owner references** | Child resources deleted when the CR is deleted. | | **Finalizers** | CRs protected from dirty deletion automatically. | | **Events** | Every reconcile is a traceable Kubernetes event. | diff --git a/cmd/cli/deploy.go b/cmd/cli/deploy.go index 952616cf..8f4ca92e 100644 --- a/cmd/cli/deploy.go +++ b/cmd/cli/deploy.go @@ -34,9 +34,9 @@ var deployCmd = &cobra.Command{ Long: `Build the Docker image, push it, generate the Orkestra bundle, apply it to the cluster, and patch the CR to trigger a rolling deploy. - ork deploy --registry ghcr.io/myorg - ork deploy --registry ghcr.io/myorg --tag v1.2.0 - ork deploy --registry ghcr.io/myorg --dry-run`, + ork doctor deploy --registry ghcr.io/myorg + ork doctor deploy --registry ghcr.io/myorg --tag v1.2.0 + ork doctor deploy --registry ghcr.io/myorg --dry-run`, RunE: func(cmd *cobra.Command, args []string) error { registry, _ := cmd.Flags().GetString("registry") tag, _ := cmd.Flags().GetString("tag") @@ -68,17 +68,11 @@ to the cluster, and patch the CR to trigger a rolling deploy. return fmt.Errorf("--registry is required (e.g. --registry ghcr.io/myorg)") } - // Load persistent state and global Komposer (both non-fatal if missing). + // Load persistent state (non-fatal if missing). state, err := doctor.LoadState() if err != nil { state = &doctor.DeployState{Projects: make(map[string]*doctor.ProjectState)} } - komposer, _ := doctor.LoadGlobalKomposer() - if state.ClusterContext == "" { - komposer.Metadata.Description = "Orkestra Managed Deployment in " + state.ClusterContext - } else { - komposer.Metadata.Description = "Orkestra Managed Deployment" - } if !dryRun { // Step 0 — Cluster connectivity. @@ -95,13 +89,14 @@ to the cluster, and patch the CR to trigger a rolling deploy. } } - // Load init config (bridges doctor init → deploy). - initCfg, _ := buildx.LoadInitConfig(dir) + // Load init config from state. + initCfg := loadInitCfgFromState(state, dir) // ── Multi-app path ──────────────────────────────────────────────────────── // --use-compose init writes Apps entries but never writes app.yaml, so the // crName resolution below is skipped entirely for multi-app projects. if len(initCfg.Apps) > 0 { + komposer, _ := doctor.LoadGlobalKomposer() err := deployMultiApp(deployContext{ dir: dir, registry: registry, @@ -122,7 +117,6 @@ to the cluster, and patch the CR to trigger a rolling deploy. clusterCtx: doctor.CurrentContext(), initCfg: initCfg, }) - _ = buildx.CleanupInitConfig(dir) return err } @@ -152,9 +146,8 @@ to the cluster, and patch the CR to trigger a rolling deploy. // Show cluster context and currently deployed projects. clusterCtx := doctor.CurrentContext() - deployed := komposer.DeployedProjects() fmt.Printf("\nCluster: %s\n", clusterCtx) - if len(deployed) > 0 { + if deployed := state.DeployedAppNames(); len(deployed) > 0 { fmt.Printf("Deployed: %s\n", strings.Join(deployed, ", ")) } @@ -186,24 +179,10 @@ to the cluster, and patch the CR to trigger a rolling deploy. fmt.Println(" ~ dry-run: skipping docker build and push") } - // Step 3 — Generate bundle + // Step 3 — Resolve motif + generate bundle from central Katalog fmt.Println("\nGenerating bundle...") - initOpts := doctor.GenerateOptions{ - NoHA: noHA, - NoSecure: noSecure, - Clean: clean, - } - bundleDir := filepath.Join(dir, orkDir, "bundle") - katalogPath := filepath.Join(dir, orkDir, "katalog.yaml") - absKatalogPath, _ := filepath.Abs(katalogPath) - - if !dryRun { - if err := doctor.GenerateBundle(appName, ns, info.Secrets, info.Config, bundleDir); err != nil { - return err - } - } if len(info.Secrets) > 0 { fmt.Printf(" %s %s-secrets (%d variables from .env)\n", utils.SuccessMark(), appName, len(info.Secrets)) @@ -212,45 +191,24 @@ to the cluster, and patch the CR to trigger a rolling deploy. fmt.Printf(" %s %s-config (%d variables from .env)\n", utils.SuccessMark(), appName, len(info.Config)) } - // Auto-generate katalog if not present yet. - if !fileExistsAtPath(katalogPath) { - if !dryRun { - if err := doctor.Init(info, initOpts); err != nil { - return fmt.Errorf("generating katalog: %w", err) - } - } - fmt.Printf(" %s katalog.yaml generated", utils.SuccessMark()) - } - - if fileExistsAtPath(katalogPath) || dryRun { - if !dryRun { - komposer.RegisterKatalog(absKatalogPath) - state.ClusterContext = clusterCtx - komposer.Metadata.Name = clusterCtx - komposer.Metadata.License = info.License - if saveErr := komposer.Save(); saveErr != nil { - return fmt.Errorf("saving komposer: %w", saveErr) - } - - mergedPath, mergeErr := runKompose() - if mergeErr != nil { - return fmt.Errorf("merging katalogs: %w", mergeErr) - } - if err := doctor.DeduplicateKatalogGVKs(mergedPath); err != nil { - return fmt.Errorf("deduplicating katalog GVKs: %w", err) - } - effectiveKatalog := mergedPath - fmt.Printf(" %s Komposer merged (%d projects)\n", utils.SuccessMark(), len(komposer.DeployedProjects())) - - genArgs := []string{"generate", "bundle", "-f", effectiveKatalog, "-w", ns, "-o", bundleDir} - genCmd := exec.Command("ork", genArgs...) - genCmd.Stdout = os.Stdout - genCmd.Stderr = os.Stderr - if err := genCmd.Run(); err != nil { - return fmt.Errorf("generating bundle: %w", err) - } - } - fmt.Printf(" %s RBAC + Katalog ConfigMap + namespace", utils.SuccessMark()) + if err := deployDeveloperPath(devPathArgs{ + dir: dir, + appName: appName, + ns: ns, + image: image, + port: info.Port, + language: string(info.Language), + bundleDir: bundleDir, + secrets: info.Secrets, + config: info.Config, + dryRun: dryRun, + opts: doctor.GenerateOptions{ + NoHA: noHA, + NoSecure: noSecure, + Clean: clean, + }, + }); err != nil { + return err } // Step 4 — Apply bundle @@ -280,7 +238,7 @@ to the cluster, and patch the CR to trigger a rolling deploy. if err := applyBundle.Run(); err != nil { return fmt.Errorf("applying bundle: %w", err) } - fmt.Printf(" %s Bundle applied", utils.SuccessMark()) + fmt.Printf(" %s Bundle applied ", utils.SuccessMark()) for _, f := range []string{doctor.AppConfigFile, doctor.AppSecretFile} { path := filepath.Join(bundleDir, f) @@ -326,15 +284,27 @@ to the cluster, and patch the CR to trigger a rolling deploy. } } - resolvedValues := values - if resolvedValues == "" { + var helmValues []string + if values != "" { + helmValues = append(helmValues, values) + } else { localValues := filepath.Join(dir, orkDir, "values.yaml") if fileExistsAtPath(localValues) { - resolvedValues = localValues + helmValues = append(helmValues, localValues) fmt.Printf(" Using values: %s\n", localValues) } } + // If the developer set controlCenterHost in app.yaml, enable CC ingress. + appData, _ := doctor.ReadAppYAMLData(filepath.Join(dir, orkDir, doctor.ApplicationFile)) + if ccHost := appData["controlCenterHost"]; ccHost != "" { + if ccValuesFile, err := doctor.BuildControlCenterValues(ccHost); err == nil { + defer os.Remove(ccValuesFile) + helmValues = append(helmValues, ccValuesFile) + fmt.Printf(" Control Center ingress: %s\n", ccHost) + } + } + repoAdd := exec.Command("helm", "repo", "add", doctor.Orkestra, doctor.OrkestraChartRepo) repoAdd.Stdout = os.Stdout @@ -353,7 +323,7 @@ to the cluster, and patch the CR to trigger a rolling deploy. if !doctor.OrkestraInstalled() || upgradeOrkestra { fmt.Println(" ⠸ Installing Orkestra...") if err := doctor.InstallOrUpgradeOrkestra( - orkestraVersion, resolvedValues, upgradeOrkestra, + orkestraVersion, helmValues, upgradeOrkestra, ); err != nil { return err } @@ -377,7 +347,8 @@ to the cluster, and patch the CR to trigger a rolling deploy. return fmt.Errorf("orkestra runtime is not healthy") } - if doctor.KatalogChanged(dir) { + deployDir, _ := doctor.StateDir() + if doctor.CentralKatalogChanged(state, deployDir) { fmt.Println(" Katalog changed — restarting Orkestra runtime") if err := doctor.RestartOrkestra(); err != nil { return fmt.Errorf("restarting Orkestra: %w", err) @@ -386,7 +357,7 @@ to the cluster, and patch the CR to trigger a rolling deploy. fmt.Println(" Katalog unchanged — Orkestra restart not required") } - state.RecordDeploy(appName, ns, absKatalogPath, image) + state.RecordDeploy(appName, ns, filepath.Join(deployDir, "katalog.yaml"), image) if err := state.Save(); err != nil { fmt.Printf(" ~ State save failed: %v\n", err) } @@ -630,11 +601,13 @@ func deployMultiApp(dc deployContext) error { fmt.Printf(" %s All bundles applied", utils.SuccessMark()) // Install Orkestra once - resolvedValues := dc.values - if resolvedValues == "" { + var helmValues []string + if dc.values != "" { + helmValues = append(helmValues, dc.values) + } else { localValues := filepath.Join(dc.dir, orkDir, "values.yaml") if fileExistsAtPath(localValues) { - resolvedValues = localValues + helmValues = append(helmValues, localValues) } } @@ -645,7 +618,7 @@ func deployMultiApp(dc deployContext) error { if !doctor.OrkestraInstalled() || dc.upgradeOrkestra { fmt.Println(" ⠸ Installing Orkestra...") - if err := doctor.InstallOrUpgradeOrkestra(dc.orkestraVersion, resolvedValues, dc.upgradeOrkestra); err != nil { + if err := doctor.InstallOrUpgradeOrkestra(dc.orkestraVersion, helmValues, dc.upgradeOrkestra); err != nil { return err } fmt.Printf(" %s Orkestra installed", utils.SuccessMark()) @@ -766,8 +739,8 @@ var rollbackCmd = &cobra.Command{ Long: `Restore the previous image instantly by patching the ConfigMap. No rebuild or push required — the image is stored in ~/.orkestra/deploy/state.json. - ork deploy rollback # restore previous image - ork deploy rollback --image ghcr.io/x:v1 # restore a specific image`, + ork doctor deploy rollback # restore previous image + ork doctor deploy rollback --image ghcr.io/x:v1 # restore a specific image`, Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { targetImage, _ := cmd.Flags().GetString("image") @@ -891,16 +864,47 @@ func init() { // appName is the bare project name (without -orkestra suffix) used for state // lookup. state may be nil (e.g. when called from rollbackCmd). func watchUntilReady(crName, ns, appName string, state *doctor.DeployState) error { - ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) - defer cancel() + // Total budget: 2 min waiting for Orkestra to create the Deployment + + // 5 min for the rollout itself. Orkestra's default resync is 30 s so a + // new app can take 30–60 s before its Deployment object appears. + const deploymentAppearTimeout = 2 * time.Minute + const rolloutTimeout = 5 * time.Minute spin := spinner.Start(" → Waiting for rollout...") - cmd := exec.CommandContext(ctx, + // Phase 1: poll until the Deployment exists. kubectl rollout status exits + // immediately with a non-zero code when the object is missing, so we must + // not call it before Orkestra has reconciled the ConfigMap CR. + appearCtx, appearCancel := context.WithTimeout(context.Background(), deploymentAppearTimeout) + defer appearCancel() + + for { + check := exec.CommandContext(appearCtx, + "kubectl", "get", "deployment", crName, "-n", ns) + check.Stdout = io.Discard + check.Stderr = io.Discard + if check.Run() == nil { + break // Deployment exists + } + if appearCtx.Err() != nil { + spin.Failure() + return fmt.Errorf( + "timed out waiting for Deployment %s to appear in %s — Orkestra may still be starting\n"+ + " check: kubectl get deployment %s -n %s", + crName, ns, crName, ns) + } + time.Sleep(5 * time.Second) + } + + // Phase 2: standard rollout watch now that the Deployment exists. + rollCtx, rollCancel := context.WithTimeout(context.Background(), rolloutTimeout) + defer rollCancel() + + cmd := exec.CommandContext(rollCtx, "kubectl", "rollout", "status", "deployment/"+crName, "-n", ns, - "--timeout=5m", + fmt.Sprintf("--timeout=%s", rolloutTimeout), ) cmd.Stdout = io.Discard cmd.Stderr = io.Discard @@ -908,31 +912,25 @@ func watchUntilReady(crName, ns, appName string, state *doctor.DeployState) erro if err := cmd.Run(); err != nil { spin.Failure() - // Fetch recent pod logs to help the developer diagnose the failure. logOut, logErr := exec.Command("kubectl", "logs", - "deployment/"+crName, "-n", ns, - "--tail=20", - ).CombinedOutput() + "deployment/"+crName, "-n", ns, "--tail=20").CombinedOutput() if logErr == nil && len(bytes.TrimSpace(logOut)) > 0 { fmt.Printf("\n--- %s logs (last 20 lines) ---\n%s\n---\n", crName, string(logOut)) } - // Rollback hint — only when this is not the first deploy. if state != nil && state.PreviousImage(appName) != "" { fmt.Printf("\n A previous good image is available.\n") - fmt.Printf(" Roll back with: ork deploy rollback\n") + fmt.Printf(" Roll back with: ork doctor deploy rollback\n") } - if ctx.Err() == context.DeadlineExceeded { + if rollCtx.Err() == context.DeadlineExceeded { return fmt.Errorf("timed out waiting for %s — check: kubectl get pods -n %s", crName, ns) } - return fmt.Errorf("rollout failed for %s — check: kubectl describe deployment %s -n %s", crName, crName, ns) } spin.Success() - printReadySummary(crName, ns, state) return nil } @@ -1030,6 +1028,174 @@ func fileExistsAtPath(path string) bool { return err == nil && !info.IsDir() } +// loadInitCfgFromState reads init settings (useCompose, apps) from state.json, +// avoiding the need for .orkestra/bundle/.init.ork on re-deploy. +// Returns an empty InitConfig when the state has no matching entry. +func loadInitCfgFromState(state *doctor.DeployState, dir string) buildx.InitConfig { + if state == nil { + return buildx.InitConfig{} + } + // Look for any project whose Dir matches this directory. + for _, p := range state.Projects { + if p.Dir == dir { + cfg := buildx.InitConfig{ + UseCompose: p.UseCompose, + ComposeFile: p.ComposeFile, + } + // Reconstruct Apps from DirApps if present. + if names, ok := state.DirApps[dir]; ok { + for _, name := range names { + cfg.Apps = append(cfg.Apps, buildx.AppEntry{Name: name, Dir: dir}) + } + } + return cfg + } + } + return buildx.InitConfig{} +} + +// devPathArgs bundles parameters for deployDeveloperPath. +type devPathArgs struct { + dir string + appName string + ns string + image string + port string + language string + bundleDir string + secrets []orktypes.EnvVar + config []orktypes.EnvVar + dryRun bool + opts doctor.GenerateOptions +} + +// deployDeveloperPath implements the developer deploy flow: +// 1. Load the motif template from ~/.orkestra/apps//motif.yaml +// 2. Collect all deployed app namespaces (current + previously deployed) for allowedNamespaces +// 3. Write ~/.orkestra/deploy/katalog.yaml with ONE platform CRD — resources +// embedded directly in operatorBox.onReconcile (no file imports) +// 4. Generate bundle (RBAC + ConfigMap) from the self-contained central katalog +func deployDeveloperPath(a devPathArgs) error { + motifPath, err := doctor.MotifPath(a.appName) + if err != nil { + return fmt.Errorf("resolving motif path: %w", err) + } + // Legacy fallback: accept motif.yaml from .orkestra/ if the global one is missing. + if !fileExistsAtPath(motifPath) { + legacyPath := filepath.Join(a.dir, orkDir, "motif.yaml") + if fileExistsAtPath(legacyPath) { + motifPath = legacyPath + } else { + return fmt.Errorf("motif not found — run 'ork doctor init --name %s' first", a.appName) + } + } + + fmt.Println("\nUsing developer path...") + + deployDir, err := doctor.StateDir() + if err != nil { + return fmt.Errorf("resolving deploy dir: %w", err) + } + + if !a.dryRun { + if err := os.MkdirAll(deployDir, 0o755); err != nil { + return fmt.Errorf("creating deploy dir: %w", err) + } + + // Build the apps list: current app first, then all previously deployed apps. + // We resolve metadata (name, namespace) here — the Katalog gets concrete resource + // entries per app so Orkestra manages them independently without cross-app collision. + apps := []doctor.AppDeployInfo{{ + Name: a.appName, + Namespace: a.ns, + Port: a.port, + Language: a.language, + Image: a.image, + }} + state, _ := doctor.LoadState() + if state != nil { + for name, p := range state.Projects { + if name != a.appName && p.Namespace != "" { + apps = append(apps, doctor.AppDeployInfo{ + Name: name, + Namespace: p.Namespace, + Port: p.Port, + Language: p.Language, + Image: p.CurrentImage, + }) + } + } + } + + // Read the motif template content and generate the central katalog. + motifContent, err := os.ReadFile(motifPath) + if err != nil { + return fmt.Errorf("reading motif template: %w", err) + } + if err := doctor.GenerateDeveloperKatalog(deployDir, string(motifContent), apps, a.opts); err != nil { + return fmt.Errorf("generating developer katalog: %w", err) + } + fmt.Printf(" %s Developer katalog updated\n", utils.SuccessMark()) + + // Persist port/language to state for future re-deploys. + if state != nil { + if p := state.Projects[a.appName]; p != nil { + p.Port = a.port + p.Language = a.language + } else { + state.Projects[a.appName] = &doctor.ProjectState{ + Name: a.appName, + Namespace: a.ns, + Port: a.port, + Language: a.language, + } + } + // state.Save() is called by the caller after RecordDeploy — no double save needed. + } + + // Validate the generated katalog. + validateCmd := exec.Command("ork", "validate", "-f", filepath.Join(deployDir, "katalog.yaml")) + if out, err := validateCmd.CombinedOutput(); err != nil { + fmt.Printf(" ~ katalog validation warning: %s\n", strings.TrimSpace(string(out))) + } + + // Ensure each app's namespace exists. Namespaces are infrastructure — + // we create them directly via kubectl (idempotent, no bundle dependency). + for _, app := range apps { + nsYAML := fmt.Sprintf("apiVersion: v1\nkind: Namespace\nmetadata:\n name: %s\n", app.Namespace) + nsCmd := exec.Command("kubectl", "apply", "-f", "-") + nsCmd.Stdin = strings.NewReader(nsYAML) + nsCmd.Stdout = os.Stdout + nsCmd.Stderr = os.Stderr + if err := nsCmd.Run(); err != nil { + fmt.Printf(" ~ could not ensure namespace %s: %v\n", app.Namespace, err) + } + } + + // Generate env Secret/ConfigMap for the current app. + if err := os.MkdirAll(a.bundleDir, 0o755); err != nil { + return fmt.Errorf("creating bundle dir: %w", err) + } + if err := doctor.GenerateBundle(a.appName, a.ns, a.secrets, a.config, a.bundleDir); err != nil { + return fmt.Errorf("generating env bundle: %w", err) + } + + // Generate the RBAC + Katalog ConfigMap bundle from the central katalog. + centralKatalogPath := filepath.Join(deployDir, "katalog.yaml") + genCmd := exec.Command("ork", "generate", "bundle", "-f", centralKatalogPath, "-w", a.ns, "-o", a.bundleDir) + genCmd.Stdout = os.Stdout + genCmd.Stderr = os.Stderr + if err := genCmd.Run(); err != nil { + return fmt.Errorf("generating bundle: %w", err) + } + fmt.Printf(" %s RBAC + Katalog ConfigMap\n", utils.SuccessMark()) + } else { + fmt.Printf(" ~ dry-run: would generate %s/katalog.yaml and bundle\n", deployDir) + } + + return nil +} + // exposeApp starts a tunnel for the given app and prints the public URL. // It port-forwards to the app's K8s service (-orkestra-svc) so the // tunnel survives after the deploy command exits regardless of ingress setup. diff --git a/cmd/cli/doctor.go b/cmd/cli/doctor.go index fb1e1bb4..c18bc9ad 100644 --- a/cmd/cli/doctor.go +++ b/cmd/cli/doctor.go @@ -7,8 +7,8 @@ import ( "os" "path/filepath" "strings" + "time" - "github.com/orkspace/orkestra/pkg/buildx" "github.com/orkspace/orkestra/pkg/doctor" orktypes "github.com/orkspace/orkestra/pkg/types" "github.com/spf13/cobra" @@ -197,11 +197,11 @@ Please add a Dockerfile to the project root. missing := 0 fmt.Println("Missing dependencies:") if !doctor.KubectlAvailable() { - fmt.Println(" kubectl (will be installed during 'ork deploy')") + fmt.Println(" kubectl (will be installed during 'ork doctor deploy')") missing++ } if !doctor.HelmAvailable() { - fmt.Println(" helm (will be installed during 'ork deploy')") + fmt.Println(" helm (will be installed during 'ork doctor deploy')") missing++ } if missing == 0 { @@ -341,7 +341,7 @@ var doctorInitCmd = &cobra.Command{ // ── Single-app init (legacy) ── if name == "" { - return fmt.Errorf("--name is required") + name = filepath.Base(dir) } opts.Name = name @@ -350,33 +350,38 @@ var doctorInitCmd = &cobra.Command{ return fmt.Errorf("detection failed: %w", err) } - if err := doctor.Init(info, opts); err != nil { + motifContent, err := doctor.InitDeveloper(info, opts) + if err != nil { return err } - shouldUseCompose := useCompose != "" - if err := buildx.WriteInitConfig(dir, shouldUseCompose, useCompose); err != nil { - return fmt.Errorf("writing init config: %v", err) + // Store the motif in ~/.orkestra/apps// — outside the project tree. + if err := doctor.SaveMotif(name, motifContent); err != nil { + return fmt.Errorf("saving motif: %w", err) } - crName := name + "-orkestra" - ns := name + "-orkestra-ns" + // Persist init settings to state so ork doctor deploy never needs .init.ork. + state, _ := doctor.LoadState() + if state == nil { + state = &doctor.DeployState{Projects: make(map[string]*doctor.ProjectState)} + } + if state.Projects[name] == nil { + state.Projects[name] = &doctor.ProjectState{Name: name} + } + state.Projects[name].Dir = dir + state.Projects[name].UseCompose = useCompose != "" + state.Projects[name].ComposeFile = useCompose + _ = state.Save() fmt.Println() fmt.Printf("App: %s\n", name) - fmt.Printf("AppConfig: %s\n", crName) - fmt.Printf("Namespace: %s\n", ns) + fmt.Printf("Namespace: %s-ns\n", name) fmt.Println() - fmt.Println("Generated .orkestra/katalog.yaml") fmt.Println("Generated .orkestra/app.yaml") - if addIngress && !info.HasFrontend { - fmt.Println(" (Ingress included via --add-ingress)") - } fmt.Println() fmt.Println("Next steps:") - fmt.Println(" 1. Review .orkestra/katalog.yaml (edit freely)") - fmt.Println(" 2. Fill in .orkestra/app.yaml (replicas, host, controlCenterHost, etc.)") - fmt.Println(" 3. Run 'ork deploy --registry '") + fmt.Println(" 1. Fill in .orkestra/app.yaml (port, replicas, etc.)") + fmt.Println(" 2. Run 'ork doctor deploy --registry '") return nil }, @@ -475,7 +480,8 @@ func doctorInitMultiApp(baseDir string, cmd *cobra.Command, opts doctor.Generate fmt.Println("Generating multi-app config...") fmt.Println() - var initApps []buildx.AppEntry + type initApp struct{ Name, Dir, Dockerfile string } + var initApps []initApp // Cache augmented info per app so URL hints use the same resolved port. appInfoCache := make(map[string]*orktypes.ProjectInfo, len(apps)) @@ -487,10 +493,10 @@ func doctorInitMultiApp(baseDir string, cmd *cobra.Command, opts doctor.Generate if perAppStateful != nil { // Multi-app compose path: supply only the stateful services this - // specific app depends on. Clearing UseCompose prevents doctor.Init - // from re-parsing the compose file and injecting everything again. + // specific app depends on. Clearing UseCompose prevents re-parsing + // the compose file and injecting everything again. appOpts.UseCompose = "" - appOpts.InjectStateful = perAppStateful[app.name] // nil = no stateful for this app + appOpts.InjectStateful = perAppStateful[app.name] } // Wire dep conditions into the deployment when: block. @@ -510,31 +516,47 @@ func doctorInitMultiApp(baseDir string, cmd *cobra.Command, opts doctor.Generate appInfoCache[app.name] = info - if err := doctor.Init(info, appOpts); err != nil { + motifContent, err := doctor.InitDeveloper(info, appOpts) + if err != nil { return fmt.Errorf("init %s: %w", app.name, err) } + if err := doctor.SaveMotif(app.name, motifContent); err != nil { + return fmt.Errorf("saving motif for %s: %w", app.name, err) + } + fmt.Printf(" %s:\n", app.name) - fmt.Printf(" Generated .orkestra/%s/katalog.yaml\n", app.name) fmt.Printf(" Generated .orkestra/%s/app.yaml\n", app.name) - initApps = append(initApps, buildx.AppEntry{ + initApps = append(initApps, initApp{ Name: app.name, Dir: app.dir, Dockerfile: app.dockerfile, }) } - // Persist init config - cfg := buildx.InitConfig{ - UseCompose: useCompose != "", - ComposeFile: useCompose, - Apps: initApps, + // Persist init config to state + state, _ := doctor.LoadState() + if state == nil { + state = &doctor.DeployState{Projects: make(map[string]*doctor.ProjectState)} } - if err := buildx.WriteInitConfigFull(baseDir, cfg); err != nil { - return fmt.Errorf("writing init config: %w", err) + if state.DirApps == nil { + state.DirApps = make(map[string][]string) + } + appNames := make([]string, len(initApps)) + for i, a := range initApps { + appNames[i] = a.Name + if state.Projects[a.Name] == nil { + state.Projects[a.Name] = &doctor.ProjectState{Name: a.Name} + } + state.Projects[a.Name].Dir = a.Dir + state.Projects[a.Name].UseCompose = useCompose != "" + state.Projects[a.Name].ComposeFile = useCompose + } + state.DirApps[baseDir] = appNames + if err := state.Save(); err != nil { + return fmt.Errorf("saving state: %w", err) } - // Print internal URLs — use cached augmented info so ports reflect compose ports:. fmt.Println() fmt.Println("Internal service URLs (set these in each app's .env before deploying):") @@ -550,8 +572,7 @@ func doctorInitMultiApp(baseDir string, cmd *cobra.Command, opts doctor.Generate } fmt.Println() fmt.Println("Next steps:") - fmt.Println(" 1. Review .orkestra//katalog.yaml for each app") - fmt.Println(" 2. Fill in .orkestra//app.yaml for each app") + fmt.Println(" 1. Fill in .orkestra//app.yaml for each app") // When stateful services were wired to specific apps, tell the user exactly // where to find and configure the dependency keys. @@ -575,11 +596,105 @@ func doctorInitMultiApp(baseDir string, cmd *cobra.Command, opts doctor.Generate } fmt.Println() - fmt.Println(" 3. Run 'ork deploy --registry '") + fmt.Println(" 3. Run 'ork doctor deploy --registry '") _ = projectName return nil } +// doctorDeployCmd is `ork doctor deploy` — the developer-path deploy command. +// It runs the same flow as `ork doctor deploy` but is discoverable as a subcommand of +// `ork doctor`, making it natural for developers who start with `ork doctor init`. +var doctorDeployCmd = &cobra.Command{ + Use: "deploy", + Short: "Build, push, and deploy the current project (developer path)", + Long: `Build the Docker image, push it, write the central developer katalog, +generate the bundle, apply it to the cluster, and patch the ConfigMap CR. + + ork doctor deploy --registry docker.io/myorg + ork doctor deploy --registry docker.io/myorg --dev + ork doctor deploy --registry docker.io/myorg --dry-run`, + RunE: deployCmd.RunE, +} + +// doctorStatusCmd is `ork doctor status` — prints the current deploy state. +var doctorStatusCmd = &cobra.Command{ + Use: "status", + Short: "Show current deploy state (cluster, katalog, apps)", + Long: `Read ~/.orkestra/deploy/state.json and print a concise summary of +what is deployed, which cluster it targets, and whether the central katalog +has changed since the last deploy. + + ork doctor status`, + RunE: func(cmd *cobra.Command, args []string) error { + state, err := doctor.LoadState() + if err != nil { + return fmt.Errorf("reading state: %w", err) + } + + deployDir, err := doctor.StateDir() + if err != nil { + return fmt.Errorf("resolving deploy dir: %w", err) + } + + // Cluster context + clusterCtx := state.ClusterContext + if clusterCtx == "" { + clusterCtx = doctor.CurrentContext() + } + fmt.Printf("Cluster: %s\n", clusterCtx) + + // Katalog path + changed/unchanged status + katalogPath := filepath.Join(deployDir, "katalog.yaml") + katalogChanged := doctor.CentralKatalogChanged(state, deployDir) + changeLabel := "unchanged" + if katalogChanged { + changeLabel = "changed" + } + home, _ := os.UserHomeDir() + displayPath := katalogPath + if home != "" { + displayPath = strings.Replace(katalogPath, home, "~", 1) + } + fmt.Printf("Katalog: %s (%s)\n", displayPath, changeLabel) + + // Apps + fmt.Printf("\nApps (%d):\n", len(state.Projects)) + for _, name := range state.DeployedAppNames() { + p := state.Projects[name] + relTime := relativeTime(p.DeployedAt) + fmt.Printf(" %-20s %-25s %-50s deployed %s\n", + p.Name, p.Namespace, p.CurrentImage, relTime) + } + + // Orkestra runtime health + fmt.Println() + health := doctor.CheckRuntimeHealth() + if health.Running { + fmt.Println("Orkestra: running") + } else { + fmt.Printf("Orkestra: not healthy (%s)\n", health.Reason) + } + + return nil + }, +} + +// relativeTime formats a time.Time as a human-friendly relative string ("2h ago", "5m ago"). +func relativeTime(t time.Time) string { + if t.IsZero() { + return "unknown" + } + d := time.Since(t) + switch { + case d < time.Minute: + return fmt.Sprintf("%ds ago", int(d.Seconds())) + case d < time.Hour: + return fmt.Sprintf("%dm ago", int(d.Minutes())) + default: + return fmt.Sprintf("%dh ago", int(d.Hours())) + } +} + func init() { doctorCmd.PersistentFlags().Bool("no-ha", false, "Skip HPA and PDB (single replica)") doctorCmd.PersistentFlags().Bool("no-secure", false, "Skip deletion protection and protection labels") @@ -593,7 +708,22 @@ func init() { doctorInitCmd.Flags().Bool("notify-me", false, "Auto-enable notifications using SMTP_*/SLACK_* from .env and your Git author") doctorInitCmd.Flags().String("use-compose", "", "Path to docker-compose.yaml — deploy all buildable services as separate apps") + doctorDeployCmd.Flags().StringP("registry", "r", "", "Container registry (e.g. docker.io/myorg)") + doctorDeployCmd.Flags().StringP("tag", "t", "", "Image tag (default: git commit SHA)") + doctorDeployCmd.Flags().String("name", "", "App name override (default: read from .orkestra/app.yaml)") + doctorDeployCmd.Flags().Bool("dry-run", false, "Show what would be applied without making changes") + doctorDeployCmd.Flags().Bool("upgrade-orkestra", false, "Upgrade Orkestra to latest version before deployment") + doctorDeployCmd.Flags().String("orkestra-version", "", "Version of Orkestra operator to install") + doctorDeployCmd.Flags().String("values", "", "Path to Helm values.yaml for Orkestra installation") + doctorDeployCmd.Flags().Bool("dev", false, "Create a local kind cluster (orkestra-playground) for development") + doctorDeployCmd.Flags().Bool("enable-metrics", false, "Install metrics server to the cluster") + doctorDeployCmd.Flags().Bool("expose", false, "Expose the app via a public HTTPS tunnel") + doctorDeployCmd.Flags().String("tunnel-provider", "", "Tunnel provider: cloudflared (default) or ngrok") + doctorDeployCmd.Flags().String("tunnel-token", "", "Auth token for ngrok tunnels") + doctorCmd.AddCommand(doctorInitCmd) + doctorCmd.AddCommand(doctorDeployCmd) + doctorCmd.AddCommand(doctorStatusCmd) rootCmd.AddCommand(doctorCmd) // Shadow global flags so they don't appear under `ork init` diff --git a/cmd/cli/generate.go b/cmd/cli/generate.go index e23ef455..666d3775 100644 --- a/cmd/cli/generate.go +++ b/cmd/cli/generate.go @@ -338,7 +338,7 @@ func init() { cmd.Flags().Bool("dry-run", false, "Print generated output to stdout without writing files") cmd.Flags().StringP("output", "o", "", "Write generated output to file") cmd.Flags().StringP("namespace", "n", defaultNamespace(), "Namespace for the ServiceAccount") - cmd.Flags().StringP("workload-namespace", "w", "", "Namespace for the Deployment Workloads. Used by 'ork deploy'") + cmd.Flags().StringP("workload-namespace", "w", "", "Namespace for the Deployment Workloads. Used by 'ork doctor deploy'") } // Shadow global flags so they don't appear under `ork generate` diff --git a/cmd/cli/tunnel.go b/cmd/cli/tunnel.go index 929f8cc9..421f0080 100644 --- a/cmd/cli/tunnel.go +++ b/cmd/cli/tunnel.go @@ -18,7 +18,7 @@ const controlCenterTunnelName = "controlcenter" var tunnelCmd = &cobra.Command{ Use: "tunnel", Short: "Manage Orkestra tunnel daemons", - Long: `Manage the public HTTPS tunnels started by ork deploy --expose. + Long: `Manage the public HTTPS tunnels started by ork doctor deploy --expose. ork tunnel expose Start a tunnel for an app or Control Center ork tunnel status Show all running tunnels @@ -59,16 +59,21 @@ Note: exposing orkestra-runtime is not supported.`, PortForward: true, } } else { - ns, err := resolveAppNamespace(name) + ns, port, err := resolveAppNamespaceAndPort(name) if err != nil { return err } + if ns == "" { + fmt.Fprintf(os.Stderr, " ✗ App %q is not deployed. Run 'ork doctor deploy' first.\n", name) + fmt.Fprintf(os.Stderr, " To see deployed apps: ork doctor status\n") + return fmt.Errorf("app not deployed: %s", name) + } opts = tunnel.ExposeOptions{ Name: name, Provider: provider, Token: token, - ServiceName: name + "-orkestra-svc", - ServicePort: "8080", + ServiceName: name + "-svc", + ServicePort: port, Namespace: ns, } } @@ -93,7 +98,7 @@ var tunnelStatusCmd = &cobra.Command{ } if len(states) == 0 { fmt.Println(" No tunnels running") - fmt.Println(" Start one with: ork deploy --expose or ork tunnel expose ") + fmt.Println(" Start one with: ork doctor deploy --expose or ork tunnel expose ") return nil } @@ -181,16 +186,23 @@ var tunnelRestartCmd = &cobra.Command{ }, } -// resolveAppNamespace looks up the namespace for an app from deploy state, -// falling back to the conventional -orkestra-ns pattern. -func resolveAppNamespace(appName string) (string, error) { - state, err := doctor.LoadState() - if err == nil && state != nil { - if p, ok := state.Projects[appName]; ok && p.Namespace != "" { - return p.Namespace, nil - } +// resolveAppNamespaceAndPort looks up the namespace and port for an app from +// deploy state. Returns an empty ns when the app is not in state (not deployed). +func resolveAppNamespaceAndPort(appName string) (ns, port string, err error) { + state, loadErr := doctor.LoadState() + if loadErr != nil || state == nil { + return "", "", nil + } + p, ok := state.Projects[appName] + if !ok { + return "", "", nil + } + ns = p.Namespace + port = p.Port + if port == "" { + port = "8080" } - return appName + "-orkestra-ns", nil + return ns, port, nil } func init() { diff --git a/cmd/cli/validate.go b/cmd/cli/validate.go index 780811d8..be3c94c5 100644 --- a/cmd/cli/validate.go +++ b/cmd/cli/validate.go @@ -28,6 +28,20 @@ var validateCmd = &cobra.Command{ return fmt.Errorf("reading %s: %w", path, err) } + // Validate document type + if !konfig.IsValidDocumentKind(kind) { + if kind == "" { + return fmt.Errorf( + "not an Orkestra document — expected a 'kind' field (allowed kinds: %s)", + konfig.ValidKindsString(), + ) + } + return fmt.Errorf( + "invalid Orkestra document kind %q (allowed kinds: %s)", + kind, konfig.ValidKindsString(), + ) + } + if konfig.IsMotifKind(kind) { return validateMotifFile(path) } diff --git a/cmd/controlcenter/cc/assets/templates/dev_app_detail.html b/cmd/controlcenter/cc/assets/templates/dev_app_detail.html new file mode 100644 index 00000000..111d1043 --- /dev/null +++ b/cmd/controlcenter/cc/assets/templates/dev_app_detail.html @@ -0,0 +1,224 @@ + + + + + + {{ .App.Name }} – Orkestra + + + + + + + + +
+ +
+
+ + +
+ +
+
+ +
+ + +
+
+
+
+

{{ .App.Name }}

+ {{ if .App.Language }} + {{ .App.Language }} + {{ end }} + + Deployed + +
+ {{ if .App.Namespace }} +

+ + {{ .App.Namespace }} +

+ {{ end }} +
+
+
+ + {{ $hasSignals := or .App.HasDockerfile (or .App.HasFrontend (or .App.HasCompose (or .App.HasSMTP (or .App.HasSlack (ne .App.License ""))))) }} +
+ + +
+
Deployment
+ + {{ if .App.CurrentImage }} +
+
Image
+ {{ .App.CurrentImage }} +
+ {{ end }} + + {{ if .App.GitCommit }} +
+
Commit
+ {{ .App.GitCommit }} +
+ {{ end }} + + {{ if .App.Port }} +
+
Port
+ {{ .App.Port }} +
+ {{ end }} + + {{ if .App.ServiceURL }} +
+
Internal URL
+ {{ .App.ServiceURL }} +
+ {{ end }} +
+ + + {{ if $hasSignals }} +
+
Project
+ +
+ + {{ if .App.HasDockerfile }} +
+ + Dockerfile present +
+ {{ end }} + + {{ if .App.HasFrontend }} +
+ + Frontend detected +
+ {{ end }} + + {{ if .App.HasCompose }} +
+ + Docker Compose present +
+ {{ end }} + + {{ if .App.HasSMTP }} +
+ + SMTP configured +
+ {{ end }} + + {{ if .App.HasSlack }} +
+ + Slack webhook configured +
+ {{ end }} + + {{ if .App.License }} +
+ + {{ .App.License }} +
+ {{ end }} + +
+
+ {{ end }} + +
+ + + {{ if or (gt .App.SecretCount 0) (gt .App.ConfigCount 0) }} +
+
Environment
+
+ {{ if gt .App.SecretCount 0 }} +
+
{{ .App.SecretCount }}
+
secret{{ if gt .App.SecretCount 1 }}s{{ end }}
+
+ {{ end }} + {{ if gt .App.ConfigCount 0 }} +
+
{{ .App.ConfigCount }}
+
config var{{ if gt .App.ConfigCount 1 }}s{{ end }}
+
+ {{ end }} +
+
+ {{ end }} + + +
+
+ To redeploy: ork doctor deploy +  ·  + ← Back to Applications +
+
+ +
+
+ + + + diff --git a/cmd/controlcenter/cc/assets/templates/dev_apps.html b/cmd/controlcenter/cc/assets/templates/dev_apps.html new file mode 100644 index 00000000..7d526e3f --- /dev/null +++ b/cmd/controlcenter/cc/assets/templates/dev_apps.html @@ -0,0 +1,155 @@ + + + + + + Your Applications – Orkestra + + + + + + + + +
+ +
+
+ + +
+ +
+
+ +
+ + +
+
+
+
+

Applications

+ + + Deployed + +
+

+ {{ len .Apps }} app{{ if ne (len .Apps) 1 }}s{{ end }} managed via ork doctor deploy +

+
+
+
+ + {{ if eq (len .Apps) 0 }} +
+ + + +
+
No applications deployed yet
+
Run ork doctor deploy from your project directory to deploy your first app.
+
+
+ {{ else }} + + + {{ end }} + +
+
+ + + + diff --git a/cmd/controlcenter/cc/assets/templates/dev_docs.html b/cmd/controlcenter/cc/assets/templates/dev_docs.html new file mode 100644 index 00000000..9d576073 --- /dev/null +++ b/cmd/controlcenter/cc/assets/templates/dev_docs.html @@ -0,0 +1,225 @@ + + + + + + Docs – {{ .KatalogName }} + + + + + + + +
+ +
+
+ + +
+ +
+
+ +
+ + +
+

Developer Guide

+

+ Your apps run inside an isolated cluster managed by Orkestra. + Each app gets its own namespace, service, and deployment — all created automatically when you run ork doctor deploy. + This page summarises what was detected and how to work with each app. +

+
+
+ Deploy — ork doctor deploy +
+
+ Status — ork doctor status +
+
+ Tunnel — ork tunnel expose +
+
+
+ + {{ range .Apps }} + +
+
+

{{ .Name }}

+ {{ if .Language }}{{ .Language }}{{ end }} +
+ + +
+ + {{ if .Namespace }} +
+
Namespace
+ {{ .Namespace }} +
+ {{ end }} + + {{ if .Port }} +
+
Port
+ {{ .Port }} +
+ {{ end }} + + {{ if .GitCommit }} +
+
Commit
+ {{ .GitCommit }} +
+ {{ end }} + + {{ if .License }} +
+
License
+ {{ .License }} +
+ {{ end }} + +
+ + + {{ if .ServiceURL }} +
+
Reach this app from inside the cluster
+
{{ .ServiceURL }}
+
+ {{ end }} + + +
+
Redeploy after changes
+
+ cd /path/to/{{ .Name }}
+ ork doctor deploy +
+
+ + +
+
Expose publicly for testing
+
+ ork tunnel expose --name {{ .Name }} --port {{ .Port }} +
+
+ + + {{ $hasSignals := or .HasDockerfile .HasFrontend .HasSMTP .HasSlack .HasCompose }} + {{ if $hasSignals }} +
+
Detected during setup
+
+ {{ if .HasDockerfile }} +
+ + Dockerfile found — your image is built automatically on deploy +
+ {{ end }} + {{ if .HasFrontend }} +
+ + Frontend detected — a separate service is configured for the UI +
+ {{ end }} + {{ if .HasCompose }} +
+ + Docker Compose found — services declared there are available in the cluster +
+ {{ end }} + {{ if .HasSMTP }} +
+ + SMTP credentials found in .env — email sending should work out of the box +
+ {{ end }} + {{ if .HasSlack }} +
+ + Slack webhook found — deploy notifications are wired +
+ {{ end }} +
+
+ {{ end }} + + + {{ if or (gt .SecretCount 0) (gt .ConfigCount 0) }} +
+ {{ if gt .SecretCount 0 }} + {{ .SecretCount }} secret{{ if gt .SecretCount 1 }}s{{ end }} from .env + {{ end }} + {{ if gt .ConfigCount 0 }} + {{ .ConfigCount }} config var{{ if gt .ConfigCount 1 }}s{{ end }} from .env + {{ end }} +
+ {{ end }} + +
+ {{ end }} + +
+
+ + + + diff --git a/cmd/controlcenter/cc/assets/templates/index.html b/cmd/controlcenter/cc/assets/templates/index.html index ac8a6610..f75a3964 100644 --- a/cmd/controlcenter/cc/assets/templates/index.html +++ b/cmd/controlcenter/cc/assets/templates/index.html @@ -36,12 +36,14 @@ All Katalogs + {{ if .HasOperatorKatalogs }} Metrics + {{ end }} {{ if .EnableRuntimeManager }} @@ -51,6 +53,7 @@ Manage Runtimes {{ end }} + {{ if .HasOperatorKatalogs }} @@ -61,6 +64,7 @@ Documentation + {{ end }}
@@ -114,21 +118,34 @@
{{ .TotalKatalogs }}
{{ .HealthyKatalogs }} healthy
+ {{ if gt .TotalApps 0 }}
-
Total CRDs
+
Applications
+
{{ .TotalApps }}
+
via ork doctor
+
+ {{ end }} + {{ if gt .TotalCRDs 0 }} +
+
CRDs
{{ .TotalCRDs }}
-
Across all Katalogs
+
Operator resources
+ {{ end }} + {{ if gt .TotalWorkers 0 }}
-
Total Workers
+
Workers
{{ .TotalWorkers }}
-
All reconcilers combined
+
Reconcilers running
+ {{ end }} + {{ if gt .TotalResources 0 }}
Live Resources
{{ .TotalResources }}
CRs in cache
+ {{ end }} {{ if gt (len .Katalogs) 0 }} @@ -158,6 +175,16 @@

{{ .Name }}

+ {{ if eq .CreatedBy "orkdoctor" }} +
+ Applications + {{ .AppCount }} +
+
+ Managed by + ork doctor +
+ {{ else }}
CRDs {{ .TotalCRDs }} ({{ .HealthyCRDs }} healthy) @@ -170,9 +197,10 @@

{{ .Name }}

Resources {{ .TotalResources }}
+ {{ end }}
- View Panel + {{ if eq .CreatedBy "orkdoctor" }}View Apps{{ else }}View Panel{{ end }} diff --git a/cmd/controlcenter/cc/controlcenter.go b/cmd/controlcenter/cc/controlcenter.go index bc2837cc..1e05eb71 100644 --- a/cmd/controlcenter/cc/controlcenter.go +++ b/cmd/controlcenter/cc/controlcenter.go @@ -293,10 +293,13 @@ func (cc *ControlCenter) ServeHTTP(w http.ResponseWriter, r *http.Request) { cc.handleDocsLanding(w, r) case strings.HasPrefix(path, "/docs/"): - // /docs/{katalog}/{crd} + // /docs/{katalog} → developer docs or operator CRD list + // /docs/{katalog}/{crd} → CRD docs page parts := strings.SplitN(strings.TrimPrefix(path, "/docs/"), "/", 2) if len(parts) == 2 { cc.handleCRDDocs(w, r, parts[0], parts[1]) + } else if len(parts) == 1 && parts[0] != "" { + cc.handleKatalogDocs(w, r, parts[0]) } else { cc.handleDocsLanding(w, r) } @@ -330,6 +333,10 @@ func (cc *ControlCenter) routeKatalog(w http.ResponseWriter, r *http.Request, pa katalogName := parts[1] switch { + // /katalog/{name}/app/{appName} — developer path + case len(parts) == 4 && parts[2] == "app": + cc.handleDevAppDetail(w, r, katalogName, parts[3]) + // /katalog/{name}/crd/{crd}/cr[/...] case len(parts) >= 5 && parts[2] == "crd" && parts[4] == "cr": crdName := parts[3] @@ -519,7 +526,8 @@ func (cc *ControlCenter) handleIndex(w http.ResponseWriter, _ *http.Request) { }) var summaries []KatalogSummary - totalCRDs, totalWorkers, totalResources, healthyKatalogs := 0, 0, 0, 0 + totalCRDs, totalWorkers, totalResources, totalApps, healthyKatalogs := 0, 0, 0, 0, 0 + hasOperatorKatalogs := false for _, inst := range insts { kat := inst.Katalog @@ -529,19 +537,27 @@ func (cc *ControlCenter) handleIndex(w http.ResponseWriter, _ *http.Request) { healthyCRDs++ } } - summaries = append(summaries, KatalogSummary{ + summary := KatalogSummary{ Name: kat.Name, Description: kat.Description, Version: kat.Version, Healthy: kat.Healthy, + CreatedBy: kat.CreatedBy, + AppCount: len(kat.Projects), TotalCRDs: len(kat.CRDs), HealthyCRDs: healthyCRDs, TotalWorkers: sumWorkers(kat.CRDs), TotalResources: sumResources(kat.CRDs), - }) - totalCRDs += len(kat.CRDs) - totalWorkers += sumWorkers(kat.CRDs) - totalResources += sumResources(kat.CRDs) + } + summaries = append(summaries, summary) + if kat.CreatedBy == "orkdoctor" { + totalApps += len(kat.Projects) + } else { + hasOperatorKatalogs = true + totalCRDs += len(kat.CRDs) + totalWorkers += sumWorkers(kat.CRDs) + totalResources += sumResources(kat.CRDs) + } if kat.Healthy { healthyKatalogs++ } @@ -551,10 +567,12 @@ func (cc *ControlCenter) handleIndex(w http.ResponseWriter, _ *http.Request) { Katalogs: summaries, TotalKatalogs: len(summaries), HealthyKatalogs: healthyKatalogs, + TotalApps: totalApps, TotalCRDs: totalCRDs, TotalWorkers: totalWorkers, TotalResources: totalResources, AnyHealthy: len(summaries) > 0, + HasOperatorKatalogs: hasOperatorKatalogs, OrkestraURLs: strings.Join(cc.urls, ", "), CCVersion: ccversion.Short(), EnableRuntimeManager: cc.config.EnableRuntimeManager, @@ -575,6 +593,12 @@ func (cc *ControlCenter) handleKatalogPanel(w http.ResponseWriter, r *http.Reque kat := inst.Katalog + // Developer path: render a simplified app-focused view. + if kat.CreatedBy == "orkdoctor" { + cc.renderDevApps(w, r, kat) + return + } + // Sort CRDs by name for consistent display sortedCRDs := make([]CRDSummary, len(kat.CRDs)) copy(sortedCRDs, kat.CRDs) @@ -602,6 +626,82 @@ func (cc *ControlCenter) handleKatalogPanel(w http.ResponseWriter, r *http.Reque }) } +// buildDevAppSummary converts a ProjectInfoSummary into a DevAppSummary. +func buildDevAppSummary(proj ProjectInfoSummary) DevAppSummary { + imageTag := proj.CurrentImage + if idx := strings.LastIndex(imageTag, ":"); idx >= 0 { + imageTag = imageTag[idx+1:] + } + port := proj.Port + if port == "" { + port = "8080" + } + svcURL := "" + if proj.Name != "" && proj.Namespace != "" { + svcURL = fmt.Sprintf("http://%s-svc.%s.svc.cluster.local:%s", proj.Name, proj.Namespace, port) + } + return DevAppSummary{ + Name: proj.Name, + Namespace: proj.Namespace, + Port: port, + Language: proj.Language, + CurrentImage: proj.CurrentImage, + ImageTag: imageTag, + ServiceURL: svcURL, + GitCommit: proj.GitCommit, + License: proj.License, + HasDockerfile: proj.HasDockerfile, + HasFrontend: proj.HasFrontend, + HasSMTP: proj.HasSMTP, + HasSlack: proj.HasSlack, + HasCompose: proj.HasCompose, + SecretCount: proj.SecretCount, + ConfigCount: proj.ConfigCount, + } +} + +// renderDevApps renders the developer-path view for a katalog created by ork doctor. +func (cc *ControlCenter) renderDevApps(w http.ResponseWriter, _ *http.Request, kat *KatalogResponse) { + var apps []DevAppSummary + for _, proj := range kat.Projects { + s := buildDevAppSummary(proj) + if s.Name != "" { + apps = append(apps, s) + } + } + // Sort apps by name for stable output. + sort.Slice(apps, func(i, j int) bool { return apps[i].Name < apps[j].Name }) + + cc.renderTemplate(w, "dev_apps.html", DevAppsData{ + KatalogName: kat.Name, + Apps: apps, + RuntimeVersion: kat.RuntimeVersion, + }) +} + +// handleDevAppDetail renders /katalog/{katalog}/app/{appName} for developer katalogs. +func (cc *ControlCenter) handleDevAppDetail(w http.ResponseWriter, r *http.Request, katalogName, appName string) { + inst, ok := cc.instanceByKatalogName(katalogName) + if !ok { + cc.handleNotFound(w, r) + return + } + if inst.Katalog.CreatedBy != "orkdoctor" { + cc.handleNotFound(w, r) + return + } + proj, ok := inst.Katalog.Projects[appName] + if !ok { + cc.handleNotFound(w, r) + return + } + cc.renderTemplate(w, "dev_app_detail.html", DevAppDetailData{ + KatalogName: katalogName, + App: buildDevAppSummary(proj), + RuntimeVersion: inst.Katalog.RuntimeVersion, + }) +} + func (cc *ControlCenter) handleCRDDetail(w http.ResponseWriter, r *http.Request, katalogName, crdName string) { inst, ok := cc.instanceByKatalogName(katalogName) if !ok { diff --git a/cmd/controlcenter/cc/docs_handlers.go b/cmd/controlcenter/cc/docs_handlers.go index 5dc2c7c4..8488687e 100644 --- a/cmd/controlcenter/cc/docs_handlers.go +++ b/cmd/controlcenter/cc/docs_handlers.go @@ -100,6 +100,40 @@ func (cc *ControlCenter) handleDocsLanding(w http.ResponseWriter, r *http.Reques }) } +// DevDocsData is the view-model for the developer katalog docs page. +type DevDocsData struct { + KatalogName string + Apps []DevAppSummary + RuntimeVersion string +} + +// handleKatalogDocs dispatches /controlcenter/docs/{katalog}. +// Developer katalogs (createdBy == "orkdoctor") get a developer-friendly docs page. +// Operator katalogs fall back to the docs landing. +func (cc *ControlCenter) handleKatalogDocs(w http.ResponseWriter, r *http.Request, katalogName string) { + inst, ok := cc.instanceByKatalogName(katalogName) + if !ok { + cc.handleDocsLanding(w, r) + return + } + if inst.Katalog.CreatedBy != "orkdoctor" { + cc.handleDocsLanding(w, r) + return + } + + var apps []DevAppSummary + for _, proj := range inst.Katalog.Projects { + apps = append(apps, buildDevAppSummary(proj)) + } + sort.Slice(apps, func(i, j int) bool { return apps[i].Name < apps[j].Name }) + + cc.renderTemplate(w, "dev_docs.html", DevDocsData{ + KatalogName: katalogName, + Apps: apps, + RuntimeVersion: inst.Katalog.RuntimeVersion, + }) +} + // handleCRDDocs renders /controlcenter/docs/{katalog}/{crd}. func (cc *ControlCenter) handleCRDDocs(w http.ResponseWriter, r *http.Request, katalogName, crdName string) { inst, ok := cc.instanceByKatalogName(katalogName) diff --git a/cmd/controlcenter/cc/types.go b/cmd/controlcenter/cc/types.go index 662bacc7..5c824935 100644 --- a/cmd/controlcenter/cc/types.go +++ b/cmd/controlcenter/cc/types.go @@ -18,6 +18,8 @@ type KatalogSummary struct { Description string Version string Healthy bool + CreatedBy string + AppCount int TotalCRDs int HealthyCRDs int TotalWorkers int @@ -49,10 +51,12 @@ type IndexData struct { Katalogs []KatalogSummary TotalKatalogs int HealthyKatalogs int + TotalApps int TotalCRDs int TotalWorkers int TotalResources int AnyHealthy bool + HasOperatorKatalogs bool OrkestraURLs string EnableRuntimeManager bool CCVersion string @@ -83,21 +87,77 @@ type RBACRule struct { // KatalogResponse is the response from the /katalog endpoint type KatalogResponse struct { - Total int `json:"total"` - TotalEnabled int `json:"totalEnabled"` - Healthy bool `json:"healthy"` - Status int `json:"status"` - OrkReady bool `json:"OrkReady"` - DeletionProtection bool `json:"deletionProtection"` - CRDs []CRDSummary `json:"crds"` - Name string `json:"name,omitempty"` - Version string `json:"version,omitempty"` - Author string `json:"author,omitempty"` - Description string `json:"description,omitempty"` - DegradedReason string `json:"degradedReason,omitempty"` - StatusCounts StatusCounts `json:"statusCounts"` - License string `json:"license,omitempty"` - RuntimeVersion string `json:"runtimeVersion,omitempty"` + Total int `json:"total"` + TotalEnabled int `json:"totalEnabled"` + Healthy bool `json:"healthy"` + Status int `json:"status"` + OrkReady bool `json:"OrkReady"` + DeletionProtection bool `json:"deletionProtection"` + CRDs []CRDSummary `json:"crds"` + Name string `json:"name,omitempty"` + Version string `json:"version,omitempty"` + Author string `json:"author,omitempty"` + Description string `json:"description,omitempty"` + DegradedReason string `json:"degradedReason,omitempty"` + StatusCounts StatusCounts `json:"statusCounts"` + License string `json:"license,omitempty"` + RuntimeVersion string `json:"runtimeVersion,omitempty"` + CreatedBy string `json:"createdBy,omitempty"` + Projects map[string]ProjectInfoSummary `json:"projects,omitempty"` +} + +// ProjectInfoSummary is the CC-side view of one app in KatalogResponse.Projects. +// Fields mirror orktypes.ProjectInfo — add here when the runtime starts sending more. +type ProjectInfoSummary struct { + Name string `json:"name"` + Namespace string `json:"namespace"` + Port string `json:"port,omitempty"` + Language string `json:"language,omitempty"` + CurrentImage string `json:"currentImage,omitempty"` + GitCommit string `json:"gitCommit,omitempty"` + License string `json:"license,omitempty"` + HasDockerfile bool `json:"hasDockerfile,omitempty"` + HasFrontend bool `json:"hasFrontend,omitempty"` + HasSMTP bool `json:"hasSMTP,omitempty"` + HasSlack bool `json:"hasSlack,omitempty"` + HasCompose bool `json:"hasCompose,omitempty"` + SecretCount int `json:"secretCount,omitempty"` + ConfigCount int `json:"configCount,omitempty"` +} + +// DevAppsData is passed to the developer-view template. +type DevAppsData struct { + KatalogName string + Apps []DevAppSummary + CCVersion string + RuntimeVersion string +} + +// DevAppSummary holds display data for one app in the developer view. +type DevAppSummary struct { + Name string + Namespace string + Port string + Language string + CurrentImage string + ImageTag string + ServiceURL string + GitCommit string + License string + HasDockerfile bool + HasFrontend bool + HasSMTP bool + HasSlack bool + HasCompose bool + SecretCount int + ConfigCount int +} + +// DevAppDetailData is passed to the app detail template. +type DevAppDetailData struct { + KatalogName string + App DevAppSummary + RuntimeVersion string } // CRDSummary is a summary of a CRD diff --git a/docs/design-documents/one-katalog-developer-path.md b/docs/design-documents/one-katalog-developer-path.md new file mode 100644 index 00000000..0d2fa6d7 --- /dev/null +++ b/docs/design-documents/one-katalog-developer-path.md @@ -0,0 +1,440 @@ +# One Katalog — The Developer Path + +*Orkestra Project — May 2026* + +--- + +## The model + +One Katalog. One CRD entry (ConfigMap). One operatorBox. + +Each application contributes its resources — Deployment, Service, HPA, PDB, +ServiceAccount, Role, RoleBinding — as concrete entries inside the single +`onReconcile` block. Each app has its own ConfigMap CR in its own namespace. +The one CRD entry watches all registered app namespaces. + +``` +~/.orkestra/deploy/ + state.json ← deployed apps, images, namespaces, katalog hash + katalog.yaml ← one Katalog, one CRD, all app resources inline + +app/.orkestra/ + motif.yaml ← app's resource template (has {{ .metadata.* }} etc.) + app.yaml ← app's ConfigMap CR in app-ns + +frontend/.orkestra/ + motif.yaml ← frontend's template + app.yaml ← frontend's ConfigMap CR in frontend-ns +``` + +There is no `motifs/` directory. The central Katalog carries all resolved +resources directly in `onReconcile`. No imports. No file references. + +--- + +## Why inline — not imports + +Orkestra bundles the Katalog as a ConfigMap in the cluster. File `imports:` +are resolved at parse time on the host, not at runtime inside the cluster. +A Katalog that imports local paths cannot survive a restart because the +cluster-side runtime has no access to `~/.orkestra/`. Resources are therefore +resolved and embedded verbatim when `ork doctor deploy` writes the Katalog. + +--- + +## The central Katalog + +```yaml +# ~/.orkestra/deploy/katalog.yaml +apiVersion: orkestra.orkspace.io/v1 +kind: Katalog +metadata: + name: orkestra-developer + createdBy: orkdoctor + projects: + app: + language: python + port: "8080" + namespace: app-ns + currentImage: docker.io/myorg/app:abc123 + frontend: + language: node + port: "3000" + namespace: frontend-ns + currentImage: docker.io/myorg/frontend:def456 + +security: + deletionProtection: + enabled: true + +spec: + crds: + platform: + apiTypes: + kind: ConfigMap + labelSelector: + ork.io/platform: developer + allowedNamespaces: ["app-ns", "frontend-ns"] + + operatorBox: + onReconcile: + serviceAccounts: + - name: "app" + namespace: "app-ns" + reconcile: true + - name: "frontend" + namespace: "frontend-ns" + reconcile: true + + roles: + - name: "app" + namespace: "app-ns" + rules: + - apiGroups: [""] + resources: ["configmaps"] + resourceNames: ["app"] + verbs: ["get", "watch"] + reconcile: true + - name: "frontend" + namespace: "frontend-ns" + rules: + - apiGroups: [""] + resources: ["configmaps"] + resourceNames: ["frontend"] + verbs: ["get", "watch"] + reconcile: true + + roleBindings: + - name: "app" + namespace: "app-ns" + roleRef: "app" + subjects: + - kind: ServiceAccount + name: "app" + namespace: "app-ns" + reconcile: true + - name: "frontend" + namespace: "frontend-ns" + roleRef: "frontend" + subjects: + - kind: ServiceAccount + name: "frontend" + namespace: "frontend-ns" + reconcile: true + + deployments: + - name: "app" + namespace: "app-ns" + image: "docker.io/myorg/app:abc123" + resourceProfile: "burst" + port: "8080" + serviceAccountName: "app" + envFrom: + - secretRef: "app-secrets" + - configMapRef: "app-config" + reconcile: true + - name: "frontend" + namespace: "frontend-ns" + image: "docker.io/myorg/frontend:def456" + resourceProfile: "small" + port: "3000" + serviceAccountName: "frontend" + reconcile: true + + services: + - name: "app-svc" + namespace: "app-ns" + port: "8080" + reconcile: true + - name: "frontend-svc" + namespace: "frontend-ns" + port: "3000" + reconcile: true + + hpas: + - name: "app-hpa" + namespace: "app-ns" + scaleTargetRef: + name: "app" + minReplicas: "2" + maxReplicas: "10" + reconcile: true + - name: "frontend-hpa" + namespace: "frontend-ns" + scaleTargetRef: + name: "frontend" + minReplicas: "1" + maxReplicas: "5" + reconcile: true + + pdbs: + - name: "app-pdb" + namespace: "app-ns" + minAvailable: "1" + reconcile: true + - name: "frontend-pdb" + namespace: "frontend-ns" + minAvailable: "1" + reconcile: true +``` + +One CRD. One `onReconcile` block. Each app's resources are adjacent entries. +`allowedNamespaces` grows as apps are added. `metadata.projects` carries +per-app display data for the Control Center. + +--- + +## Each app has its own ConfigMap CR + +```yaml +# app/.orkestra/app.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: app + namespace: app-ns + labels: + ork.io/platform: developer # watched by the CRD entry +``` + +```yaml +# frontend/.orkestra/app.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: frontend + namespace: frontend-ns + labels: + ork.io/platform: developer +``` + +The ConfigMap is the trigger. When `ork doctor deploy` applies it, Orkestra +reconciles every resource in `onReconcile` whose name matches the ConfigMap's +`metadata.name`. Because `allowedNamespaces` scopes reconciliation, the `app` +ConfigMap only creates resources in `app-ns` and the `frontend` ConfigMap only +creates resources in `frontend-ns`. + +--- + +## How the reconciler works + +The one CRD entry watches all ConfigMaps labelled `ork.io/platform: developer` +across all `allowedNamespaces`. When the `app` ConfigMap is applied, the +reconciler fires for `app`. When the `frontend` ConfigMap is applied, the +reconciler fires for `frontend`. Each fires independently. + +Because all resources in `onReconcile` carry concrete values (no `{{ }}`), the +reconciler applies them directly. No template evaluation at runtime. The Katalog +is plain YAML. + +--- + +## Namespace management — outside the Katalog + +Namespaces are cluster-scoped. They cannot be owned by a namespaced +ConfigMap, so Kubernetes garbage collection never deletes them. They are +not inside the `onReconcile` block. + +`ork doctor deploy` creates namespaces directly with `kubectl`: + +```go +kubectl apply -f - <.port` and `projects..namespace`. +No API call needed — the data is in the Katalog response. + +`metadata.projects` is `map[string]ProjectInfo`. The fields written by +`ork doctor deploy` are: `name`, `language`, `port`, `namespace`, +`currentImage`. All are defined on `ProjectInfo` in `pkg/types`. + +**Route:** `/katalog/` → branches on `createdBy == "orkdoctor"` +→ renders `dev_apps.html` instead of the standard `katalog.html`. + +--- + +## --notify-me + +```bash +ork doctor init --notify-me +``` + +Adds a `notification:` block to the central Katalog using SMTP or Slack +credentials detected in `.env`. The developer's git `user.email` is the +default recipient. Notifications are a Katalog-level concern — not per-app. + +--- + +## What is not here + +- No Komposer. Deployment tracking uses `state.json` directly. +- No `motifs/` directory. Resolved resources are embedded in the Katalog. +- No status fields on the ConfigMap CR. Orkestra writes no status. +- No `{{ }}` in the written Katalog. All expressions are resolved before write. +- No custom CRD. The platform CRD is a standard Kubernetes ConfigMap. +- No imports in the Katalog. Import paths do not survive cluster-side restart. diff --git a/docs/design-documents/ork-doctor.md b/docs/design-documents/ork-doctor.md index 1ac22f8b..8b1c66fc 100644 --- a/docs/design-documents/ork-doctor.md +++ b/docs/design-documents/ork-doctor.md @@ -1,4 +1,4 @@ -# ork doctor + ork deploy — Developer Experience Design +# ork doctor + ork doctor deploy — Developer Experience Design *April 2026* @@ -40,7 +40,7 @@ Kubernetes deployment. ``` ork doctor → examine project, show what was found ork doctor init → generate .orkestra/katalog.yaml -ork deploy → build, push, apply bundle, deploy +ork doctor deploy → build, push, apply bundle, deploy ork open → open the app URL from status ``` @@ -50,7 +50,7 @@ Everything happens locally. The developer never leaves VSCode. ## The .env contract -The `.env` file is read **locally** during `ork deploy`. It is never baked +The `.env` file is read **locally** during `ork doctor deploy`. It is never baked into the image. It is never stored in the Katalog. It becomes Kubernetes resources (Secret and ConfigMap) when the bundle is generated — applied to the cluster once, managed by the operator thereafter. @@ -146,7 +146,7 @@ Generated .orkestra/app.yaml ← the ConfigMap the developer fills in Next steps: 1. Review .orkestra/katalog.yaml (edit freely) 2. Fill in .orkestra/app.yaml (replicas, host, etc.) - 3. Run 'ork deploy' + 3. Run 'ork doctor deploy' ``` ### .orkestra/katalog.yaml (generated) @@ -262,7 +262,7 @@ spec: ```yaml # This is the only Kubernetes object you manage. # Apply it once: kubectl apply -f .orkestra/app.yaml -# ork deploy updates the image field automatically. +# ork doctor deploy updates the image field automatically. apiVersion: v1 kind: ConfigMap @@ -277,7 +277,7 @@ data: minReplicas: "2" maxReplicas: "10" host: "" # fill this: myapp.example.com - image: "" # set by ork deploy — do not edit manually + image: "" # set by ork doctor deploy — do not edit manually ``` The developer sees no pod spec. No service account. No resource limits until @@ -285,19 +285,19 @@ they want them. Just the parameters of their app. --- -## ork deploy +## ork doctor deploy Builds the image, generates the full bundle, and applies everything to the cluster. The only command the developer runs after `ork doctor init`. ```bash -ork deploy --registry ghcr.io/myorg -ork deploy --registry ghcr.io/myorg --tag v1.2.0 # override tag (default: git commit) -ork deploy --registry ghcr.io/myorg --no-ha # skip HPA and PDB -ork deploy --registry ghcr.io/myorg --dry-run # show what would be applied +ork doctor deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg --tag v1.2.0 # override tag (default: git commit) +ork doctor deploy --registry ghcr.io/myorg --no-ha # skip HPA and PDB +ork doctor deploy --registry ghcr.io/myorg --dry-run # show what would be applied ``` -### What ork deploy does, in order +### What ork doctor deploy does, in order ``` 1. Build @@ -383,14 +383,14 @@ This is the step that makes the .env model safe. The `.env` file is read locally. The generated Secret file is applied to the cluster once. After that, the developer manages secrets by: -- Editing `.env` and re-running `ork deploy` (regenerates and re-applies the Secret) +- Editing `.env` and re-running `ork doctor deploy` (regenerates and re-applies the Secret) - Or editing the Kubernetes Secret directly for production changes The generated Secret is a standard Kubernetes Secret: ```yaml # .orkestra/bundle/app-secrets.yaml -# Generated by ork deploy — DO NOT COMMIT THIS FILE +# Generated by ork doctor deploy — DO NOT COMMIT THIS FILE # Add .orkestra/bundle/ to .gitignore apiVersion: v1 @@ -406,7 +406,7 @@ data: ``` **`.orkestra/bundle/` goes in `.gitignore`.** The generated secrets never -enter source control. `ork deploy` regenerates them from the local `.env` +enter source control. `ork doctor deploy` regenerates them from the local `.env` on every run. The `.gitignore` entry is added automatically by `ork doctor init`: @@ -425,7 +425,7 @@ contain no secrets, only structure and configuration values. ```bash ork doctor init --no-ha # generates katalog without HPA and PDB -ork deploy --no-ha # deploy flag (overrides what's in katalog) +ork doctor deploy --no-ha # deploy flag (overrides what's in katalog) ``` Without `--no-ha` (default): @@ -460,7 +460,7 @@ Reads from `ork status` on a 10-second poll. Clicking opens the Control Center. **4. Command palette** - `Orkestra: Initialize Project` → `ork doctor init` -- `Orkestra: Deploy` → `ork deploy` +- `Orkestra: Deploy` → `ork doctor deploy` - `Orkestra: Open App` → `ork open` - `Orkestra: Open Control Center` → `ork control start` @@ -503,7 +503,7 @@ They have HPA, PDB, Ingress, secrets management, and a live status view. ## v1 scope -Ships with `ork doctor` and `ork deploy`: +Ships with `ork doctor` and `ork doctor deploy`: - `.env` parsing with `# ork:cfg` tag - Language and port detection - Katalog and CR generation @@ -529,7 +529,7 @@ This closes the three-audience model: |---|---|---| | Platform engineers | Build operators declaratively | Katalog + operatorBox | | DevOps engineers | Compose multi-operator platforms | Komposer + Registry | -| Developers | Deploy to Kubernetes from VSCode | ork doctor + ork deploy | +| Developers | Deploy to Kubernetes from VSCode | ork doctor + ork doctor deploy | Kubernetes operators for everyone — including people who do not know what a Kubernetes operator is. \ No newline at end of file diff --git a/docs/design-documents/ork-doktor-expose.md b/docs/design-documents/ork-doktor-expose.md index 458d231e..324525cf 100644 --- a/docs/design-documents/ork-doktor-expose.md +++ b/docs/design-documents/ork-doktor-expose.md @@ -1,4 +1,4 @@ -# ork doctor + ork deploy --expose — Design Document +# ork doctor + ork doctor deploy --expose — Design Document *Orkestra Project — April 2026* @@ -11,7 +11,7 @@ This document covers two related features: 1. **`ork doctor` expansions** — notification detection, dependency auto-install, git/license metadata, kind cluster without requiring Go. -2. **`ork deploy --expose`** — instant public URL for local and dev clusters +2. **`ork doctor deploy --expose`** — instant public URL for local and dev clusters via a managed tunnel daemon. Both features serve the same goal: a developer with a Dockerfile and a `.env` @@ -148,7 +148,7 @@ Each installation is shown as a status line. no sudo required. Binaries go to `~/.orkestra/bin/`. The deploy commands add this directory to their child process PATH automatically. -**`kind`** is also a static binary. `ork deploy --dev` downloads it to +**`kind`** is also a static binary. `ork doctor deploy --dev` downloads it to `~/.orkestra/bin/kind`. **Go is not required.** The earlier design required `go install kind` — this is replaced with a direct binary download. Most developers who want a local cluster do not have Go installed. @@ -178,7 +178,7 @@ If not available and HPA is in the Katalog: **`ingress-nginx`** is installed when `host:` is set in `.orkestra/cr.yaml`. Already documented in the previous design — included here for completeness. -**Installation output** during `ork deploy`: +**Installation output** during `ork doctor deploy`: ``` Checking dependencies... @@ -191,10 +191,10 @@ Checking dependencies... ✓ Metrics server ready ``` -### 1.5 `ork deploy --dev` — kind cluster without Go +### 1.5 `ork doctor deploy --dev` — kind cluster without Go ```bash -ork deploy --dev --registry ghcr.io/myorg +ork doctor deploy --dev --registry ghcr.io/myorg ``` When `--dev` is specified: @@ -206,7 +206,7 @@ When `--dev` is specified: 5. Set kubectl context to `kind-orkestra-dev` 6. Continue with normal deploy flow -The kind cluster creation is one-time. Subsequent `ork deploy --dev` calls +The kind cluster creation is one-time. Subsequent `ork doctor deploy --dev` calls detect the existing cluster and skip creation. ``` @@ -219,11 +219,11 @@ from `https://github.com/kubernetes-sigs/kind/releases/` directly. --- -## Part 2: ork deploy --expose +## Part 2: ork doctor deploy --expose ### 2.1 Goal -After `ork deploy`, the application is running in the cluster. On a local kind +After `ork doctor deploy`, the application is running in the cluster. On a local kind cluster, it is only accessible via localhost port-forwarding. On a remote cluster with no public Ingress IP, the same problem exists. @@ -231,7 +231,7 @@ cluster with no public Ingress IP, the same problem exists. pointing at the application. The URL survives the deploy command's exit. ```bash -ork deploy --dev --expose +ork doctor deploy --dev --expose # ✓ App live at https://abc123.ngrok.io # ✓ Tunnel: running (ork tunnel stop to end) ``` @@ -250,7 +250,7 @@ what is installed: The developer can override with `--tunnel-provider`: ```bash -ork deploy --expose --tunnel-provider ngrok +ork doctor deploy --expose --tunnel-provider ngrok ``` **Cloudflare Tunnel (default):** @@ -269,13 +269,13 @@ Stable URL possible with paid account (out of scope for v1). ### 2.3 Tunnel as a background daemon -The tunnel must outlive the `ork deploy` command. It runs as a detached +The tunnel must outlive the `ork doctor deploy` command. It runs as a detached background process. **Daemon lifecycle:** ``` -ork deploy --expose +ork doctor deploy --expose ↓ Start tunnel daemon (detached process) Write PID + URL to ~/.orkestra/tunnel-state.json @@ -300,7 +300,7 @@ ork tunnel stop → kills daemon, removes state file } ``` -`ork deploy --expose` checks for an existing running daemon before starting +`ork doctor deploy --expose` checks for an existing running daemon before starting a new one: - If running and pointing at the same local port → print existing URL, skip start - If running but stale (PID dead) → clean up and start fresh @@ -314,18 +314,18 @@ The tunnel forwards to the ingress controller's local port. Detection order: 2. Port-forward if NodePort is not available: `kubectl port-forward -n ingress-nginx svc/ingress-nginx-controller 8080:80` → use 8080 3. Direct service port-forward if no ingress: `kubectl port-forward -n svc/-svc :` -For kind clusters, the NodePort is the most reliable path. `ork deploy --dev` +For kind clusters, the NodePort is the most reliable path. `ork doctor deploy --dev` creates the kind cluster with the ingress controller already configured to expose NodePort 80. ### 2.5 CLI commands -**`ork deploy --expose`** — start tunnel as part of deploy: +**`ork doctor deploy --expose`** — start tunnel as part of deploy: ```bash -ork deploy --registry ghcr.io/myorg --expose -ork deploy --dev --expose # kind + tunnel -ork deploy --dev --expose --tunnel-provider ngrok # explicit provider -ork deploy --dev --expose --tunnel-token $NGROK_TOKEN # non-interactive +ork doctor deploy --registry ghcr.io/myorg --expose +ork doctor deploy --dev --expose # kind + tunnel +ork doctor deploy --dev --expose --tunnel-provider ngrok # explicit provider +ork doctor deploy --dev --expose --tunnel-token $NGROK_TOKEN # non-interactive ``` **`ork tunnel status`** — show current tunnel state: @@ -478,7 +478,7 @@ developer → local to production, no Kubernetes required The developer pack is the only pack that assumes no Kubernetes knowledge. It is the entry point for the third Orkestra audience. Every example uses -`ork doctor`, `ork deploy`, and the ConfigMap-as-CRD pattern. No custom CRDs. +`ork doctor`, `ork doctor deploy`, and the ConfigMap-as-CRD pattern. No custom CRDs. No Go. No Helm charts written by the developer. --- @@ -501,7 +501,7 @@ New project # → generates .orkestra/cr.yaml Local deploy - ork deploy --dev --expose + ork doctor deploy --dev --expose # → downloads kind if needed, creates cluster # → builds image, deploys to kind cluster # → installs metrics-server, ingress-nginx automatically @@ -511,7 +511,7 @@ Local deploy Second project (same cluster) cd my-api/ ork doctor init - ork deploy --dev --expose + ork doctor deploy --dev --expose # → detects existing kind cluster, skips creation # → registers my-api in ~/.orkestra/deploy/komposer.yaml # → Orkestra picks up new CRD, no restart @@ -519,11 +519,11 @@ Second project (same cluster) Something goes wrong # Slack: "my-app: error rate 12% — reconcile failing" - ork deploy rollback + ork doctor deploy rollback # → previous image restored, rolling update, 2/2 pods ready Production deploy - ork deploy --registry ghcr.io/myorg + ork doctor deploy --registry ghcr.io/myorg # → same commands, same experience, real cluster ``` @@ -544,7 +544,7 @@ Production deploy 11. ngrok provider (2h) 12. Tunnel daemon + state file (3h) 13. `ork tunnel` subcommands (2h) -14. `ork deploy --expose` integration (2h) +14. `ork doctor deploy --expose` integration (2h) 15. Developer example pack (4h) Total: ~28h focused work. \ No newline at end of file diff --git a/docs/design-documents/ork-doktor-full.md b/docs/design-documents/ork-doktor-full.md index d122d656..4100f49a 100644 --- a/docs/design-documents/ork-doktor-full.md +++ b/docs/design-documents/ork-doktor-full.md @@ -12,7 +12,7 @@ layer, with honest phasing based on what can ship clean versus what needs its own release. - Part 1: Core `ork doctor` expansions (v1.1) -- Part 2: `ork deploy --expose` — public URL via tunnel daemon (v1.1) +- Part 2: `ork doctor deploy --expose` — public URL via tunnel daemon (v1.1) - Part 3: Cleanup — `cleanupOnShutdown` and `ork cleanup` (v1.1) - Part 4: RBAC scoped to the application namespace (v1.1) - Part 5: `--use-compose` — docker-compose as input (v1.2) @@ -120,7 +120,7 @@ ready. The 15-minute interval prevents spam when an issue persists. ### 1.4 Dependency auto-install -`ork doctor` and `ork deploy` check for required tools and install missing +`ork doctor` and `ork doctor deploy` check for required tools and install missing ones automatically. Every installation is a static binary download to `~/.orkestra/bin/` — no package manager, no sudo required. The deploy commands prepend `~/.orkestra/bin/` to their child process PATH. @@ -157,7 +157,7 @@ local cluster do not have Go installed. clusters, uses the kind-specific manifest. For all other clusters, uses the standard Helm chart. -**Installation output during `ork deploy`:** +**Installation output during `ork doctor deploy`:** ``` Checking dependencies... ✓ docker 27.1.0 @@ -180,7 +180,7 @@ controls in plain language, not Kubernetes vocabulary. ```yaml # app.yaml — your application configuration # Apply once: kubectl apply -f .orkestra/app.yaml -# ork deploy updates the image field automatically. +# ork doctor deploy updates the image field automatically. apiVersion: v1 kind: ConfigMap @@ -204,7 +204,7 @@ data: # Example: myapp.example.com host: "" - # Set by ork deploy — do not edit manually + # Set by ork doctor deploy — do not edit manually image: "" ``` @@ -259,10 +259,10 @@ This is separate from the Orkestra operator's own RBAC (ClusterRole, etc.). The application's service account can read only its own ConfigMap and Secret — nothing more, nothing outside its namespace. -### 1.7 ork deploy --dev — kind cluster +### 1.7 ork doctor deploy --dev — kind cluster ```bash -ork deploy --dev --registry ghcr.io/myorg +ork doctor deploy --dev --registry ghcr.io/myorg ``` Lifecycle: @@ -276,23 +276,23 @@ Lifecycle: ✓ Cluster ready: kind-orkestra-dev ``` -The cluster is created once. All subsequent `ork deploy --dev` calls detect +The cluster is created once. All subsequent `ork doctor deploy --dev` calls detect the existing cluster and skip creation. Multiple projects deploy to the same kind cluster via the global Komposer. --- -## Part 2: ork deploy --expose +## Part 2: ork doctor deploy --expose ### 2.1 Goal -After `ork deploy`, the application runs in the cluster. On a local kind +After `ork doctor deploy`, the application runs in the cluster. On a local kind cluster it is only accessible on localhost. `--expose` starts a background tunnel daemon that creates a public HTTPS URL. The URL survives the deploy command's exit and persists until explicitly stopped. ```bash -ork deploy --dev --expose +ork doctor deploy --dev --expose # ✓ App live at https://abc123.trycloudflare.com # Tunnel running — ork tunnel stop to end ``` @@ -311,14 +311,14 @@ three seconds. ngrok is the fallback when cloudflared is not available or explicitly requested. ```bash -ork deploy --expose # cloudflared by default -ork deploy --expose --tunnel-provider ngrok # explicit -ork deploy --expose --tunnel-token $NGROK_TOKEN # non-interactive CI +ork doctor deploy --expose # cloudflared by default +ork doctor deploy --expose --tunnel-provider ngrok # explicit +ork doctor deploy --expose --tunnel-token $NGROK_TOKEN # non-interactive CI ``` ### 2.3 Tunnel as a background daemon -The tunnel runs detached — it outlives the `ork deploy` command. +The tunnel runs detached — it outlives the `ork doctor deploy` command. **State file: `~/.orkestra/tunnel-state.json`** ```json @@ -331,7 +331,7 @@ The tunnel runs detached — it outlives the `ork deploy` command. } ``` -`ork deploy --expose` checks for an existing daemon before starting: +`ork doctor deploy --expose` checks for an existing daemon before starting: - Running, same port → print existing URL, skip start - Running but PID dead (stale) → clean up, start fresh - Not running → start new daemon @@ -516,7 +516,7 @@ deploys all stateless services as Deployments. ```bash ork doctor init --use-compose docker-compose.yaml -ork deploy --use-compose docker-compose.yaml --registry ghcr.io/myorg +ork doctor deploy --use-compose docker-compose.yaml --registry ghcr.io/myorg ``` The fast path (Dockerfile + `.env`) remains the default. `--use-compose` is @@ -740,7 +740,7 @@ When compose has multiple services, `app.yaml` grows to cover all of them: ``` The developer sees their entire stack's configuration in one file. They change -`postgresImage: "postgres:17"` and run `ork deploy` — Orkestra updates the +`postgresImage: "postgres:17"` and run `ork doctor deploy` — Orkestra updates the StatefulSet. --- @@ -807,7 +807,7 @@ Prepare → .gitignore updated (.orkestra/bundle/ added) Deploy locally - ork deploy --dev --expose + ork doctor deploy --dev --expose → kind binary downloaded (~/.orkestra/bin/kind) → kind-orkestra-dev cluster created → kubectl and helm downloaded if needed @@ -824,20 +824,20 @@ Share Something fails → Slack: "my-app: 2/2 pods not ready — CrashLoopBackOff" - ork deploy rollback + ork doctor deploy rollback → previous image restored, 2/2 pods ready Second project, same cluster cd my-api/ ork doctor init - ork deploy --dev --expose + ork doctor deploy --dev --expose → existing kind cluster detected, reused → registered in ~/.orkestra/deploy/komposer.yaml → Orkestra picks up new CRD without restart → https://xyz789.trycloudflare.com Production - ork deploy --registry ghcr.io/myorg + ork doctor deploy --registry ghcr.io/myorg → identical commands, real cluster Clean up @@ -857,7 +857,7 @@ ork doctor init --use-compose docker-compose.yaml --notify-me → generates katalog with StatefulSets for postgres and redis → generates app.yaml with postgresVolumeSize: "10Gi" -ork deploy --dev --expose +ork doctor deploy --dev --expose → all services deployed → pgAdmin + RedisInsight deployed and exposed @@ -884,7 +884,7 @@ Output: - Scoped RBAC for generated deployments - `cleanupOnShutdown` finalizer removal - `ork cleanup -f katalog.yaml` -- `ork deploy --expose` with cloudflared (default) and ngrok (fallback) +- `ork doctor deploy --expose` with cloudflared (default) and ngrok (fallback) - `ork tunnel status / stop / restart` - Developer example pack (5 examples) diff --git a/docs/design-documents/orkestra-motifs-architecture.md b/docs/design-documents/orkestra-motifs-architecture.md index a9075cbd..3a9f1ff5 100644 --- a/docs/design-documents/orkestra-motifs-architecture.md +++ b/docs/design-documents/orkestra-motifs-architecture.md @@ -171,7 +171,7 @@ data: ``` The developer changes `postgresVolumeSize: "20Gi"` before first deploy. They -run `ork deploy`. Postgres is running. pgAdmin is accessible. They never wrote +run `ork doctor deploy`. Postgres is running. pgAdmin is accessible. They never wrote a StatefulSet. **Application of resources:** Direct `kubectl apply`. No Orkestra operator @@ -358,7 +358,7 @@ requirements). ork doctor designs the Katalog, creates the app.yaml interface, and manages the deployment. The developer is inside the operator pattern without knowing it. The ConfigMap -is their CR. app.yaml is their CR spec. `ork deploy` is their `kubectl apply`. +is their CR. app.yaml is their CR spec. `ork doctor deploy` is their `kubectl apply`. The Control Center is their operator dashboard. The pattern is identical. Only the vocabulary changes. diff --git a/docs/design-documents/registry-vs-motifs.md b/docs/design-documents/registry-vs-motifs.md index 871ac666..80edeab6 100644 --- a/docs/design-documents/registry-vs-motifs.md +++ b/docs/design-documents/registry-vs-motifs.md @@ -11,7 +11,7 @@ | **Unit** | Operator pattern (Katalog) | Infrastructure deployment (StatefulSet + Service) | | **Audience** | Platform engineers | Developers | | **Consumer knows** | CRDs, operators, Kubernetes | Docker, docker-compose | -| **Mechanism** | Komposer sources → `ork registry pull` | `ork deploy --use-compose` | +| **Mechanism** | Komposer sources → `ork registry pull` | `ork doctor deploy --use-compose` | | **Complexity** | Embraced | Hidden | | **CRD required** | Yes | No | | **Reconciliation** | Yes — Orkestra manages lifecycle | No — applied once, Kubernetes manages | @@ -66,7 +66,7 @@ ork doctor init --use-compose docker-compose.yaml # imports postgres manifest from orkestra-motifs # adds postgresImage + postgresVolumeSize to app.yaml -ork deploy --dev --expose +ork doctor deploy --dev --expose # postgres StatefulSet applied # pgAdmin deployed # both URLs printed @@ -104,7 +104,7 @@ understanding the operatorbox model, CRD lifecycle, and Orkestra's declarative layer. The motifs repository operates through direct application. A developer runs -`ork deploy` and the StatefulSet is applied with `kubectl apply`. Kubernetes +`ork doctor deploy` and the StatefulSet is applied with `kubectl apply`. Kubernetes manages it from that point. No Orkestra reconciliation. No finalizers. No custom CRD. Just a postgres pod running in a namespace. @@ -180,7 +180,7 @@ Orkestra reconciles the PostgresCluster CR and manages the full lifecycle. # password auto-generated — see my-app-secrets in cluster ``` -The developer changes the image version or volume size. `ork deploy` applies +The developer changes the image version or volume size. `ork doctor deploy` applies the change. No CR. No operator. No reconciliation loop. --- diff --git a/docs/profiles/__index.md b/docs/profiles/__index.md new file mode 100644 index 00000000..850ec0db --- /dev/null +++ b/docs/profiles/__index.md @@ -0,0 +1,124 @@ +# Profiles + +Profiles are named presets that expand into a fully-formed configuration at Katalog load time. + +You declare a profile name. Orkestra resolves it into the concrete values — CPU limits, worker counts, probe timings — before the runtime starts. By the time a reconcile loop runs, there is no profile. There is only a fully-expanded spec, exactly as if you had written it by hand. + +--- + +## Why profiles exist + +Writing raw Kubernetes configuration is correct but carries no intent. + +```yaml +# What does this tell you? +resources: + requests: + cpu: 200m + memory: 256Mi + limits: + cpu: 2 + memory: 2Gi +``` + +A profile captures the **reason** the numbers are what they are. + +```yaml +resources: + profile: burst +``` + +`burst` tells you — and the operator — that this workload handles sudden spikes. The numbers follow from that decision, not the other way around. + +The same logic applies to autoscaler behavior and probe timing. Profiles encode intent. Intent survives change. + +--- + +## How profiles work + +Every profile family follows the same pattern: + +1. **Declare** — write a profile name in the Katalog +2. **Validate** — Orkestra checks the name at load time; unknown profiles fail fast +3. **Expand** — Orkestra replaces the profile name with the full configuration +4. **Run** — the runtime sees the expanded spec; the profile name is gone + +Profiles can be static or dynamic: + +```yaml +# Static — the profile is always "steady" +resources: + profile: steady + +# Dynamic — resolved from the CR at reconcile time +resources: + profile: "{{ .spec.resourceProfile | default \"standard\" }}" +``` + +Both are valid. Template expressions are validated at runtime. Static names are validated at load time. + +--- + +## The three profile families + +### Resource profiles +*What CPU and memory this workload gets.* + +Named presets for Kubernetes `resources.requests` and `resources.limits`. +Applied to any Deployment, StatefulSet, ReplicaSet, or Pod. + +```yaml +resources: + profile: small +``` + +→ [Resource Profile](./resource-profile.md) + +--- + +### Autoscale profiles +*How this operator scales its own workers and queue.* + +Named presets for `operatorBox.autoscale` — the operator's internal autoscaler. +Expand relative to the operator's declared baseline. + +```yaml +autoscale: + profile: latency-sensitive +``` + +→ [Autoscale Profile](./autoscale-profile.md) + +--- + +### Probe profiles +*How long Kubernetes waits before acting on probe results.* + +Named presets for startup, liveness, and readiness probe timing. +Applied to any Deployment, StatefulSet, ReplicaSet, or Pod. + +```yaml +probes: + startup: + type: tcp + profile: slow-start + liveness: + type: http + path: /health + profile: standard +``` + +→ [Probe Profile](./probe-profile.md) + +--- + +## Rules that apply to every profile + +- **Atomic** — a profile fully defines its configuration. You cannot combine a profile with manual fields of the same type. +- **Fail-fast** — an unknown profile name is a Katalog load error, not a runtime error. +- **No mixing** — a resource profile and manual `resources:` fields cannot coexist on the same resource. +- **Template-safe** — profile names can be template expressions. Static names are validated immediately. Template expressions are validated when the CR is reconciled. + +--- + +**Next →** [Resource Profile](./resource-profile.md) diff --git a/docs/profiles/autoscale-profile.md b/docs/profiles/autoscale-profile.md new file mode 100644 index 00000000..d60f2dcb --- /dev/null +++ b/docs/profiles/autoscale-profile.md @@ -0,0 +1,168 @@ +# Autoscale Profile +*Operator scaling presets — workers, queues, and conditions.* + +An autoscale profile is a named preset that expands into a complete `operatorBox.autoscale` block at Katalog load time. + +Autoscale profiles are relative. They use the CRD's declared `workers` and `queue.maxQueueDepth` as a **baseline** and derive thresholds, overrides, and timing from it. The same profile behaves differently for a low-throughput operator with 2 workers than for a high-throughput operator with 20. + +--- + +## Profiles + +| Profile | Trigger | Workers Override | Queue Override | Interval | Cooldown | +|---|---|---|---|---|---| +| `burst` | queueDepth > baseline × 3 | baseline × 4 | baseline × 10 | 5s | 30s | +| `steady` | queueDepth > baseline × 1.5 AND workers busy > 70% | baseline × 2 | baseline × 3 | 30s | 2m | +| `batch` | cron window 23:00 → 02:00 | baseline × 3 | baseline × 8 | 60s | 5m | +| `latency-sensitive` | P95 reconcile > 200ms | ⌈baseline × 2.5⌉ | — | 15s | 1m | +| `cost-optimized` | workers idle > 60% | max(1, baseline × 0.5) | baseline × 0.5 | 30s | 10m | + +--- + +## Usage + +Set `profile` inside the `autoscale:` block under `operatorBox:`: + +```yaml +operatorBox: + workers: 4 + queue: + maxQueueDepth: 100 + autoscale: + profile: steady +``` + +The profile expands using `workers: 4` and `maxQueueDepth: 100` as the baseline. + +For `steady`, that produces: + +- Trigger: queueDepth > 150 AND workersBusyPercent > 70 +- Override: workers → 8, queueDepth → 300 +- Interval: 30s, Cooldown: 2m + +--- + +## Rules + +**Profile or explicit — not both.** +A `profile:` cannot coexist with manual `autoscale` fields (`interval:`, `cooldown:`, `conditions:`, `do:`) on the same CRD. Use one or the other. + +```yaml +# Valid — profile only +autoscale: + profile: burst + +# Valid — explicit only +autoscale: + interval: 10s + cooldown: 1m + conditions: + when: + - field: metrics.queueDepth + greaterThan: "500" + do: + workers: 16 + +# Invalid — profile and explicit together +autoscale: + profile: burst + interval: 10s # error: cannot mix profile and manual autoscale fields +``` + +**Unknown profiles fail fast.** +An unrecognized profile name is a Katalog load error. + +--- + +## Profile details + +### `burst` +*React instantly to spikes.* + +Short intervals, aggressive overrides. Intended for operators that see sudden flood events — mass ingestion, fan-out operations, event storms. + +``` +trigger: queueDepth > workers × 3 +override: workers × 4, queueDepth × 10 +timing: interval 5s, cooldown 30s +``` + +Reverts quickly once the queue drains. Use when bursts are short-lived. + +--- + +### `steady` +*Smooth, predictable scaling.* + +Two-condition trigger prevents scaling on noise — both queue depth and worker saturation must rise together. Moderate overrides. Long cooldown. + +``` +trigger: queueDepth > baseline × 1.5 AND workersBusyPercent > 70 +override: workers × 2, queueDepth × 3 +timing: interval 30s, cooldown 2m +``` + +Good default for operators that serve consistent API load. + +--- + +### `batch` +*Scale for a nightly processing window.* + +Time-triggered via cron. Activates at 23:00, stays active for 3 hours, then reverts. No metric conditions. + +``` +trigger: cron "0 23 * * *", duration 3h +override: workers × 3, queueDepth × 8 +timing: interval 60s, cooldown 5m +``` + +Use for ETL operators, nightly report generators, scheduled cleanup jobs. + +--- + +### `latency-sensitive` +*Keep reconcile latency low.* + +Triggers on P95 reconcile duration — not queue depth. Adds workers before the queue even builds. Only modifies worker count, not queue. + +``` +trigger: reconcileDurationP95Ms > 200 +override: workers × 2.5 (ceiling) +timing: interval 15s, cooldown 1m +``` + +Use for operators where response time matters more than throughput — admission controllers, cert rotators, DNS operators. + +--- + +### `cost-optimized` +*Minimize resource usage during low activity.* + +Inverted logic — triggers when workers are mostly idle. Reduces both workers and queue depth. Long cooldown prevents flapping. + +``` +trigger: workersIdlePercent > 60 +override: max(1, workers × 0.5), queueDepth × 0.5 +timing: interval 30s, cooldown 10m +``` + +Use for operators that see highly variable load and you want to conserve resources during quiet periods. + +--- + +## Choosing a profile + +Ask these questions: + +1. **Does this operator see sudden spikes?** → `burst` +2. **Does this operator run a scheduled nightly job?** → `batch` +3. **Does reconcile latency matter more than throughput?** → `latency-sensitive` +4. **Is the load consistent and predictable?** → `steady` +5. **Is the load low and I want to minimize footprint?** → `cost-optimized` + +If none fit cleanly, write the autoscale block manually. Profiles are shortcuts, not constraints. + +--- + +**Next →** [Probe Profile](./probe-profile.md) diff --git a/docs/profiles/probe-profile.md b/docs/profiles/probe-profile.md new file mode 100644 index 00000000..2a181507 --- /dev/null +++ b/docs/profiles/probe-profile.md @@ -0,0 +1,253 @@ +# Probe Profile +*Health check timing presets — how long Kubernetes waits.* + +A probe profile is a named preset for the timing parameters of a Kubernetes health probe: `initialDelaySeconds`, `periodSeconds`, `failureThreshold`, `successThreshold`, and `timeoutSeconds`. + +Probes have two concerns: **what to check** (HTTP path or TCP port) and **when to give up** (timing). A probe profile handles the second one so you only have to declare the first. + +--- + +## Profiles + +| Profile | initialDelay | period | failureThreshold | successThreshold | timeout | Window | +|---|---|---|---|---|---|---| +| `fast` | 5s | 10s | 2 | 1 | 5s | ~25s max | +| `standard` | 15s | 20s | 3 | 1 | 10s | ~75s max | +| `patient` | 30s | 30s | 5 | 1 | 10s | ~180s max | +| `slow-start` | 0s | 10s | 30 | 1 | 10s | 300s max | + +**Window** is the maximum time before Kubernetes declares the probe failed and restarts or stops routing traffic to the container. + +--- + +## Probe types + +Probe profiles work with both probe types: + +### HTTP GET +Sends an HTTP GET to the declared path. Succeeds on 2xx–3xx responses. + +```yaml +probes: + liveness: + type: http + path: /health + profile: standard +``` + +### TCP socket +Opens a TCP connection to the container's port. Succeeds if the port accepts the connection. + +```yaml +probes: + liveness: + type: tcp + profile: standard +``` + +When `type` is omitted and `path` is set, HTTP is assumed. + +--- + +## Usage + +Set `probes:` on any Deployment, StatefulSet, ReplicaSet, or Pod: + +```yaml +onCreate: + deployments: + - name: "{{ .metadata.name }}-api" + image: "{{ .spec.image }}" + port: "8080" + probes: + startup: + type: http + path: /health + profile: slow-start + liveness: + type: http + path: /health + profile: standard + readiness: + type: http + path: /ready + profile: standard +``` + +For databases and other TCP services: + +```yaml +probes: + startup: + type: tcp + profile: slow-start + liveness: + type: tcp + profile: standard + readiness: + type: tcp + profile: standard +``` + +--- + +## Rules + +**Profile or explicit — not both.** +A probe profile cannot coexist with explicit timing fields (`initialDelaySeconds`, `periodSeconds`, `failureThreshold`, `successThreshold`, `timeoutSeconds`) on the same probe. Use one or the other. + +```yaml +# Valid — profile only +liveness: + type: http + path: /health + profile: standard + +# Valid — explicit only +liveness: + type: http + path: /health + initialDelaySeconds: 15 + periodSeconds: 20 + failureThreshold: 3 + +# Invalid — profile and explicit together +liveness: + type: http + path: /health + profile: standard + initialDelaySeconds: 5 # error: cannot mix profile and explicit timing +``` + +**Unknown profiles fail fast.** +An unrecognized profile name is a Katalog load error. + +**Template expressions are allowed.** +Profile names can be template expressions: + +```yaml +profile: '{{ .spec.probeProfile | default "standard" }}' +``` + +Static names are validated at load time. Template expressions are validated at reconcile time. + +**Port defaults to the container's declared port.** +If the probe does not specify `port:`, it uses the container's `port:` field. Override with `port:` on the probe when needed. + +--- + +## Profile details + +### `fast` +*Quick detection for services that start instantly.* + +Starts checking after 5 seconds, checks every 10 seconds, fails after 2 missed checks. Use for stateless HTTP services where startup is fast and problems should be caught immediately. + +``` +initialDelaySeconds: 5 +periodSeconds: 10 +failureThreshold: 2 +timeout: 5s +``` + +--- + +### `standard` +*Balanced defaults for most services.* + +Starts checking after 15 seconds, checks every 20 seconds, fails after 3 missed checks. This is the right default if you have no specific information about the workload. + +``` +initialDelaySeconds: 15 +periodSeconds: 20 +failureThreshold: 3 +timeout: 10s +``` + +--- + +### `patient` +*Tolerant of slower operations.* + +Starts checking after 30 seconds, checks every 30 seconds, fails after 5 missed checks — a total window of 180 seconds after initial delay. Use for batch workers, services with non-trivial initialization, or services that do expensive startup work. + +``` +initialDelaySeconds: 30 +periodSeconds: 30 +failureThreshold: 5 +timeout: 10s +``` + +--- + +### `slow-start` +*5-minute window for heavy startup.* + +Starts checking immediately (no initial delay), checks every 10 seconds, allows 30 consecutive failures before giving up — a 300-second (5-minute) tolerance window. + +``` +initialDelaySeconds: 0 +periodSeconds: 10 +failureThreshold: 30 +timeout: 10s +``` + +Designed for **startup probes** on services with slow initialization: databases loading large datasets, JVM services with slow class loading, Kafka brokers completing leader election after a restart. + +Once the startup probe passes, Kubernetes hands control to liveness and readiness probes. + +--- + +## Startup vs liveness vs readiness + +| Probe | Purpose | Failure action | +|---|---|---| +| `startup` | Is the container done initializing? | Restart | +| `liveness` | Is the container still alive? | Restart | +| `readiness` | Should this container receive traffic? | Remove from Service endpoints | + +**A typical pattern for a database:** + +```yaml +probes: + startup: + type: tcp + profile: slow-start # generous window for first boot + liveness: + type: tcp + profile: standard # restart if frozen + readiness: + type: tcp + profile: standard # stop routing if not ready +``` + +**A typical pattern for an HTTP API:** + +```yaml +probes: + startup: + type: http + path: /health + profile: patient # time for app startup + liveness: + type: http + path: /health + profile: standard # restart if health degrades + readiness: + type: http + path: /ready # separate ready check + profile: fast # pull traffic fast when ready +``` + +--- + +## Choosing a profile + +| Question | Profile | +|---|---| +| Does startup finish in under 10 seconds? | `fast` | +| Standard web service with normal startup? | `standard` | +| Does startup take up to 2-3 minutes? | `patient` | +| Database, JVM, or Kafka? Startup might need 5 minutes? | `slow-start` | + +Use `slow-start` only for startup probes. Use `standard` or `patient` for liveness and readiness — a slow liveness probe means problems are detected slowly. diff --git a/docs/profiles/resource-profile.md b/docs/profiles/resource-profile.md new file mode 100644 index 00000000..12cd4326 --- /dev/null +++ b/docs/profiles/resource-profile.md @@ -0,0 +1,101 @@ +# Resource Profile +*CPU and memory presets for workloads.* + +A resource profile is a named preset that expands into a complete Kubernetes `resources` block — requests and limits — at Katalog load time. + +You write a name. Orkestra writes the numbers. + +--- + +## Profiles + +| Profile | CPU Request | CPU Limit | Memory Request | Memory Limit | Use Case | +|---|---|---|---|---|---| +| `tiny` | 25m | 100m | 64Mi | 128Mi | Sidecars, health endpoints, minimal utilities | +| `small` | 100m | 500m | 128Mi | 512Mi | Standard microservices | +| `medium` | 250m | 1 | 256Mi | 1Gi | Production web services | +| `large` | 500m | 2 | 512Mi | 2Gi | High-traffic or heavier workloads | +| `burst` | 200m | 2 | 256Mi | 2Gi | Services with sudden spikes; low request, high limit | +| `steady` | 300m | 600m | 256Mi | 512Mi | Predictable, stable workloads | +| `compute-heavy` | 1 | 2 | 512Mi | 1Gi | CPU-bound work — builds, ML inference, data pipelines | +| `memory-heavy` | 250m | 500m | 1Gi | 2Gi | Memory-bound work — JVMs, large caches, analytics | + +--- + +## Usage + +Set `resources.profile` on any Deployment, StatefulSet, ReplicaSet, or Pod: + +```yaml +onCreate: + deployments: + - name: "{{ .metadata.name }}-api" + image: "{{ .spec.image }}" + resources: + profile: small +``` + +Or dynamically from the CR: + +```yaml +resources: + profile: '{{ .spec.resourceProfile | default "small" }}' +``` + +--- + +## Rules + +**Profile or explicit — not both.** +`resources.profile` cannot coexist with `resources.requests` or `resources.limits` on the same resource. If both are present, Orkestra rejects the Katalog at load time. + +```yaml +# Valid — profile only +resources: + profile: burst + +# Valid — explicit only +resources: + requests: + cpu: 500m + memory: 512Mi + limits: + cpu: 2 + memory: 2Gi + +# Invalid — profile and explicit together +resources: + profile: burst + requests: + cpu: 500m # error: cannot mix profile and explicit fields +``` + +**Unknown profiles fail fast.** +A typo in a profile name (`buurst`, `Large`) is a Katalog load error. You will see the error before the operator starts. + +**Template expressions are allowed.** +When `resourceProfile` is a template expression, the profile name is resolved at reconcile time and validated then. Unknown names at runtime cause a reconcile failure on that CR — other CRs are not affected. + +--- + +## When to use each profile + +**tiny** — only when you genuinely need minimal overhead. A health check sidecar. A token rotator that runs once per hour. + +**small** — your default for anything that does not have unusual resource behavior. Start here. + +**medium** — when `small` limits are hit in practice. Most production web services. + +**large** — services with consistently high load. Not a catch-all for uncertainty. + +**burst** — when your service is mostly idle but needs to absorb sudden spikes without being throttled. The wide gap between requests and limits is intentional. + +**steady** — when burst is overkill but `small` feels too tight. Predictable workloads where you want the limit to be close to the request. + +**compute-heavy** — batch jobs, build pipelines, ML inference, anything that maxes out CPU cores. Memory stays low. + +**memory-heavy** — JVM services, large in-process caches, analytics engines. CPU stays moderate; memory is generous. + +--- + +**Next →** [Autoscale Profile](./autoscale-profile.md) diff --git a/docs/publications/look-prepare-go.md b/docs/publications/look-prepare-go.md index f9a22fa1..ebd4a876 100644 --- a/docs/publications/look-prepare-go.md +++ b/docs/publications/look-prepare-go.md @@ -18,7 +18,7 @@ move the Kubernetes knowledge requirement rather than removing it. Orkestra eliminates it. A developer who has a Dockerfile and a `.env` already has everything Orkestra needs to produce a production-grade Kubernetes -deployment. Three commands — `ork doctor`, `ork doctor init`, `ork deploy` — +deployment. Three commands — `ork doctor`, `ork doctor init`, `ork doctor deploy` — convert that description into a running deployment with autoscaling, pod disruption budgets, ingress routing, secrets management, and live observability. The developer writes no Kubernetes YAML. The developer learns no Kubernetes @@ -112,7 +112,7 @@ resources. The Katalog is correct by default; `app.yaml` is the only file the developer needs to read and possibly edit. It contains no Kubernetes primitives. It contains only application parameters. -**Go** — `ork deploy` builds the Docker image tagged with the current commit +**Go** — `ork doctor deploy` builds the Docker image tagged with the current commit SHA, pushes it to the specified registry, generates the full deployment bundle including RBAC and a Kubernetes Secret from the `.env` file's non-config variables, applies everything to the cluster, and waits for the rollout to @@ -162,7 +162,7 @@ generate step on every deployment. ## 5. Production grade by default -The deployment produced by `ork deploy` is not a minimal viable deployment +The deployment produced by `ork doctor deploy` is not a minimal viable deployment that the developer will need to enhance later. It is production-grade from the first run. @@ -188,7 +188,7 @@ The developer never encounters "IngressClass not found" or "No address for ingress" — these errors exist below the abstraction layer. **Observability** is available from the first deployment. The Control Center -is accessible immediately after deploy — `ork deploy` prints the port-forward +is accessible immediately after deploy — `ork doctor deploy` prints the port-forward command when no external hostname is configured: ``` @@ -202,8 +202,8 @@ selects their CR, and sees every resource Orkestra created, its current state, and the timeline of events that brought it there. `kubectl logs` works normally alongside this view. -**Rollback** is a single command. `ork deploy rollback` restores the previous -image. `ork deploy rollback --image ` restores any specific image. +**Rollback** is a single command. `ork doctor deploy rollback` restores the previous +image. `ork doctor deploy rollback --image ` restores any specific image. The state tracking in `~/.orkestra/deploy/state.json` maintains the previous image reference across deploy runs. The rollback patches the ConfigMap, which Orkestra reconciles into a new rolling update. The developer does not need to @@ -256,14 +256,14 @@ This has a practical consequence: operators Orkestra manages for platform engineers and operators generated by `ork doctor init` for developers are the same kind of thing managed by the same runtime with the same observability and the same failure model. A platform team that adopts Orkestra for their own -operator development and a developer who uses `ork deploy` are both users of +operator development and a developer who uses `ork doctor deploy` are both users of the same system, with the same guarantees, visible in the same Control Center. --- ## 8. What the developer does not learn -The developer who uses `ork doctor init` and `ork deploy` does not learn: +The developer who uses `ork doctor init` and `ork doctor deploy` does not learn: - What a pod spec is or how to write one - The difference between a ClusterIP, NodePort, and LoadBalancer service @@ -295,7 +295,7 @@ The abstraction is additive, not opaque. Kubernetes operators for everyone has always been Orkestra's stated goal. The operator runtime, the declarative layer, and the provider ecosystem address that goal for platform engineers and DevOps practitioners. `ork doctor` and -`ork deploy` address it for the developer who has never heard the word operator +`ork doctor deploy` address it for the developer who has never heard the word operator and does not need to. The three commands — look, prepare, go — are not a simplification of diff --git a/docs/reference/cli/developer/__index.md b/docs/reference/cli/developer/__index.md index bda5af0c..6391b7d2 100644 --- a/docs/reference/cli/developer/__index.md +++ b/docs/reference/cli/developer/__index.md @@ -9,8 +9,8 @@ Three commands cover the entire lifecycle: | Command | What it does | |---------|-------------| | [`ork doctor`](./doctor.md) | Examine the project, show what Orkestra detected, and generate the `.orkestra/` configuration | -| [`ork deploy`](./deploy.md) | Build the Docker image, push it, generate the cluster bundle, install Orkestra, and roll out | -| [`ork deploy rollback`](./rollback.md) | Instantly restore the previous image — no rebuild required | +| [`ork doctor deploy`](./deploy.md) | Build the Docker image, push it, generate the cluster bundle, install Orkestra, and roll out | +| [`ork doctor deploy rollback`](./rollback.md) | Instantly restore the previous image — no rebuild required | --- @@ -24,11 +24,11 @@ ork doctor ← understand what Orkestra sees ork doctor init --name my-app ← generate .orkestra/ config │ ▼ -ork deploy --registry ghcr.io/org ← build → push → deploy → watch +ork doctor deploy --registry ghcr.io/org ← build → push → deploy → watch │ ├─ deploy succeeds ──────────────────────────► done │ - └─ replicas not ready ──► ork deploy rollback ← instant restore + └─ replicas not ready ──► ork doctor deploy rollback ← instant restore ``` --- @@ -53,8 +53,8 @@ Every deployment generated by `ork doctor init` includes: | Tool | Purpose | Auto-installed? | |------|---------|-----------------| | Docker | Image build and push | No — install manually | -| kubectl | Apply manifests, watch rollout | Yes — `ork deploy` installs if missing | -| helm | Install the Orkestra operator | Yes — `ork deploy` installs if missing | +| kubectl | Apply manifests, watch rollout | Yes — `ork doctor deploy` installs if missing | +| helm | Install the Orkestra operator | Yes — `ork doctor deploy` installs if missing | | A container registry | Store images | Required — pass via `--registry` | For local development without a registry, use `--dev` to spin up a diff --git a/docs/reference/cli/developer/doktor.md b/docs/reference/cli/developer/doktor.md index fa70ade1..fbee3fea 100644 --- a/docs/reference/cli/developer/doktor.md +++ b/docs/reference/cli/developer/doktor.md @@ -30,7 +30,7 @@ ork doctor | `.env` variables | Parsed from `.env`; lines tagged `# ork:cfg` become ConfigMap entries, all others become Secrets | | Frontend detection | `build/`, `dist/`, or `public/` directories; or `package.json` with React, Vue, Angular, Next, Nuxt, or Svelte | | SMTP / Slack | Prefixes `SMTP_` or `SLACK_` in `.env` — triggers a `--notify-me` hint | -| Missing tools | `kubectl` and `helm` availability — both are auto-installed by `ork deploy` | +| Missing tools | `kubectl` and `helm` availability — both are auto-installed by `ork doctor deploy` | ### Flags @@ -162,7 +162,7 @@ data: maxReplicas: "10" host: "" # public hostname for Ingress (leave empty if not needed) controlCenterHost: "" # Orkestra Control Center hostname - image: "" # set automatically by ork deploy — do not edit + image: "" # set automatically by ork doctor deploy — do not edit ``` --- @@ -173,8 +173,8 @@ After `ork doctor init`: 1. Review `.orkestra/katalog.yaml` — it is generated but editable 2. Fill in `.orkestra/app.yaml` — replicas, host, controlCenterHost -3. Run [`ork deploy`](./deploy.md) to build, push, and deploy +3. Run [`ork doctor deploy`](./deploy.md) to build, push, and deploy --- -**← CLI Reference** [index](../index.md) | **Next →** [ork deploy](./deploy.md) +**← CLI Reference** [index](../index.md) | **Next →** [ork doctor deploy](./deploy.md) diff --git a/docs/reference/cli/developer/rollback.md b/docs/reference/cli/developer/rollback.md index 4eb24fe9..cb5eefb1 100644 --- a/docs/reference/cli/developer/rollback.md +++ b/docs/reference/cli/developer/rollback.md @@ -1,10 +1,10 @@ -# ork deploy rollback +# ork doctor deploy rollback Instantly restore the previous deployed image by patching the ConfigMap CR. No Docker build, no push, no bundle regeneration. ```bash -ork deploy rollback [app-name] [flags] +ork doctor deploy rollback [app-name] [flags] ``` --- @@ -22,7 +22,7 @@ ork deploy rollback [app-name] [flags] ### Roll back to the previous image ```bash -ork deploy rollback +ork doctor deploy rollback ``` Reads the previous image from `~/.orkestra/deploy/state.json`, patches the @@ -31,13 +31,13 @@ ConfigMap CR, and watches the rollout. ### Roll back a specific app from outside its directory ```bash -ork deploy rollback my-api +ork doctor deploy rollback my-api ``` ### Roll back to a specific image ```bash -ork deploy rollback --image ghcr.io/myorg/my-api:d1e2f30 +ork doctor deploy rollback --image ghcr.io/myorg/my-api:d1e2f30 ``` Bypasses all state lookups and patches directly to the given image. @@ -62,7 +62,7 @@ no previous image found for my-api — use --image to specify ## State swap Before patching the cluster, rollback swaps `currentImage` and `previousImage` in -state.json. This means a second `ork deploy rollback` immediately after the first will +state.json. This means a second `ork doctor deploy rollback` immediately after the first will re-roll-forward — each rollback is reversible. The annotation is updated with the same swap logic so both sources stay consistent. @@ -71,7 +71,7 @@ The annotation is updated with the same swap logic so both sources stay consiste ## Watch behaviour -After patching, rollback watches the rollout with the same logic as `ork deploy`: +After patching, rollback watches the rollout with the same logic as `ork doctor deploy`: ```bash kubectl rollout status deployment/ -n --timeout=5m @@ -87,19 +87,19 @@ previous image just failed). | Situation | Recommended action | |-----------|-------------------| -| Replicas stuck in `Deploying` for more than a few minutes | `ork deploy rollback` | -| Pod crash loop after a deploy | `ork deploy rollback` | -| Orkestra sends a deployment-not-ready notification | `ork deploy rollback` | -| Bad config pushed with the image | Fix `.env` or `app.yaml`, then `ork deploy` | +| Replicas stuck in `Deploying` for more than a few minutes | `ork doctor deploy rollback` | +| Pod crash loop after a deploy | `ork doctor deploy rollback` | +| Orkestra sends a deployment-not-ready notification | `ork doctor deploy rollback` | +| Bad config pushed with the image | Fix `.env` or `app.yaml`, then `ork doctor deploy` | | First deploy that has never succeeded | Fix the Dockerfile or config — no previous image exists | --- ## Related -- `ork deploy` records state before every patch — [deploy docs](./deploy.md) +- `ork doctor deploy` records state before every patch — [deploy docs](./deploy.md) - Notifications that suggest rollback — [notification docs](../../../notification/docs/04-developer-notifications.md) --- -**← Previous** [ork deploy](./deploy.md) | **Back to index →** [Developer CLI](./__index.md) +**← Previous** [ork doctor deploy](./deploy.md) | **Back to index →** [Developer CLI](./__index.md) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index f06a2e2f..c7db8bec 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -14,8 +14,8 @@ Commands for deploying your own project to Kubernetes — no operator knowledge | Command | Description | |---------|-------------| | [`ork doctor`](./developer/doctor.md) | Examine the project and generate `.orkestra/` configuration | -| [`ork deploy`](./developer/deploy.md) | Build, push, and deploy to the cluster | -| [`ork deploy rollback`](./developer/rollback.md) | Instantly restore the previous image | +| [`ork doctor deploy`](./developer/deploy.md) | Build, push, and deploy to the cluster | +| [`ork doctor deploy rollback`](./developer/rollback.md) | Instantly restore the previous image | → [Developer CLI overview](./developer/__index.md) diff --git a/examples/advanced/15-any-language/README.md b/examples/advanced/15-any-language/README.md index d2510c94..50e2d40d 100644 --- a/examples/advanced/15-any-language/README.md +++ b/examples/advanced/15-any-language/README.md @@ -7,7 +7,7 @@ This directory contains three language examples that produce identical `katalog. ## Prerequisites - Orkestra CLI installed (`ork`) -- `kubectl` configured for a cluster (or use `ork deploy --dev` to create a Kind cluster) +- `kubectl` configured for a cluster (or use `ork doctor deploy --dev` to create a Kind cluster) - For each language: - **Python**: `python3` and `pyyaml` (`pip install pyyaml`) - **Go**: `go` and `gopkg.in/yaml.v3` (fetched automatically) diff --git a/examples/beginner/01-hello-website/katalog.yaml b/examples/beginner/01-hello-website/katalog.yaml index 6c15603a..086b6ce3 100644 --- a/examples/beginner/01-hello-website/katalog.yaml +++ b/examples/beginner/01-hello-website/katalog.yaml @@ -26,7 +26,6 @@ spec: onCreate: deployments: - image: "{{ .spec.image }}" - sleep: 5xx # name defaults to: -deployment # namespace defaults to: # replicas defaults to: 1 diff --git a/examples/developer/01-one-project/README.md b/examples/developer/01-one-project/README.md index 85a0f23d..07c29da0 100644 --- a/examples/developer/01-one-project/README.md +++ b/examples/developer/01-one-project/README.md @@ -7,7 +7,7 @@ No CRDs to write. No Helm charts. No `kubectl apply`. - `ork doctor` — what Orkestra detects in your project - `ork doctor init` — generating the `.orkestra/` configuration -- `ork deploy` — the full build → push → deploy → watch pipeline +- `ork doctor deploy` — the full build → push → deploy → watch pipeline - Viewing your live deployment in the Orkestra Control Center --- @@ -48,7 +48,7 @@ kubectl config current-context You don't need a cluster yet. Jump to Step 4 and add `--dev`: ```bash -ork deploy --registry --dev +ork doctor deploy --registry --dev ``` Orkestra creates a local `kind` cluster called `orkestra-playground` and deploys @@ -116,7 +116,7 @@ data: port: "8080" replicas: "2" controlCenterHost: "" # leave empty for local access - image: "" # set automatically by ork deploy + image: "" # set automatically by ork doctor deploy ``` !!! tip @@ -128,10 +128,10 @@ data: ## Step 4 — Deploy ```bash -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg # Or, if you don't have a cluster yet: -ork deploy --registry ghcr.io/myorg --dev +ork doctor deploy --registry ghcr.io/myorg --dev ``` !!! note diff --git a/examples/developer/02-frontend-backend/README.md b/examples/developer/02-frontend-backend/README.md index b9029890..16943904 100644 --- a/examples/developer/02-frontend-backend/README.md +++ b/examples/developer/02-frontend-backend/README.md @@ -98,7 +98,7 @@ ork doctor init --name my-frontend --add-ingress ## Step 4 — Deploy the frontend ```bash -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg # Add --dev if you used it in example 01 ``` diff --git a/examples/developer/03-rollback-ingress/README.md b/examples/developer/03-rollback-ingress/README.md index 7e1d58d8..60b779e7 100644 --- a/examples/developer/03-rollback-ingress/README.md +++ b/examples/developer/03-rollback-ingress/README.md @@ -6,7 +6,7 @@ Then expose your app at a real public URL using `--add-ingress`. **What you learn:** - How deploy state is recorded before every push -- `ork deploy rollback` — instant image restore, no rebuild +- `ork doctor deploy rollback` — instant image restore, no rebuild - Exposing an app publicly with `--add-ingress` and a hostname !!! note @@ -32,7 +32,7 @@ Commit and deploy: ```bash cd my-api git add . && git commit -m "intentional break" -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg ``` Watch the deploy proceed normally through build and push. @@ -48,7 +48,7 @@ goroutine 1 [running]: --- A previous good image is available. - Roll back with: ork deploy rollback + Roll back with: ork doctor deploy rollback ~ could not confirm readiness: timed out waiting for my-api-orkestra ``` @@ -58,7 +58,7 @@ goroutine 1 [running]: ### Step 2 — Roll back ```bash -ork deploy rollback +ork doctor deploy rollback ``` Output: @@ -101,10 +101,10 @@ Revert the change: ```bash git revert HEAD --no-edit -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg ``` -Rollback is reversible too — `ork deploy rollback` immediately after a successful +Rollback is reversible too — `ork doctor deploy rollback` immediately after a successful rollback will re-roll-forward to the image you just rolled back from. --- @@ -133,10 +133,10 @@ data: Deploy: ```bash -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg ``` -`ork deploy` detects the frontend/ingress and installs an nginx ingress controller +`ork doctor deploy` detects the frontend/ingress and installs an nginx ingress controller automatically if one is not already present. !!! note "kind cluster" diff --git a/examples/developer/04-notify/README.md b/examples/developer/04-notify/README.md index 3f310cc1..3f211c35 100644 --- a/examples/developer/04-notify/README.md +++ b/examples/developer/04-notify/README.md @@ -30,7 +30,7 @@ when: teams: [developer] message: "{{ .metadata.name }} is deploying but replicas are not ready yet. Check logs: kubectl logs -n {{ .metadata.namespace }} -l ork.io/app={{ .metadata.name }} --tail=50 - | Roll back if stuck: ork deploy rollback" + | Roll back if stuck: ork doctor deploy rollback" ``` The `developer` team reference is a no-op until you configure it. @@ -123,7 +123,7 @@ This mounts the Secret into the Orkestra runtime as env vars. ## Step 4 — Deploy ```bash -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg ``` After applying the bundle, watch for: @@ -156,7 +156,7 @@ Deploy a broken image (same as in example 03): # In main.go, add at the top of main(): // panic("testing notification") git add . && git commit -m "trigger notification test" -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg ``` Within 15 minutes of the replicas failing to become ready, you will receive: @@ -169,7 +169,7 @@ Subject: [orkestra] replicasReady condition triggered my-api is deploying but replicas are not ready yet. Check logs: kubectl logs -n my-api-orkestra-ns -l ork.io/app=my-api --tail=50 -Roll back if stuck: ork deploy rollback +Roll back if stuck: ork doctor deploy rollback ``` **Slack:** @@ -177,7 +177,7 @@ Roll back if stuck: ork deploy rollback ``` my-api is deploying but replicas are not ready yet. Check logs: kubectl logs -n my-api-orkestra-ns -l ork.io/app=my-api --tail=50 -Roll back if stuck: ork deploy rollback +Roll back if stuck: ork doctor deploy rollback [Katalog: my-api] [Team: developer] ``` @@ -190,7 +190,7 @@ while the condition stays true. On Orkestra restart, the clock resets. ## Step 6 — Roll back and verify silence ```bash -ork deploy rollback +ork doctor deploy rollback ``` Once replicas become ready, `replicasReady` evaluates to `true` — the condition is diff --git a/examples/developer/05-deletion-protection/README.md b/examples/developer/05-deletion-protection/README.md index 852f20c1..53571a63 100644 --- a/examples/developer/05-deletion-protection/README.md +++ b/examples/developer/05-deletion-protection/README.md @@ -84,7 +84,7 @@ security: Redeploy so Orkestra picks up the change: ```bash -ork deploy --registry ghcr.io/myorg +ork doctor deploy --registry ghcr.io/myorg ``` Watch the Orkestra logs confirm the webhook is removed: @@ -123,7 +123,7 @@ cycle just to clean up a test deploy. Use `--no-secure`: ```bash ork doctor init --name my-api --no-secure -ork deploy --registry ghcr.io/myorg --no-secure +ork doctor deploy --registry ghcr.io/myorg --no-secure ``` `--no-secure` skips deletion protection labels and the webhook entirely. diff --git a/examples/developer/06-docker-compose-with-postgres/README.md b/examples/developer/06-docker-compose-with-postgres/README.md index ed9052a2..2fb275b3 100644 --- a/examples/developer/06-docker-compose-with-postgres/README.md +++ b/examples/developer/06-docker-compose-with-postgres/README.md @@ -9,7 +9,7 @@ knowledge required. |---|---| | Docker | https://docs.docker.com/get-docker/ | | `ork` | `curl -sSL https://get.orkestra.sh \| sh` | -| A cluster | Existing cluster **or** use `ork deploy --dev` to create one | +| A cluster | Existing cluster **or** use `ork doctor deploy --dev` to create one | A registry to push your image to (e.g. `ghcr.io/yourorg`). @@ -68,12 +68,12 @@ stack. **With an existing cluster:** ```bash -ork deploy --registry ghcr.io/yourorg +ork doctor deploy --registry ghcr.io/yourorg ``` **With a local kind cluster (created automatically):** ```bash -ork deploy --registry ghcr.io/yourorg --dev +ork doctor deploy --registry ghcr.io/yourorg --dev ``` Orkestra: diff --git a/examples/developer/06-docker-compose-with-postgres/motifs/postgres/motif.yaml b/examples/developer/06-docker-compose-with-postgres/motifs/postgres/motif.yaml index 2f39e37c..9f0a694e 100644 --- a/examples/developer/06-docker-compose-with-postgres/motifs/postgres/motif.yaml +++ b/examples/developer/06-docker-compose-with-postgres/motifs/postgres/motif.yaml @@ -58,7 +58,8 @@ resources: name: "{{ inputs.passwordSecretName }}" key: POSTGRES_PASSWORD reconcile: true - resourceProfile: "{{ .inputs.resourceProfile }}" + resources: + profile: "{{ .inputs.resourceProfile }}" services: - name: "{{ .metadata.name }}-postgres-headless" diff --git a/examples/developer/README.md b/examples/developer/README.md index a094b732..8876baf2 100644 --- a/examples/developer/README.md +++ b/examples/developer/README.md @@ -8,7 +8,7 @@ Three commands cover everything: ``` ork doctor ← understand what Orkestra sees in your project ork doctor init ← generate .orkestra/ config -ork deploy ← build, push, deploy, watch +ork doctor deploy ← build, push, deploy, watch ``` --- @@ -52,12 +52,12 @@ Example 02 adds a minimal nginx frontend from `frontend/`. | Docker | Yes | Build and push images | | A container registry | Yes | Pass via `--registry` (e.g. `ghcr.io/myorg`) | | Go | Only for `--dev` | Needed to install `kind` — see note below | -| `kubectl` | Auto-installed | `ork deploy` installs it if missing | -| `helm` | Auto-installed | `ork deploy` installs it if missing | +| `kubectl` | Auto-installed | `ork doctor deploy` installs it if missing | +| `helm` | Auto-installed | `ork doctor deploy` installs it if missing | !!! note "About Go and --dev" - If you don't have a Kubernetes cluster, `ork deploy --dev` creates a local - `kind` cluster called `orkestra-playground`. `ork deploy` installs `kind` + If you don't have a Kubernetes cluster, `ork doctor deploy --dev` creates a local + `kind` cluster called `orkestra-playground`. `ork doctor deploy` installs `kind` automatically — but `kind` requires Go. Install Go from https://go.dev/dl/ before using `--dev`. Everything else (`kubectl`, `helm`, `kind`) is handled for you. @@ -76,16 +76,16 @@ Check that your current context points to the right cluster: kubectl config current-context ``` -If it does, continue. `ork deploy` will deploy to that cluster. +If it does, continue. `ork doctor deploy` will deploy to that cluster. **Option B — Let Orkestra create a local cluster (--dev)** ```bash # Requires Go — see Dependencies above -ork deploy --registry --dev +ork doctor deploy --registry --dev ``` -`ork deploy --dev` creates a `kind` cluster named `orkestra-playground` on the +`ork doctor deploy --dev` creates a `kind` cluster named `orkestra-playground` on the first run and reuses it on subsequent runs. Kind and all cluster tooling are installed automatically. diff --git a/new-frontiers/feedbacks/ork-deploy.md b/new-frontiers/feedbacks/ork-deploy.md index 1d705ac2..2fd602ac 100644 --- a/new-frontiers/feedbacks/ork-deploy.md +++ b/new-frontiers/feedbacks/ork-deploy.md @@ -1,4 +1,4 @@ -# `ork deploy` Feedback – Organised +# `ork doctor deploy` Feedback – Organised ## 1. Developer Experience – Genuinely New Ground @@ -6,9 +6,9 @@ The closest analogy is what Vercel did for frontend deployment: took something t What you have built is that for Kubernetes backends. The developer's mental model is "my Dockerfile and .env describe my app" — Orkestra absorbs everything between that and a running, scaled, observed, rollback‑capable production deployment. HPA, PDB, ingress controller, RBAC, secrets management, namespace isolation — none of it surfaces. -The thing that makes this more interesting than Vercel for some use cases: it runs on the developer's own cluster. No vendor lock‑in. No per‑seat pricing. No data leaving the cluster. A startup with a $20/month Hetzner VPS and a Kind cluster gets production‑grade Kubernetes deployment infrastructure from `ork deploy`. +The thing that makes this more interesting than Vercel for some use cases: it runs on the developer's own cluster. No vendor lock‑in. No per‑seat pricing. No data leaving the cluster. A startup with a $20/month Hetzner VPS and a Kind cluster gets production‑grade Kubernetes deployment infrastructure from `ork doctor deploy`. -The three commands are right. `ork doctor` (look), `ork doctor init` (prepare), `ork deploy` (go). The rollback being one more command is fine — it's a recovery action, not part of the happy path. The ingress auto‑install removes the last moment where a developer would have hit a wall and needed to search "how to install nginx ingress controller kubernetes." +The three commands are right. `ork doctor` (look), `ork doctor init` (prepare), `ork doctor deploy` (go). The rollback being one more command is fine — it's a recovery action, not part of the happy path. The ingress auto‑install removes the last moment where a developer would have hit a wall and needed to search "how to install nginx ingress controller kubernetes." ## 2. The Transformation in One Sentence @@ -30,13 +30,13 @@ None of those words appear in `app.yaml`. The developer manages `port`, `replica ## 3. The Generated Katalog as a Ramp -The `katalog.yaml` is generated, not hidden. A developer who gets curious can open it, read it, and learn exactly what Orkestra built for them. The progression is natural: run `ork deploy` → notice what was created → edit `katalog.yaml` → eventually write one from scratch. Orkestra is a ramp, not a ceiling. +The `katalog.yaml` is generated, not hidden. A developer who gets curious can open it, read it, and learn exactly what Orkestra built for them. The progression is natural: run `ork doctor deploy` → notice what was created → edit `katalog.yaml` → eventually write one from scratch. Orkestra is a ramp, not a ceiling. ## 4. Business Angles ### Near Term — Managed Orkestra -Users bring their own cluster (GKE, EKS, Kind), `ork deploy` does the rest. The `Komposer` and `state.json` already live in `~/.orkestra/` — that's one sync away from being cloud‑backed. A team plan syncs state across developers on the same cluster. +Users bring their own cluster (GKE, EKS, Kind), `ork doctor deploy` does the rest. The `Komposer` and `state.json` already live in `~/.orkestra/` — that's one sync away from being cloud‑backed. A team plan syncs state across developers on the same cluster. ### Medium Term — The Katalog Registry @@ -52,4 +52,4 @@ The moat isn't the tooling. The moat is the Katalog format — if teams start sh ## 6. The Honest Risk -The developer experience has to be genuinely zero‑friction from the first `ork deploy`. One confusing error message, one missing prerequisite, one "why didn't it just work" — and they go back to Railway. The `--dev` flag creating a Kind cluster automatically, the ingress controller installing itself, the runtime health check with inline logs — those aren't features, they're the table stakes for that audience. \ No newline at end of file +The developer experience has to be genuinely zero‑friction from the first `ork doctor deploy`. One confusing error message, one missing prerequisite, one "why didn't it just work" — and they go back to Railway. The `--dev` flag creating a Kind cluster automatically, the ingress controller installing itself, the runtime health check with inline logs — those aren't features, they're the table stakes for that audience. \ No newline at end of file diff --git a/pkg/autoscaler/autoscale_semaphore.go b/pkg/autoscaler/autoscale_semaphore.go index b67e69cb..f68f6dad 100644 --- a/pkg/autoscaler/autoscale_semaphore.go +++ b/pkg/autoscaler/autoscale_semaphore.go @@ -163,5 +163,9 @@ func (s *ResizableSemaphore) IdlePercent() float64 { if s.cap == 0 { return 0 } - return 100 - s.BusyPercent() + idle := s.cap - s.current + if idle < 0 { + idle = 0 + } + return float64(idle) / float64(s.cap) * 100 } diff --git a/pkg/buildx/README.md b/pkg/buildx/README.md index 04c767f2..16426c43 100644 --- a/pkg/buildx/README.md +++ b/pkg/buildx/README.md @@ -8,7 +8,7 @@ The buildx package abstracts container image building and pushing across Docker, |------|------| | `buildx.go` | `Builder` interface, `BuildImage` / `PushImage` public API, builder selection | | `builders.go` | `DockerBuilder`, `PodmanBuilder`, `BuildahBuilder` — one struct per supported tool | -| `compose_init.go` | `InitConfig`, `AppEntry` — persist `ork doctor init` settings to `.orkestra/bundle/.init.ork` for `ork deploy` to read | +| `compose_init.go` | `InitConfig`, `AppEntry` — persist `ork doctor init` settings to `.orkestra/bundle/.init.ork` for `ork doctor deploy` to read | ## Builder auto-selection @@ -18,7 +18,7 @@ The buildx package abstracts container image building and pushing across Docker, AllBuilders = [DockerBuilder, PodmanBuilder, BuildahBuilder] ``` -The user never selects a builder — the first available tool wins. This makes the same `ork deploy` command work in Docker Desktop, Podman Machine, and CI environments that only have Buildah. +The user never selects a builder — the first available tool wins. This makes the same `ork doctor deploy` command work in Docker Desktop, Podman Machine, and CI environments that only have Buildah. ## Public API diff --git a/pkg/buildx/compose_init.go b/pkg/buildx/compose_init.go index 07c73dff..a8602322 100644 --- a/pkg/buildx/compose_init.go +++ b/pkg/buildx/compose_init.go @@ -15,7 +15,7 @@ type AppEntry struct { } // InitConfig is the full configuration persisted in .orkestra/bundle/.init.ork. -// It bridges `ork doctor init` settings through to `ork deploy`. +// It bridges `ork doctor init` settings through to `ork doctor deploy`. type InitConfig struct { UseCompose bool // true → compose-based build ComposeFile string // path to docker-compose.yaml (only when UseCompose) diff --git a/pkg/buildx/docs/02-init-config.md b/pkg/buildx/docs/02-init-config.md index b679f191..af689a0e 100644 --- a/pkg/buildx/docs/02-init-config.md +++ b/pkg/buildx/docs/02-init-config.md @@ -1,10 +1,10 @@ # 02 — InitConfig and the .init.ork File -`InitConfig` bridges the `ork doctor init` step to `ork deploy`. After init runs, deploy must know how to build each app — which directory, which Dockerfile, and whether to use compose. `.init.ork` is the handshake file. +`InitConfig` bridges the `ork doctor init` step to `ork doctor deploy`. After init runs, deploy must know how to build each app — which directory, which Dockerfile, and whether to use compose. `.init.ork` is the handshake file. ## The file -`.orkestra/bundle/.init.ork` is a simple key=value file written by `ork doctor init` and read by `ork deploy`. It is never committed (`.orkestra/bundle/` is gitignored, but `.init.ork` sits one level up at `.orkestra/`). +`.orkestra/bundle/.init.ork` is a simple key=value file written by `ork doctor init` and read by `ork doctor deploy`. It is never committed (`.orkestra/bundle/` is gitignored, but `.init.ork` sits one level up at `.orkestra/`). ``` useCompose=false @@ -42,7 +42,7 @@ type InitConfig struct { } ``` -`Apps` is empty for the single-app (legacy) path. `ork deploy` checks `len(initCfg.Apps) > 0` to choose between single-app and multi-app deploy flows. +`Apps` is empty for the single-app (legacy) path. `ork doctor deploy` checks `len(initCfg.Apps) > 0` to choose between single-app and multi-app deploy flows. ## API @@ -65,6 +65,6 @@ cfg, err := buildx.LoadInitConfig(projectDir) buildx.CleanupInitConfig(projectDir) ``` -`LoadInitConfig` returns an empty `InitConfig` (no error) when `.init.ork` does not exist — this is the case when the user runs `ork deploy` without having run `ork doctor init` first (legacy flow). +`LoadInitConfig` returns an empty `InitConfig` (no error) when `.init.ork` does not exist — this is the case when the user runs `ork doctor deploy` without having run `ork doctor init` first (legacy flow). → Back to: [README.md](../README.md) diff --git a/pkg/doctor/bundle.go b/pkg/doctor/bundle.go index d2671750..8c03a49b 100644 --- a/pkg/doctor/bundle.go +++ b/pkg/doctor/bundle.go @@ -56,7 +56,7 @@ func GenerateBundle(name, namespace string, secrets, config []orktypes.EnvVar, o func buildSecret(name, namespace string, vars []orktypes.EnvVar) string { var b strings.Builder b.WriteString("# .orkestra/bundle/app-secrets.yaml\n") - b.WriteString("# Generated by ork deploy — DO NOT COMMIT THIS FILE\n") + b.WriteString("# Generated by ork doctor deploy — DO NOT COMMIT THIS FILE\n") b.WriteString("# Add .orkestra/bundle/ to .gitignore\n\n") b.WriteString("apiVersion: v1\n") b.WriteString("kind: Secret\n") @@ -75,7 +75,7 @@ func buildSecret(name, namespace string, vars []orktypes.EnvVar) string { func buildConfigMap(name, namespace string, vars []orktypes.EnvVar) string { var b strings.Builder b.WriteString("# .orkestra/bundle/app-config.yaml\n") - b.WriteString("# Generated by ork deploy — DO NOT COMMIT THIS FILE\n\n") + b.WriteString("# Generated by ork doctor deploy — DO NOT COMMIT THIS FILE\n\n") b.WriteString("apiVersion: v1\n") b.WriteString("kind: ConfigMap\n") b.WriteString("metadata:\n") diff --git a/pkg/doctor/compose.go b/pkg/doctor/compose.go index 0e737f67..b257e3ad 100644 --- a/pkg/doctor/compose.go +++ b/pkg/doctor/compose.go @@ -86,13 +86,25 @@ var knownMotifs = []KnownMotif{ { Image: "confluentinc/cp-kafka", MotifRef: "kafka", - AppYAMLKeys: []string{"kafkaImage"}, + AppYAMLKeys: []string{"kafkaImage", "kafkaVolumeSize"}, AdminUI: "Kafka UI", }, { Image: "bitnami/kafka", MotifRef: "kafka", - AppYAMLKeys: []string{"kafkaImage"}, + AppYAMLKeys: []string{"kafkaImage", "kafkaVolumeSize"}, + AdminUI: "Kafka UI", + }, + { + Image: "apache/kafka", + MotifRef: "kafka", + AppYAMLKeys: []string{"kafkaImage", "kafkaVolumeSize"}, + AdminUI: "Kafka UI", + }, + { + Image: "kafka", + MotifRef: "kafka", + AppYAMLKeys: []string{"kafkaImage", "kafkaVolumeSize"}, AdminUI: "Kafka UI", }, { diff --git a/pkg/doctor/docs/01-detection.md b/pkg/doctor/docs/01-detection.md index 93697a7e..74d267da 100644 --- a/pkg/doctor/docs/01-detection.md +++ b/pkg/doctor/docs/01-detection.md @@ -68,7 +68,7 @@ When `HasFrontend` is true, the generator includes an Ingress in the Katalog and `shortGitCommit` reads `.git/HEAD` directly — no `git` binary required. It follows symbolic refs (`ref: refs/heads/main`) to the commit SHA and returns the first 7 characters. Returns `""` for detached HEAD with a short SHA and for non-git directories. -The short SHA is used as the default image tag in `ork deploy`: +The short SHA is used as the default image tag in `ork doctor deploy`: ``` ghcr.io/myorg/my-app:a3f5c2b diff --git a/pkg/doctor/docs/03-generation.md b/pkg/doctor/docs/03-generation.md index 7a5416c9..aef93b9f 100644 --- a/pkg/doctor/docs/03-generation.md +++ b/pkg/doctor/docs/03-generation.md @@ -50,7 +50,7 @@ The Role is scoped to the app's namespace and allows only `get`, `list`, `watch` ### Resources created when `data.image` is set -The Deployment, HPA, and PDB all carry `when: - field: data.image / exists: true`. Until `ork deploy` patches the image field, these resources are not created — the namespace, service account, role, and role binding exist but the workload is idle. +The Deployment, HPA, and PDB all carry `when: - field: data.image / exists: true`. Until `ork doctor deploy` patches the image field, these resources are not created — the namespace, service account, role, and role binding exist but the workload is idle. | Resource | onCreate | Condition | |----------|----------|-----------| @@ -171,12 +171,12 @@ data: maxReplicas: "10" host: "" # this app's public hostname (e.g. myapp.example.com) controlCenterHost: "" # Orkestra Control Center hostname (e.g. control.mycompany.com) - image: "" # set by ork deploy — do not edit manually + image: "" # set by ork doctor deploy — do not edit manually ``` -`ork deploy` patches the `image` field. Everything else is developer-managed. +`ork doctor deploy` patches the `image` field. Everything else is developer-managed. -`controlCenterHost` is cluster-wide — the same value for all apps in the cluster. When empty, `ork deploy` shows the internal svc URL `http://orkestra-cc.orkestra-system.svc.cluster.local:8081`. +`controlCenterHost` is cluster-wide — the same value for all apps in the cluster. When empty, `ork doctor deploy` shows the internal svc URL `http://orkestra-cc.orkestra-system.svc.cluster.local:8081`. ## Multi-app projects @@ -196,7 +196,7 @@ doctor.Init(frontendInfo, doctor.GenerateOptions{ }) ``` -Each app gets its own `katalog.yaml` and `app.yaml`. The CLI also writes a shared `.init.ork` via `buildx.WriteInitConfigFull` that records all app entries for `ork deploy` to consume. +Each app gets its own `katalog.yaml` and `app.yaml`. The CLI also writes a shared `.init.ork` via `buildx.WriteInitConfigFull` that records all app entries for `ork doctor deploy` to consume. ## Usage diff --git a/pkg/doctor/docs/04-bundle.md b/pkg/doctor/docs/04-bundle.md index f8d5ebcd..1f066166 100644 --- a/pkg/doctor/docs/04-bundle.md +++ b/pkg/doctor/docs/04-bundle.md @@ -16,7 +16,7 @@ Only files for non-empty variable sets are written: if there are no secrets, `ap ```yaml # .orkestra/bundle/app-secrets.yaml -# Generated by ork deploy — DO NOT COMMIT THIS FILE +# Generated by ork doctor deploy — DO NOT COMMIT THIS FILE # Add .orkestra/bundle/ to .gitignore apiVersion: v1 @@ -36,7 +36,7 @@ Values are base64-encoded using `encoding/base64` standard encoding. The name is ```yaml # .orkestra/bundle/app-config.yaml -# Generated by ork deploy — DO NOT COMMIT THIS FILE +# Generated by ork doctor deploy — DO NOT COMMIT THIS FILE apiVersion: v1 kind: ConfigMap @@ -54,9 +54,9 @@ Values are written as quoted strings. The name is `-config`. `.orkestra/bundle/` is added to `.gitignore` by `ork doctor init`. Generated secret files never enter source control. -`ork deploy` regenerates the bundle from the local `.env` on every run. This means: -- Adding a variable to `.env` and re-running `ork deploy` applies it to the cluster. -- Removing a variable and re-running `ork deploy` removes it from the Secret/ConfigMap. +`ork doctor deploy` regenerates the bundle from the local `.env` on every run. This means: +- Adding a variable to `.env` and re-running `ork doctor deploy` applies it to the cluster. +- Removing a variable and re-running `ork doctor deploy` removes it from the Secret/ConfigMap. - The cluster's live Secret always reflects the local `.env` after the most recent deploy. For production secret rotation without re-deploying: edit the Kubernetes Secret directly. The operator does not touch secrets it did not create in the current reconcile cycle. diff --git a/pkg/doctor/docs/05-deploy.md b/pkg/doctor/docs/05-deploy.md index 7a7022da..4da4d12a 100644 --- a/pkg/doctor/docs/05-deploy.md +++ b/pkg/doctor/docs/05-deploy.md @@ -9,7 +9,7 @@ image := doctor.ImageTag("ghcr.io/myorg", "my-app", "a3f5c2b") // → "ghcr.io/myorg/my-app:a3f5c2b" ``` -The tag is the git commit short SHA by default. `ork deploy --tag v1.2.0` overrides it. When there is no git repository, the tag falls back to `"latest"`. +The tag is the git commit short SHA by default. `ork doctor deploy --tag v1.2.0` overrides it. When there is no git repository, the tag falls back to `"latest"`. ## Build and push @@ -36,7 +36,7 @@ if !doctor.ClusterReachable() { Runs `kubectl cluster-info --request-timeout=5s` with a 5-second context timeout. Returns false when kubectl is missing, the kubeconfig is invalid, or the API server is unreachable. -`ork deploy` calls this before any cluster operations. When the check fails and `--dev` was not passed, the user is told to use `--dev`. +`ork doctor deploy` calls this before any cluster operations. When the check fails and `--dev` was not passed, the user is told to use `--dev`. ### KubectlAvailable @@ -68,7 +68,7 @@ err := doctor.EnsureKindCluster(doctor.KindClusterName) - Switches kubectl to the kind context (`kind-orkestra-playground`). - Installs kind via `go install sigs.k8s.io/kind@v0.31.0` if not found in PATH or GOBIN. -`ork deploy --dev` calls `GoInstalled()` first; if Go is absent it returns an error with install instructions before attempting anything else. +`ork doctor deploy --dev` calls `GoInstalled()` first; if Go is absent it returns an error with install instructions before attempting anything else. ## Orkestra installation @@ -78,7 +78,7 @@ if !doctor.OrkestraInstalled() || upgradeOrkestra { } ``` -`helm.go` runs `helm install` or `helm upgrade --install` against `https://orkspace.github.io/orkestra`. `ork deploy` auto-detects `.orkestra/values.yaml` and passes it via `--values` when the `--values` flag is not set explicitly. +`helm.go` runs `helm install` or `helm upgrade --install` against `https://orkspace.github.io/orkestra`. `ork doctor deploy` auto-detects `.orkestra/values.yaml` and passes it via `--values` when the `--values` flag is not set explicitly. ## Runtime health @@ -116,7 +116,7 @@ ic := doctor.DetectIngressController() // IngressNginx | IngressTraefik | IngressNone ``` -`ork deploy` calls `ensureIngressController()` automatically when the project has a frontend (`HasFrontend == true`). It: +`ork doctor deploy` calls `ensureIngressController()` automatically when the project has a frontend (`HasFrontend == true`). It: 1. Calls `DetectIngressController()` — returns early if already present. 2. Detects a kind context and applies the kind-specific nginx manifest. 3. Otherwise installs via `helm install ingress-nginx ingress-nginx/ingress-nginx`. @@ -149,11 +149,11 @@ komposer.Save() names := komposer.DeployedProjects() // ["my-app", "my-api"] ``` -`ork deploy` registers the current project's Katalog path on every deploy and then attempts to run `ork kompose` to merge all Katalogs into a single `~/.orkestra/deploy/merged-katalog.yaml` that Orkestra can watch. This step is non-fatal — if `ork kompose` is not yet available, a warning is printed and the deploy continues normally. +`ork doctor deploy` registers the current project's Katalog path on every deploy and then attempts to run `ork kompose` to merge all Katalogs into a single `~/.orkestra/deploy/merged-katalog.yaml` that Orkestra can watch. This step is non-fatal — if `ork kompose` is not yet available, a warning is printed and the deploy continues normally. ## The full deploy sequence -`ork deploy` orchestrates everything in order: +`ork doctor deploy` orchestrates everything in order: ``` 0. Cluster check → --dev: EnsureKindCluster / else: ClusterReachable() @@ -181,15 +181,15 @@ Steps 1–16 are skipped with `--dry-run`. ## Rollback ```bash -ork deploy rollback # restore previous image from state.json -ork deploy rollback --image ghcr.io/myorg/app:a1b2c3d # explicit image +ork doctor deploy rollback # restore previous image from state.json +ork doctor deploy rollback --image ghcr.io/myorg/app:a1b2c3d # explicit image ``` Rollback reads `~/.orkestra/deploy/state.json` first and falls back to the `orkestra.io/previous-image` annotation on the ConfigMap for backward compatibility. It swaps `currentImage` ↔ `previousImage` in state before patching, so a second rollback call re-rolls-forward. ## Control Center URL -After a successful deploy, `ork deploy` prints: +After a successful deploy, `ork doctor deploy` prints: ``` Control Center → https://control.mycompany.com diff --git a/pkg/doctor/generate.go b/pkg/doctor/generate.go index 9b3f0493..9ad4fe08 100644 --- a/pkg/doctor/generate.go +++ b/pkg/doctor/generate.go @@ -18,13 +18,8 @@ const ( ) var ( - gitignoreEntries = []string{ - ".orkestra/bundle/", - } - - dockerignoreEntries = []string{ - ".orkestra/bundle/", - } + gitignoreEntries = []string{} + dockerignoreEntries = []string{} ) // GenerateOptions controls which sections are included in the generated Katalog. @@ -113,6 +108,130 @@ func Init(info *orktypes.ProjectInfo, opts GenerateOptions) error { return nil } +// InitDeveloper generates the developer-path artifacts for a project. +// The only file written to the project directory is .orkestra/app.yaml — +// the one file a developer is expected to edit. +// +// Stateful services (databases, caches, queues) are injected automatically +// from opts.InjectStateful or discovered via opts.UseCompose. +// +// The motif template (resource blueprint) is returned as a string so the +// caller can persist it to ~/.orkestra/apps//motif.yaml — outside +// the project tree and invisible to the developer. +// +// No katalog.yaml is generated. The central Katalog at +// ~/.orkestra/deploy/katalog.yaml is managed by ork doctor deploy. +func InitDeveloper(info *orktypes.ProjectInfo, opts GenerateOptions) (motifContent string, err error) { + name := opts.Name + if name == "" { + name = info.Name + } + + orkDir := opts.OutDir + if orkDir == "" { + orkDir = filepath.Join(info.Dir, ".orkestra") + } + if err := os.MkdirAll(orkDir, 0o755); err != nil { + return "", fmt.Errorf("creating %s/: %w", orkDir, err) + } + + // Resolve stateful services to inject (same logic as Init). + var stateful []StatefulService + if opts.InjectStateful != nil { + stateful = opts.InjectStateful + } else if opts.UseCompose != "" { + cf, err := ParseCompose(opts.UseCompose) + if err != nil { + return "", fmt.Errorf("reading compose file: %w", err) + } + _, stateful = ClassifyServices(cf) + } + + // Build motif template and inject stateful blocks. + motif := buildAppMotifTemplate(info, opts) + if len(stateful) > 0 { + motif = injectStatefulServices(motif, name, stateful) + } + + // Build app.yaml CR and inject stateful config keys. + crContent := buildDeveloperCR(name, info, opts) + if len(stateful) > 0 { + crContent = injectStatefulAppYAML(crContent, stateful, info) + } + + // app.yaml — the only file the developer sees or edits + if err := os.WriteFile(filepath.Join(orkDir, ApplicationFile), []byte(crContent), 0o644); err != nil { + return "", fmt.Errorf("writing app.yaml: %w", err) + } + + if err := updateGitignore(info.Dir); err != nil { + return "", fmt.Errorf("updating .gitignore: %w", err) + } + if err := updateDockerignore(info.Dir); err != nil { + return "", fmt.Errorf("updating .dockerignore: %w", err) + } + + // Return the motif template — caller stores it in ~/.orkestra/apps// + return motif, nil +} + +// buildDeveloperCR builds the developer-style ConfigMap CR. Labels include +// ork.io/platform: developer (CRD watch selector) and ork.io/app: +// so individual apps can be identified. Image is left empty — ork doctor deploy patches it. +func buildDeveloperCR(name string, info *orktypes.ProjectInfo, opts GenerateOptions) string { + replicas := "2" + if opts.NoHA { + replicas = "1" + } + + var b strings.Builder + b.WriteString("# This is the only Kubernetes object you manage.\n") + b.WriteString("# Run 'ork doctor deploy' to apply — do not apply this file manually.\n\n") + + b.WriteString("apiVersion: v1\n") + b.WriteString("kind: ConfigMap\n") + b.WriteString("metadata:\n") + b.WriteString(" name: " + name + "\n") + b.WriteString(" namespace: " + name + "-ns\n") + b.WriteString(" labels:\n") + b.WriteString(" ork.io/platform: developer\n") + b.WriteString(" ork.io/app: " + name + "\n") + if !opts.NoSecure { + b.WriteString(" " + deletionProtectionLabel + ": \"true\"\n") + b.WriteString(" " + createdBy + ": " + orkdoctor + "\n") + } + + b.WriteString("data:\n") + b.WriteString(" # ork doctor deploy updates this automatically — do not edit\n") + b.WriteString(" image: \"\"\n") + b.WriteString(" # ───────────────────────────────────────────────────────────────\n\n") + + b.WriteString(" # Application port\n") + fmt.Fprintf(&b, " port: \"%s\"\n\n", info.Port) + + b.WriteString(" # How many copies of your app to run normally\n") + fmt.Fprintf(&b, " replicas: \"%s\"\n\n", replicas) + + b.WriteString(" # How much CPU and memory your app should get. Choose a profile:\n") + b.WriteString(" # docs.orkestra.sh/concepts/resource-profiles\n") + b.WriteString(" resourceProfile: \"burst\"\n\n") + + if !opts.NoHA { + b.WriteString(" # Maximum copies of your app to run when traffic increases\n") + b.WriteString(" maxReplicas: \"10\"\n\n") + } + + if info.HasFrontend || opts.AddIngress { + b.WriteString(" # This app's public hostname (e.g. myapp.example.com)\n") + b.WriteString(" host: \"\"\n\n") + } + + b.WriteString(" # Orkestra Control Center hostname (e.g. control.mycompany.com)\n") + b.WriteString(" controlCenterHost: \"\"\n\n") + + return b.String() +} + // injectStatefulServices appends Motif import blocks for each stateful service // to the generated Katalog YAML string. func injectStatefulServices(katalogYAML, appName string, services []StatefulService) string { @@ -122,37 +241,37 @@ func injectStatefulServices(katalogYAML, appName string, services []StatefulServ var b strings.Builder b.WriteString(katalogYAML) - b.WriteString("\n # Stateful services expanded from docker-compose.yaml\n") - b.WriteString(" imports:\n") + b.WriteString("\n imports:\n") for _, s := range services { ref := s.Motif.MotifRef - b.WriteString(fmt.Sprintf(" - motif: %s\n", ref)) - b.WriteString(" with:\n") + b.WriteString(fmt.Sprintf(" - motif: %s\n", ref)) + b.WriteString(" with:\n") switch ref { case "postgres": - b.WriteString(" image: \"{{ .data.postgresImage }}\"\n") - b.WriteString(fmt.Sprintf(" passwordSecretName: %s-secrets\n", appName)) - b.WriteString(" user: \"{{ .data.postgresUser }}\"\n") - b.WriteString(" volumeSize: \"{{ .data.postgresVolumeSize }}\"\n") - b.WriteString(" adminEmail: \"{{ .data.adminEmail }}\"\n") - b.WriteString(" adminPassword: \"{{ .data.adminPassword }}\"\n") + b.WriteString(" image: \"{{ .data.postgresImage }}\"\n") + b.WriteString(fmt.Sprintf(" passwordSecretName: %s-secrets\n", appName)) + b.WriteString(" user: \"{{ .data.postgresUser }}\"\n") + b.WriteString(" volumeSize: \"{{ .data.postgresVolumeSize }}\"\n") + b.WriteString(" adminEmail: \"{{ .data.adminEmail }}\"\n") + b.WriteString(" adminPassword: \"{{ .data.adminPassword }}\"\n") case "redis": - b.WriteString(" image: \"{{ .data.redisImage }}\"\n") - b.WriteString(" volumeSize: \"{{ .data.redisVolumeSize }}\"\n") + b.WriteString(" image: \"{{ .data.redisImage }}\"\n") + b.WriteString(" volumeSize: \"{{ .data.redisVolumeSize }}\"\n") case "mysql": - b.WriteString(" image: \"{{ .data.mysqlImage }}\"\n") - b.WriteString(fmt.Sprintf(" passwordSecretName: %s-secrets\n", appName)) - b.WriteString(" user: \"{{ .data.mysqlUser }}\"\n") - b.WriteString(" volumeSize: \"{{ .data.mysqlVolumeSize }}\"\n") + b.WriteString(" image: \"{{ .data.mysqlImage }}\"\n") + b.WriteString(fmt.Sprintf(" passwordSecretName: %s-secrets\n", appName)) + b.WriteString(" user: \"{{ .data.mysqlUser }}\"\n") + b.WriteString(" volumeSize: \"{{ .data.mysqlVolumeSize }}\"\n") case "kafka": - b.WriteString(" image: \"{{ .data.kafkaImage }}\"\n") + b.WriteString(" image: \"{{ .data.kafkaImage }}\"\n") + b.WriteString(" volumeSize: \"{{ .data.kafkaVolumeSize }}\"\n") case "rabbitmq": - b.WriteString(" image: \"{{ .data.rabbitmqImage }}\"\n") + b.WriteString(" image: \"{{ .data.rabbitmqImage }}\"\n") case "mongodb": - b.WriteString(" image: \"{{ .data.mongoImage }}\"\n") - b.WriteString(" volumeSize: \"{{ .data.mongoVolumeSize }}\"\n") + b.WriteString(" image: \"{{ .data.mongoImage }}\"\n") + b.WriteString(" volumeSize: \"{{ .data.mongoVolumeSize }}\"\n") default: - fmt.Fprintf(&b, " image: \"{{ .data.%sImage }}\"\n", ref) + fmt.Fprintf(&b, " image: \"{{ .data.%sImage }}\"\n", ref) } } return b.String() @@ -167,12 +286,11 @@ func injectStatefulAppYAML(appYAML string, services []StatefulService, info *ork author, _ := LastCommitAuthor() if author == nil { - author = &GitAuthor{} - } - - if author.Notfound { - author.Email = "dev@orkestra.sh" - author.Name = "admin" + author = &GitAuthor{ + Notfound: true, + Email: "dev@orkestra.sh", + Name: "admin", + } } appUser := truncate(info.Name+"_"+"user", 15) @@ -205,6 +323,7 @@ func injectStatefulAppYAML(appYAML string, services []StatefulService, info *ork case "kafka": fmt.Fprintf(&b, " kafkaImage: \"%s\" # Container image for Kafka\n", s.Image) + b.WriteString(" kafkaVolumeSize: \"20Gi\" # Volume size for Kafka log storage\n") case "rabbitmq": fmt.Fprintf(&b, " rabbitmqImage: \"%s\" # Container image for RabbitMQ\n", s.Image) @@ -282,6 +401,13 @@ func buildKatalog(name string, info *orktypes.ProjectInfo, opts GenerateOptions) if notifyME { author, _ := LastCommitAuthor() + if author == nil { + author = &GitAuthor{ + Notfound: true, + Email: "dev@orkestra.sh", + Name: "admin", + } + } b.WriteString("notification:\n") b.WriteString(" enabled: true\n") @@ -368,7 +494,8 @@ func buildKatalog(name string, info *orktypes.ProjectInfo, opts GenerateOptions) b.WriteString(" - configMapRef: " + name + "-config\n") } } - b.WriteString(" resourceProfile: \"{{ .data.resourceProfile | default \\\"burst\\\" }}\"\n") + b.WriteString(" resources:\n") + b.WriteString(" profile: \"{{ .data.resourceProfile | default \\\"burst\\\" }}\"\n") b.WriteString(protectionLabels(" ", secure)) b.WriteString(" reconcile: true\n") b.WriteString(" when:\n") @@ -458,7 +585,7 @@ func buildKatalog(name string, info *orktypes.ProjectInfo, opts GenerateOptions) b.WriteString(" teams: [developer]\n") b.WriteString(" message: \"{{ .metadata.name }} is deploying but replicas are not ready yet.") b.WriteString(" Check logs: kubectl logs -n {{ .metadata.namespace }} -l ork.io/app={{ .metadata.name }} --tail=50") - b.WriteString(" | Roll back if stuck: ork deploy rollback\"\n") + b.WriteString(" | Roll back if stuck: ork doctor deploy rollback\"\n") b.WriteString("\n") b.WriteString(" - path: phase\n") @@ -483,7 +610,7 @@ func buildKatalog(name string, info *orktypes.ProjectInfo, opts GenerateOptions) // buildCR constructs the developer-facing ConfigMap that defines an app’s // deployment settings. This file becomes .orkestra/app.yaml and is the only -// configuration a developer edits; ork deploy reads it and manages all +// configuration a developer edits; ork doctor deploy reads it and manages all // Kubernetes resources from it. func buildCR(name string, info *orktypes.ProjectInfo, opts GenerateOptions) string { crName := name + "-orkestra" @@ -497,7 +624,7 @@ func buildCR(name string, info *orktypes.ProjectInfo, opts GenerateOptions) stri var b strings.Builder b.WriteString("# This is the only Kubernetes object you manage.\n") - b.WriteString("# Run 'ork deploy' to apply — do not apply this file manually.\n\n") + b.WriteString("# Run 'ork doctor deploy' to apply — do not apply this file manually.\n\n") b.WriteString("apiVersion: v1\n") b.WriteString("kind: ConfigMap\n") @@ -512,7 +639,7 @@ func buildCR(name string, info *orktypes.ProjectInfo, opts GenerateOptions) stri } b.WriteString("data:\n") - b.WriteString(" # ork deploy updates this automatically — do not edit\n") + b.WriteString(" # ork doctor deploy updates this automatically — do not edit\n") b.WriteString(" image: \"\"\n") b.WriteString(" # ───────────────────────────────────────────────────────────────\n\n") @@ -542,6 +669,315 @@ func buildCR(name string, info *orktypes.ProjectInfo, opts GenerateOptions) stri return b.String() } +// SaveMotif writes the motif template for appName to +// ~/.orkestra/apps//motif.yaml — outside the project directory +// so it is never visible to the developer. +func SaveMotif(appName, content string) error { + motifPath, err := MotifPath(appName) + if err != nil { + return err + } + if err := os.MkdirAll(filepath.Dir(motifPath), 0o755); err != nil { + return fmt.Errorf("creating motif dir: %w", err) + } + return os.WriteFile(motifPath, []byte(content), 0o644) +} + +// buildAppMotifTemplate returns a motif.yaml template string for the given app. +// Resources use {{ .metadata.* }} and {{ .data.* }} runtime expressions so that +// ONE platform CRD entry in the central katalog can serve all developer apps. +// Orkestra evaluates these expressions per-CR at reconcile time. +func buildAppMotifTemplate(info *orktypes.ProjectInfo, opts GenerateOptions) string { + name := info.Name + if info.AppName != "" { + name = info.AppName + } + + replicas := "2" + if opts.NoHA { + replicas = "1" + } + + var b strings.Builder + b.WriteString("# Generated by ork doctor init.\n") + b.WriteString("# Embedded verbatim into the central katalog by 'ork doctor deploy'.\n") + b.WriteString("# Runtime expressions ({{ .metadata.* }}, {{ .data.* }}) are evaluated\n") + b.WriteString("# by Orkestra per-CR — do not replace them with concrete values.\n") + b.WriteString("apiVersion: orkestra.orkspace.io/v1\n") + b.WriteString("kind: Motif\n") + b.WriteString("metadata:\n") + b.WriteString(" name: " + name + "\n\n") + + b.WriteString("resources:\n") + + b.WriteString(" serviceAccounts:\n") + b.WriteString(" - name: \"{{ .metadata.name }}\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + b.WriteString(" reconcile: true\n\n") + + b.WriteString(" roles:\n") + b.WriteString(" - name: \"{{ .metadata.name }}\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + b.WriteString(" reconcile: true\n") + b.WriteString(" rules:\n") + b.WriteString(" - apiGroups: [\"\"]\n") + b.WriteString(" resources: [\"configmaps\"]\n") + b.WriteString(" resourceNames: [\"{{ .metadata.name }}\"]\n") + b.WriteString(" verbs: [\"get\", \"watch\"]\n\n") + + b.WriteString(" roleBindings:\n") + b.WriteString(" - name: \"{{ .metadata.name }}\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + b.WriteString(" reconcile: true\n") + b.WriteString(" roleRef:\n") + b.WriteString(" name: \"{{ .metadata.name }}\"\n") + b.WriteString(" subjects:\n") + b.WriteString(" - kind: ServiceAccount\n") + b.WriteString(" name: \"{{ .metadata.name }}\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n\n") + + b.WriteString(" deployments:\n") + b.WriteString(" - name: \"{{ .metadata.name }}\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + b.WriteString(" image: \"{{ .data.image }}\"\n") + b.WriteString(" serviceAccountName: \"{{ .metadata.name }}\"\n") + fmt.Fprintf(&b, " replicas: \"{{ .data.replicas | default \\\"%s\\\" }}\"\n", replicas) + fmt.Fprintf(&b, " port: \"{{ .data.port | default \\\"%s\\\" }}\"\n", info.Port) + if info.HasCreds() { + b.WriteString(" envFrom:\n") + if info.HasSecrets() { + b.WriteString(" - secretRef: \"{{ .metadata.name }}-secrets\"\n") + } + if info.HasConfig() { + b.WriteString(" - configMapRef: \"{{ .metadata.name }}-config\"\n") + } + } + b.WriteString(" resources:\n") + b.WriteString(" profile: \"{{ .data.resourceProfile | default \\\"burst\\\" }}\"\n") + b.WriteString(" reconcile: true\n") + b.WriteString(" when:\n") + b.WriteString(" - field: data.image\n") + b.WriteString(" exists: true\n\n") + + b.WriteString(" services:\n") + b.WriteString(" - name: \"{{ .metadata.name }}-svc\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + fmt.Fprintf(&b, " port: \"{{ .data.port | default \\\"%s\\\" }}\"\n", info.Port) + fmt.Fprintf(&b, " targetPort: \"{{ .data.port | default \\\"%s\\\" }}\"\n", info.Port) + b.WriteString(" reconcile: true\n\n") + + if !opts.NoHA { + b.WriteString(" hpa:\n") + b.WriteString(" - name: \"{{ .metadata.name }}-hpa\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + b.WriteString(" scaleTargetRef:\n") + b.WriteString(" apiVersion: apps/v1\n") + b.WriteString(" kind: Deployment\n") + b.WriteString(" name: \"{{ .metadata.name }}\"\n") + fmt.Fprintf(&b, " minReplicas: \"{{ .data.replicas | default \\\"%s\\\" }}\"\n", replicas) + b.WriteString(" maxReplicas: \"{{ .data.maxReplicas | default \\\"10\\\" }}\"\n") + b.WriteString(" targetCPUUtilizationPercentage: \"70\"\n") + b.WriteString(" reconcile: true\n") + b.WriteString(" when:\n") + b.WriteString(" - field: data.image\n") + b.WriteString(" exists: true\n\n") + + b.WriteString(" pdb:\n") + b.WriteString(" - name: \"{{ .metadata.name }}-pdb\"\n") + b.WriteString(" namespace: \"{{ .metadata.namespace }}\"\n") + b.WriteString(" minAvailable: \"1\"\n") + b.WriteString(" reconcile: true\n") + b.WriteString(" when:\n") + b.WriteString(" - field: data.image\n") + b.WriteString(" exists: true\n\n") + } + + return b.String() +} + +// ReadAppYAMLData reads the data block from .orkestra/app.yaml (a ConfigMap) +// and returns it as a flat string map. Returns an empty map when the file +// does not exist or has no data section. +func ReadAppYAMLData(appYAML string) (map[string]string, error) { + raw, err := os.ReadFile(appYAML) + if os.IsNotExist(err) { + return map[string]string{}, nil + } + if err != nil { + return nil, fmt.Errorf("reading %s: %w", appYAML, err) + } + + var cm struct { + Data map[string]string `yaml:"data"` + } + if err := yaml.Unmarshal(raw, &cm); err != nil { + return nil, fmt.Errorf("parsing %s: %w", appYAML, err) + } + if cm.Data == nil { + return map[string]string{}, nil + } + return cm.Data, nil +} + +// AppDeployInfo carries the per-app metadata needed to generate the central Katalog. +// Name and Namespace are always known at deploy time; they are resolved concretely +// into the Katalog so Orkestra creates independent resources for each app. +type AppDeployInfo struct { + Name string + Namespace string + Port string + Language string + Image string // current deployed image (may be empty on first deploy) +} + +// GenerateDeveloperKatalog writes ~/.orkestra/deploy/katalog.yaml — the single +// central Katalog for the developer path. +// +// It produces ONE 'platform' CRD entry that manages ALL deployed developer apps. +// The motif template resources come from motifTemplate (a motif YAML string) and, +// for each app in apps, the metadata placeholders ({{ .metadata.name }}, +// {{ .metadata.namespace }}) are substituted with the concrete values known at +// deploy time. The data placeholders ({{ .data.image }}, {{ .data.port }}, etc.) +// are kept as-is so Orkestra evaluates them at runtime from the ConfigMap CR. +// +// Resolving metadata up-front ensures each app gets its own independently managed +// set of resources — Orkestra reconciles each ConfigMap CR in its own namespace +// against the matching named resources in onReconcile, so apps never collide. +// +// No imports or file-path references are emitted — the bundle ConfigMap is +// fully self-contained and the runtime pod needs no filesystem access. +func GenerateDeveloperKatalog(deployDir, motifTemplate string, apps []AppDeployInfo, opts GenerateOptions) error { + if len(apps) == 0 { + return fmt.Errorf("at least one app is required") + } + + // ── Parse motif resources block ───────────────────────────────────────── + var rawMotif map[string]interface{} + if err := yaml.Unmarshal([]byte(motifTemplate), &rawMotif); err != nil { + return fmt.Errorf("parsing motif template: %w", err) + } + resourcesRaw, ok := rawMotif["resources"] + if !ok { + return fmt.Errorf("motif template has no 'resources' block") + } + + // ── Resolve metadata per-app and merge resource lists ─────────────────── + // For each app we substitute {{ .metadata.name }} and {{ .metadata.namespace }} + // with the concrete values we already know, then merge each resource type's + // list (serviceAccounts, deployments, services, …) across all apps. + merged := map[string][]interface{}{} + + for _, app := range apps { + // Marshal resources to a YAML string so we can do string substitution. + appYAML, err := yaml.Marshal(resourcesRaw) + if err != nil { + return fmt.Errorf("serialising motif resources for %s: %w", app.Name, err) + } + resolved := strings.ReplaceAll(string(appYAML), "{{ .metadata.name }}", app.Name) + resolved = strings.ReplaceAll(resolved, "{{ .metadata.namespace }}", app.Namespace) + + var appResources map[string]interface{} + if err := yaml.Unmarshal([]byte(resolved), &appResources); err != nil { + return fmt.Errorf("parsing resolved resources for %s: %w", app.Name, err) + } + for key, val := range appResources { + items, ok := val.([]interface{}) + if !ok { + continue + } + merged[key] = append(merged[key], items...) + } + } + + // ── Deduplicate + sort namespaces ─────────────────────────────────────── + seen := map[string]bool{} + var uniqueNS []string + for _, app := range apps { + if app.Namespace != "" && !seen[app.Namespace] { + seen[app.Namespace] = true + uniqueNS = append(uniqueNS, app.Namespace) + } + } + for i := 0; i < len(uniqueNS); i++ { + for j := i + 1; j < len(uniqueNS); j++ { + if uniqueNS[i] > uniqueNS[j] { + uniqueNS[i], uniqueNS[j] = uniqueNS[j], uniqueNS[i] + } + } + } + var quotedNS []string + for _, ns := range uniqueNS { + quotedNS = append(quotedNS, fmt.Sprintf("%q", ns)) + } + + // ── Marshal merged resources ──────────────────────────────────────────── + mergedYAML, err := yaml.Marshal(merged) + if err != nil { + return fmt.Errorf("serialising merged resources: %w", err) + } + + // ── Build katalog YAML ────────────────────────────────────────────────── + author, _ := LastCommitAuthor() + if author == nil { + author = &GitAuthor{Raw: "unknown"} + } + + var b strings.Builder + b.WriteString("# Generated by ork doctor deploy — do not edit\n") + b.WriteString("apiVersion: orkestra.orkspace.io/v1\n") + b.WriteString("kind: Katalog\n") + b.WriteString("metadata:\n") + b.WriteString(" name: orkestra-developer\n") + b.WriteString(" description: \"Orkestra developer-path managed deployments\"\n") + b.WriteString(" createdBy: orkdoctor\n") + b.WriteString(" author: " + author.Raw + "\n") + + // Emit the projects block so the Control Center can present a developer view. + b.WriteString(" projects:\n") + for _, app := range apps { + b.WriteString(" " + app.Name + ":\n") + b.WriteString(" name: " + app.Name + "\n") + b.WriteString(" namespace: " + app.Namespace + "\n") + if app.Port != "" { + b.WriteString(" port: \"" + app.Port + "\"\n") + } + if app.Language != "" { + b.WriteString(" language: \"" + app.Language + "\"\n") + } + if app.Image != "" { + b.WriteString(" currentImage: \"" + app.Image + "\"\n") + } + } + b.WriteString("\n") + + if !opts.NoSecure { + b.WriteString("security:\n") + b.WriteString(" deletionProtection:\n") + b.WriteString(" enabled: true\n") + if opts.Clean { + b.WriteString(" cleanupOnShutdown: true\n") + } + b.WriteString("\n") + } + + b.WriteString("spec:\n") + b.WriteString(" crds:\n") + b.WriteString(" platform:\n") + b.WriteString(" apiTypes:\n") + b.WriteString(" kind: ConfigMap\n") + b.WriteString(" labelSelector:\n") + b.WriteString(" ork.io/platform: developer\n") + if len(quotedNS) > 0 { + b.WriteString(" allowedNamespaces: [" + strings.Join(quotedNS, ", ") + "]\n") + } + b.WriteString("\n") + b.WriteString(" operatorBox:\n") + b.WriteString(" onReconcile:\n") + b.WriteString(indent(string(mergedYAML), 10)) + + return os.WriteFile(filepath.Join(deployDir, "katalog.yaml"), []byte(b.String()), 0o644) +} + // ReadCRName reads the ConfigMap name from .orkestra/app.yaml. // Returns the name (e.g. "my-app-orkestra") so callers don't need to re-derive it. func ReadCRName(appYAML string) (string, error) { @@ -566,7 +1002,7 @@ func buildOrkestraValues(name string, notifyMe bool) string { if notifyMe { extraEnvFrom = ` # ── Notifications ───────────────────────────────────────────────────────────── -# orkestra-notification Secret is created by ork deploy when SMTP/Slack env +# orkestra-notification Secret is created by ork doctor deploy when SMTP/Slack env # vars are present. It injects credentials into the Orkestra runtime so # pkg/konfig reads them as normal env vars. runtime: @@ -577,10 +1013,10 @@ runtime: } _ = name return `# .orkestra/values.yaml — Orkestra cluster configuration -# Apply changes with: ork deploy --upgrade-orkestra +# Apply changes with: ork doctor deploy --upgrade-orkestra # # ── Control Center ──────────────────────────────────────────────────────────── -# Expose the Control Center externally so 'ork deploy' can show its URL. +# Expose the Control Center externally so 'ork doctor deploy' can show its URL. # After enabling, set controlCenterHost in .orkestra/app.yaml to the same host. # # controlCenter: diff --git a/pkg/doctor/helm.go b/pkg/doctor/helm.go index d9ea03c5..188184ce 100644 --- a/pkg/doctor/helm.go +++ b/pkg/doctor/helm.go @@ -6,7 +6,33 @@ import ( "os/exec" ) -func InstallOrUpgradeOrkestra(version, values string, upgrade bool) error { +// BuildControlCenterValues generates a temporary Helm values file that enables +// the Control Center ingress. Call only when controlCenterHost is non-empty. +// The caller is responsible for removing the returned file. +func BuildControlCenterValues(host string) (string, error) { + content := fmt.Sprintf(`controlCenter: + ingress: + enabled: true + hosts: + - host: %s + paths: + - path: / + pathType: Prefix +`, host) + tmp, err := os.CreateTemp("", "orkestra-cc-values-*.yaml") + if err != nil { + return "", err + } + if _, err := tmp.WriteString(content); err != nil { + tmp.Close() + os.Remove(tmp.Name()) + return "", err + } + tmp.Close() + return tmp.Name(), nil +} + +func InstallOrUpgradeOrkestra(version string, valueFiles []string, upgrade bool) error { // Always add repo (idempotent) repoAdd := exec.Command("helm", "repo", "add", Orkestra, OrkestraChartRepo) repoAdd.Stdout = os.Stdout @@ -42,8 +68,10 @@ func InstallOrUpgradeOrkestra(version, values string, upgrade bool) error { args = append(args, "--version", version) } - if values != "" { - args = append(args, "-f", values) + for _, f := range valueFiles { + if f != "" { + args = append(args, "-f", f) + } } // Run Helm diff --git a/pkg/doctor/kind.go b/pkg/doctor/kind.go index 9d154ecd..4f3adc22 100644 --- a/pkg/doctor/kind.go +++ b/pkg/doctor/kind.go @@ -16,7 +16,7 @@ import ( ) const ( - // KindClusterName is the default kind cluster created by `ork deploy --dev`. + // KindClusterName is the default kind cluster created by `ork doctor deploy --dev`. KindClusterName = "orkestra-playground" kindVersion = "v0.27.0" ) diff --git a/pkg/doctor/komposer.go b/pkg/doctor/komposer.go index 554622d4..e2f066dd 100644 --- a/pkg/doctor/komposer.go +++ b/pkg/doctor/komposer.go @@ -16,7 +16,7 @@ const ( RuntimeKatalogPath = "__runtime_katalog_do_not_edit.yml" ) -// GlobalKomposer is the structure of ~/.orkestra/deploy/komposer.yaml. +// GlobalKomposer is the structure of ~/.orkestra/doctor/deploy/komposer.yaml. // It aggregates Katalog paths from all deployed projects on this machine. type GlobalKomposer struct { APIVersion string `yaml:"apiVersion"` @@ -37,7 +37,7 @@ type KomposerSources struct { Files []string `yaml:"files,omitempty"` } -// GlobalKomposerPath returns ~/.orkestra/deploy/komposer.yaml. +// GlobalKomposerPath returns ~/.orkestra/doctor/deploy/komposer.yaml. func GlobalKomposerPath() (string, error) { dir, err := StateDir() if err != nil { diff --git a/pkg/doctor/notify.go b/pkg/doctor/notify.go index 74d74235..83d274eb 100644 --- a/pkg/doctor/notify.go +++ b/pkg/doctor/notify.go @@ -54,7 +54,7 @@ func BuildNotificationSecret(envMap map[string]string) string { b.WriteString(" namespace: " + OrkestraNamespace + "\n") b.WriteString(" labels:\n") b.WriteString(" app.kubernetes.io/managed-by: orkestra\n") - b.WriteString(" " + deletionProtectionLabel + ": true\n") + b.WriteString(" " + deletionProtectionLabel + ": \"true\"\n") b.WriteString("type: Opaque\n") b.WriteString("stringData:\n") diff --git a/pkg/doctor/state.go b/pkg/doctor/state.go index 8990bac4..f999af57 100644 --- a/pkg/doctor/state.go +++ b/pkg/doctor/state.go @@ -1,6 +1,8 @@ package doctor import ( + "crypto/sha256" + "encoding/hex" "encoding/json" "os" "os/exec" @@ -9,10 +11,18 @@ import ( "time" ) -// DeployState is the contents of ~/.orkestra/deploy/state.json. +// DeployState is the contents of ~/.orkestra/doctor/deploy/state.json. type DeployState struct { ClusterContext string `json:"clusterContext"` Projects map[string]*ProjectState `json:"projects"` + // KatalogHash is the SHA-256 of the last central developer katalog written. + // Used to detect changes without relying on git, since the katalog lives + // outside the project repo and is never committed. + KatalogHash string `json:"katalogHash,omitempty"` + // DirApps maps an absolute project directory to the ordered list of app names + // it manages. Used by multi-app compose projects so ork doctor deploy can reconstruct + // the full app list without reading .init.ork. + DirApps map[string][]string `json:"dirApps,omitempty"` } // ProjectState tracks one deployed project. @@ -23,15 +33,32 @@ type ProjectState struct { PreviousImage string `json:"previousImage,omitempty"` KatalogPath string `json:"katalogPath"` DeployedAt time.Time `json:"deployedAt"` + + // Developer path — persisted so the central katalog can be rebuilt on re-deploy. + AppData map[string]string `json:"appData,omitempty"` + Port string `json:"port,omitempty"` + Language string `json:"language,omitempty"` + GitCommit string `json:"gitCommit,omitempty"` + HasDockerfile bool `json:"hasDockerfile,omitempty"` + SecretCount int `json:"secretCount,omitempty"` + ConfigCount int `json:"configCount,omitempty"` + HasSecrets bool `json:"hasSecrets,omitempty"` + HasConfig bool `json:"hasConfig,omitempty"` + + // Init settings — replaces .orkestra/bundle/.init.ork. + // Written by ork doctor init, read by ork doctor deploy. + Dir string `json:"dir,omitempty"` // absolute project directory + UseCompose bool `json:"useCompose,omitempty"` // true when initialised from a compose file + ComposeFile string `json:"composeFile,omitempty"` // path to docker-compose.yaml } -// StateDir returns ~/.orkestra/deploy/ +// StateDir returns ~/.orkestra/doctor/deploy/ func StateDir() (string, error) { home, err := os.UserHomeDir() if err != nil { return "", err } - return filepath.Join(home, ".orkestra", "deploy"), nil + return filepath.Join(home, ".orkestra", "doctor", "deploy"), nil } // LoadState reads the state file. Returns an empty state if not found. @@ -102,6 +129,42 @@ func (s *DeployState) PreviousImage(appName string) string { return "" } +// DeployedAppNames returns a sorted list of app names recorded in state. +func (s *DeployState) DeployedAppNames() []string { + names := make([]string, 0, len(s.Projects)) + for name := range s.Projects { + names = append(names, name) + } + for i := 0; i < len(names); i++ { + for j := i + 1; j < len(names); j++ { + if names[i] > names[j] { + names[i], names[j] = names[j], names[i] + } + } + } + return names +} + +// MotifDir returns ~/.orkestra/apps/ — where per-app motif templates are stored. +// Motifs live here rather than in the project directory so developers never see them. +func MotifDir() (string, error) { + home, err := os.UserHomeDir() + if err != nil { + return "", err + } + return filepath.Join(home, ".orkestra", "apps"), nil +} + +// MotifPath returns the path to the motif template for a given app name. +// ~/.orkestra/apps//motif.yaml +func MotifPath(appName string) (string, error) { + base, err := MotifDir() + if err != nil { + return "", err + } + return filepath.Join(base, appName, "motif.yaml"), nil +} + // CurrentContext returns the active kubectl context name. func CurrentContext() string { out, err := exec.Command("kubectl", "config", "current-context").Output() @@ -110,3 +173,24 @@ func CurrentContext() string { } return strings.TrimSpace(string(out)) } + +// CentralKatalogChanged reads ~/.orkestra/doctor/deploy/katalog.yaml, hashes it, and +// compares with the hash stored in state. Returns true when the katalog is new +// or has changed since the last deploy. Persists the new hash to state so the +// next call returns false unless the content changes again. +// +// This replaces the git-diff-based KatalogChanged for the developer path, since +// the central katalog lives outside the project repo and is never committed. +func CentralKatalogChanged(state *DeployState, deployDir string) bool { + data, err := os.ReadFile(filepath.Join(deployDir, "katalog.yaml")) + if err != nil { + return true // assume changed if we can't read it + } + h := sha256.Sum256(data) + newHash := hex.EncodeToString(h[:]) + if state.KatalogHash == newHash { + return false + } + state.KatalogHash = newHash + return true +} diff --git a/pkg/katalog/cliMethods.go b/pkg/katalog/cliMethods.go index 3987e553..2baded7b 100644 --- a/pkg/katalog/cliMethods.go +++ b/pkg/katalog/cliMethods.go @@ -32,6 +32,12 @@ func (k *Katalog) ProjectInfo() orktypes.ProjectInfo { } } +// Projects returns the map of all project infos from the katalog metadata. +// Populated by the developer path (createdBy: orkdoctor) via ork doctor deploy. +func (k *Katalog) Projects() map[string]orktypes.ProjectInfo { + return k.metadata.Projects +} + // Exists returns true if a CRD with the given name exists in the katalog. func (k *Katalog) Exists(name string) bool { _, ok := k.Spec.CRDs[name] diff --git a/pkg/katalog/parser.go b/pkg/katalog/parser.go index 6f700204..86799d5a 100644 --- a/pkg/katalog/parser.go +++ b/pkg/katalog/parser.go @@ -142,6 +142,13 @@ func (k *Katalog) ValidateConfig(kfg *konfig.Konfig) (*Katalog, error) { return nil, err } + // ------------------------------------------------------------------------- + // 11a. Validate Probe Profiles + // ------------------------------------------------------------------------- + if err := k.validateProbeProfiles(); err != nil { + return nil, err + } + // ------------------------------------------------------------------------- // 12. Validate Autoscale Metrics Type // ------------------------------------------------------------------------- diff --git a/pkg/katalog/probe_profile.go b/pkg/katalog/probe_profile.go new file mode 100644 index 00000000..23eec1cf --- /dev/null +++ b/pkg/katalog/probe_profile.go @@ -0,0 +1,45 @@ +// Package katalog — Probe Profiles +// +// Named timing presets for Kubernetes probes (startup, liveness, readiness). +// Probe profiles control initialDelaySeconds, periodSeconds, and failureThreshold. +// They are validated at katalog load time — unknown profile names fail fast. +// +// Profiles DO NOT expand at load time (unlike resource profiles); timing values +// are resolved at reconcile time when the probe is built. Profiles validated here +// must match the map in pkg/orkestra-registry/common/probes.go. + +package katalog + +// ProbeProfile is a named set of probe timing parameters. +type ProbeProfile string + +const ( + // ProbeFast — quick detection, low tolerance. Good for HTTP APIs that + // start quickly and should fail loud on the first real problem. + // initialDelay: 5s, period: 10s, failureThreshold: 2 + ProbeFast ProbeProfile = "fast" + + // ProbeStandard — balanced defaults suitable for most web services. + // initialDelay: 15s, period: 20s, failureThreshold: 3 + ProbeStandard ProbeProfile = "standard" + + // ProbePatient — tolerant of slow operations. Good for batch workers or + // services with non-trivial startup that still finish within ~2 minutes. + // initialDelay: 30s, period: 30s, failureThreshold: 5 + ProbePatient ProbeProfile = "patient" + + // ProbeSlowStart — 5-minute startup window, designed for startup probes on + // JVM applications, databases, or other slow-initializing services. + // initialDelay: 0s, period: 10s, failureThreshold: 30 (= 300s window) + ProbeSlowStart ProbeProfile = "slow-start" +) + +// isValidProbeProfile reports whether p is a recognized probe profile name. +func isValidProbeProfile(p string) bool { + switch ProbeProfile(p) { + case ProbeFast, ProbeStandard, ProbePatient, ProbeSlowStart: + return true + default: + return false + } +} diff --git a/pkg/katalog/validate.go b/pkg/katalog/validate.go index 3b76cff2..08f16f97 100644 --- a/pkg/katalog/validate.go +++ b/pkg/katalog/validate.go @@ -456,18 +456,25 @@ func (k *Katalog) validateNamespaceProtection() error { // y = years (365d) func (k *Katalog) validateTimeDuration() error { for name, crd := range k.enabledCRDs { - if !crd.HasAnyHooks() || !crd.HasAnySecrets() { + if !crd.HasAnyHooks() { continue } - // Validate all declared sleep durations (discovered by pkg/types) + // Validate sleep durations across all resource types. + // Skip template expressions — those are resolved at runtime. for _, e := range crd.CollectSleepEntries() { + if strings.Contains(e.Duration, "{{") { + continue + } if _, err := orktypes.ParseTimeDuration(e.Duration); err != nil { return durationError(name, e.ResourceName, "sleep", e.Duration, err) } } // Validate secret durations (rotateAfter, TLS.validFor) + if !crd.HasAnySecrets() { + continue + } if crd.HasOnCreate() { for _, s := range crd.OperatorBox.OnCreate.Secrets { if s.RotateAfter != "" { diff --git a/pkg/katalog/validate_resource.go b/pkg/katalog/validate_resource.go index 494bc531..02db2407 100644 --- a/pkg/katalog/validate_resource.go +++ b/pkg/katalog/validate_resource.go @@ -1,97 +1,68 @@ // Resource Profile Validation // -// Resource profiles are computed presets. When a profile is declared, it must be -// the *only* resource input. Profiles expand into a complete -// ResourceRequirements struct during katalog enrichment, so mixing them with -// manual fields creates ambiguity. +// Resource profiles are computed presets. When a profile is declared under +// resources.profile, it must be the *only* resource input. Profiles expand +// into a complete ResourceRequirements struct during katalog enrichment, so +// mixing them with manual fields creates ambiguity. +// +// Validation uses the same visitor pattern as probe profile validation: +// CollectResourceProfileEntries iterates every hook phase and resource, +// surfacing entries where resources.profile is non-empty. // // Validation enforces: // // 1. Profile-only usage: -// `resources.profile` cannot appear alongside requests or limits. +// resources.profile cannot appear alongside requests or limits. // // 2. Known profile names: // Allowed: tiny, small, medium, large, burst, steady, compute-heavy, // memory-heavy. // -// 3. No partial overrides: -// Users cannot override parts of a profile (e.g., adding requests.cpu). -// -// 4. Expansion safety: -// The generated ResourceRequirements must contain valid requests and limits. -// -// 5. No cross-field mixing: -// Profiles cannot be combined with container-level overrides. -// -// Profiles are atomic and predictable. If a profile is set, it fully defines -// resource behavior for that operator. +// 3. Template expressions: +// Profile values containing "{{" are skipped at load time and validated +// at reconcile time instead. package katalog import ( "fmt" "strings" - - orktypes "github.com/orkspace/orkestra/pkg/types" ) -// validateResourceProfile ensures that resources.profile is used correctly. -// Runs before profile expansion. Profiles must be the only resource input. -func (k *Katalog) validateResourceProfile() error { - for name, crd := range k.enabledCRDs { - // No resources block → nothing to validate - if !crd.HasAnyHooks() { - continue - } - - // No Deployments, Replicasets, StatefulSet → nothing to validate - if !crd.NeedsResourceDecl() { - continue - } - - // No profile declared → nothing to validate - if !crd.HasResourceProfile() { - continue - } - - spec := crd.ResourceDecl() - profile := crd.ResourceProfile() - - // Rule 1: profile cannot be combined with manual resource fields - if !resourceIsProfileOnly(spec) { - return fmt.Errorf( - "resources.profile %q cannot be combined with manual resource fields; "+ - "remove requests/limits when using a profile", - profile, - ) - } +// isTemplateExpr reports whether s contains a Go template expression. +// Template expressions are resolved at runtime and should not be validated statically. +func isTemplateExpr(s string) bool { + return strings.Contains(s, "{{") +} - // Rule 2: profile must be recognized - if !isValidResourceProfile(profile) { - return fmt.Errorf("unknown resource profile: %q", profile) +// validateResourceProfile ensures that resources.profile is used correctly +// across all template resources in every hook phase. +// Uses the visitor pattern via CollectResourceProfileEntries. +func (k *Katalog) validateResourceProfile() error { + for crdName, crd := range k.enabledCRDs { + for _, e := range crd.CollectResourceProfileEntries() { + if isTemplateExpr(e.Profile) { + continue // resolved at runtime, skip static check + } + if !isValidResourceProfile(e.Profile) { + return fmt.Errorf( + "crd %q: %s %q (phase %s) has unknown resources.profile %q — "+ + "allowed: tiny, small, medium, large, burst, steady, compute-heavy, memory-heavy", + crdName, e.Resource, e.ResourceName, e.Phase, e.Profile, + ) + } + if e.Mixed { + return fmt.Errorf( + "crd %q: %s %q (phase %s) declares both resources.profile (%q) and "+ + "explicit requests/limits — use one or the other, not both", + crdName, e.Resource, e.ResourceName, e.Phase, e.Profile, + ) + } } - - // Save updated CRD - k.enabledCRDs[name] = crd } return nil } -// resourceIsProfileOnly returns true when the user has declared ONLY a profile -// and no manual resource fields. -func resourceIsProfileOnly(spec *orktypes.ResourceRequirements) bool { - if spec == nil { - return true - } - - // Any manual field invalidates profile usage - if len(spec.Requests) > 0 || len(spec.Limits) > 0 { - return false - } - - return true -} - // isValidResourceProfile returns true if the profile name is one of the supported presets. func isValidResourceProfile(p string) bool { switch strings.ToLower(p) { @@ -108,3 +79,31 @@ func isValidResourceProfile(p string) bool { return false } } + +// validateProbeProfiles checks that all probe profile names declared across all +// CRD hooks are recognized values. Unknown profiles fail fast at load time before +// any reconcile loop runs — same guarantee as resource profile validation. +func (k *Katalog) validateProbeProfiles() error { + for crdName, crd := range k.enabledCRDs { + for _, e := range crd.CollectProbeProfileEntries() { + if isTemplateExpr(e.Profile) { + continue // resolved at runtime, skip static check + } + if !isValidProbeProfile(e.Profile) { + return fmt.Errorf( + "crd %q: %s probe in %s %q (phase %s) has unknown probe profile %q — "+ + "allowed: fast, standard, patient, slow-start", + crdName, e.ProbeType, e.Resource, e.ResourceName, e.Phase, e.Profile, + ) + } + if e.Mixed { + return fmt.Errorf( + "crd %q: %s probe in %s %q (phase %s) declares both a profile (%q) and "+ + "explicit timing fields — use one or the other, not both", + crdName, e.ProbeType, e.Resource, e.ResourceName, e.Phase, e.Profile, + ) + } + } + } + return nil +} diff --git a/pkg/katalog/validation_autoscale.go b/pkg/katalog/validation_autoscale.go index c6241501..49a50fc8 100644 --- a/pkg/katalog/validation_autoscale.go +++ b/pkg/katalog/validation_autoscale.go @@ -38,8 +38,9 @@ import ( orktypes "github.com/orkspace/orkestra/pkg/types" ) -// validateAutoscaleProfile ensures that autoscale.profile is used correctly. -// Runs before profile expansion. Profiles must be the only autoscale input. +// validateAutoscaleProfile ensures that autoscale.profile is used correctly, +// then expands the named profile into a complete AutoscaleSpec so the runtime +// only ever sees a fully-formed spec (never a bare profile name). func (k *Katalog) validateAutoscaleProfile() error { for name, crd := range k.enabledCRDs { spec := crd.OperatorBox.Autoscale @@ -70,6 +71,19 @@ func (k *Katalog) validateAutoscaleProfile() error { return fmt.Errorf("unknown autoscale profile: %q", profile) } + // Expand the profile into a fully-formed AutoscaleSpec using the CRD's + // declared workers and queue depth as the baseline. + baseline := orktypes.AutoscaleBaseline{ + Workers: crd.Workers, + QueueDepth: crd.Queue.MaxQueueDepth, + Resync: crd.Resync, + } + expanded, err := ApplyAutoscalerProfile(profile, baseline) + if err != nil { + return fmt.Errorf("autoscale.profile %q expansion failed: %w", profile, err) + } + crd.OperatorBox.Autoscale = expanded + k.enabledCRDs[name] = crd } return nil diff --git a/pkg/konfig/katalog.go b/pkg/konfig/katalog.go index 20e6c058..9cc15bdb 100644 --- a/pkg/konfig/katalog.go +++ b/pkg/konfig/katalog.go @@ -43,10 +43,18 @@ func IsKomposerKind(kind string) bool { return kind == kindKomposer } -// IsValidDocumentKind returns true if the kind is either Katalog or Komposer. -// Used by parseKatalogDoc to accept both kinds before dispatching. +// IsValidDocumentKind reports whether the given kind is one of the supported +// Orkestra document kinds. func IsValidDocumentKind(kind string) bool { - return kind == kindKatalog || kind == kindKomposer + return kind == kindKatalog || + kind == kindKomposer || + kind == kindMotif +} + +// ValidKindsString returns a comma‑separated list of all supported document kinds. +// Useful for error messages and CLI diagnostics. +func ValidKindsString() string { + return "Katalog, Komposer, Motif" } // IsValidApiVersion returns true if the given apiVersion is a supported version. diff --git a/pkg/kordinator/crd_health_handers.go b/pkg/kordinator/crd_health_handers.go index ba985916..3f3f5372 100644 --- a/pkg/kordinator/crd_health_handers.go +++ b/pkg/kordinator/crd_health_handers.go @@ -457,23 +457,23 @@ func BuildCRDInfoHandler( // ───────────────────────────────────────────────────────────────────────────── type KatalogResponse struct { - CRDs []CRDSummaryResponse `json:"crds"` - Total int `json:"total"` - TotalEnabled int `json:"totalEnabled"` - OrkReady bool `json:"OrkReady"` - DeletionProtection bool `json:"deletionProtection"` - Healthy bool `json:"healthy"` - Status int `json:"status"` - DegradedReason string `json:"degradedReason,omitempty"` - StatusCounts StatusCounts `json:"statusCounts"` - Name string `json:"name,omitempty"` - Version string `json:"version,omitempty"` - CreatedBy string `json:"createdBy,omitempty"` - Author string `json:"author,omitempty"` - Description string `json:"description,omitempty"` - License string `json:"license,omitempty"` - RuntimeVersion string `json:"runtimeVersion,omitempty"` - ProjectInfo orktypes.ProjectInfo `json:"projectInfo,omitempty"` + CRDs []CRDSummaryResponse `json:"crds"` + Total int `json:"total"` + TotalEnabled int `json:"totalEnabled"` + OrkReady bool `json:"OrkReady"` + DeletionProtection bool `json:"deletionProtection"` + Healthy bool `json:"healthy"` + Status int `json:"status"` + DegradedReason string `json:"degradedReason,omitempty"` + StatusCounts StatusCounts `json:"statusCounts"` + Name string `json:"name,omitempty"` + Version string `json:"version,omitempty"` + CreatedBy string `json:"createdBy,omitempty"` + Author string `json:"author,omitempty"` + Description string `json:"description,omitempty"` + License string `json:"license,omitempty"` + RuntimeVersion string `json:"runtimeVersion,omitempty"` + Projects map[string]orktypes.ProjectInfo `json:"projects,omitempty"` } type CRDSummaryResponse struct { @@ -669,7 +669,7 @@ func BuildKatalogHandler( CreatedBy: kat.Meta().CreatedBy, License: kat.Meta().License, Description: kat.Meta().Description, - ProjectInfo: kat.ProjectInfo(), + Projects: kat.Projects(), RuntimeVersion: version.Short(), }) } diff --git a/pkg/motif/orkestra-motifs/deployment-stack/motif.yaml b/pkg/motif/orkestra-motifs/deployment-stack/motif.yaml deleted file mode 100644 index af04bc6b..00000000 --- a/pkg/motif/orkestra-motifs/deployment-stack/motif.yaml +++ /dev/null @@ -1,142 +0,0 @@ -apiVersion: orkestra.orkspace.io/v1 -kind: Motif -metadata: - name: deployment-stack - version: v1 - description: > - Full application deployment stack: ServiceAccount, Role, RoleBinding, - Deployment, Service, HPA, PDB, and optional Ingress. - All inputs are optional except image, port, name, and namespace. - Ingress is only created when the CR data.host field is non-empty. - author: orkspace - license: Apache-2.0 - -inputs: - - name: name - required: true - description: Resource name prefix. Pass the runtime expression for metadata.name from the katalog with block. - - - name: namespace - required: true - description: Target namespace. Pass the runtime expression for metadata.namespace from the katalog with block. - - - name: image - required: true - description: Container image (e.g. ghcr.io/myorg/myapp:latest) - - - name: port - required: true - description: Container port the application listens on (e.g. 8080) - - - name: replicas - default: "2" - description: Desired replica count - - - name: maxReplicas - default: "10" - description: Maximum replicas for HPA scale-out - - - name: resourceProfile - default: "burst" - description: Orkestra resource profile (burst, standard, optimized) - - - name: ingressClass - default: "nginx" - description: Ingress class name (nginx, traefik, kong, etc.) - - - name: host - default: "" - description: > - Public hostname for Ingress (e.g. myapp.example.com). - When empty the Ingress resource is present but the when condition - prevents it from being created until data.host is set in the CR. - -resources: - - - namespaces: - - name: ${{ .inputs.namespace }} - reconcile: true - - serviceAccounts: - - name: '{{ .inputs.name }}-sa' - namespace: '{{ .inputs.namespace }}' - reconcile: true - - roles: - - name: '{{ .inputs.name }}-role' - namespace: '{{ .inputs.namespace }}' - reconcile: true - rules: - - apiGroups: ["apps"] - resources: ["deployments"] - verbs: ["get", "list", "watch", "update", "patch"] - resourceNames: - - '{{ .inputs.name }}' - - roleBindings: - - name: '{{ .inputs.name }}-rolebinding' - namespace: '{{ .inputs.namespace }}' - reconcile: true - roleRef: - name: '{{ .inputs.name }}-role' - subjects: - - kind: ServiceAccount - name: '{{ .inputs.name }}-sa' - namespace: '{{ .inputs.namespace }}' - - deployments: - - name: '{{ .inputs.name }}' - namespace: '{{ .inputs.namespace }}' - image: '{{ .inputs.image }}' - replicas: '{{ .inputs.replicas }}' - port: '{{ .inputs.port }}' - serviceAccountName: '{{ .inputs.name }}-sa' - resourceProfile: '{{ .inputs.resourceProfile }}' - reconcile: true - when: - - field: data.image - exists: true - - services: - - name: '{{ .inputs.name }}-svc' - namespace: '{{ .inputs.namespace }}' - port: '{{ .inputs.port }}' - targetPort: '{{ .inputs.port }}' - reconcile: true - - ingresses: - - name: '{{ .inputs.name }}-ingress' - namespace: '{{ .inputs.namespace }}' - host: '{{ .inputs.host }}' - serviceName: '{{ .inputs.name }}-svc' - servicePort: '{{ .inputs.port }}' - ingressClass: '{{ .inputs.ingressClass }}' - reconcile: true - when: - - field: data.host - exists: true - - hpa: - - name: '{{ .inputs.name }}-hpa' - namespace: '{{ .inputs.namespace }}' - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: '{{ .inputs.name }}' - minReplicas: '{{ .inputs.replicas }}' - maxReplicas: '{{ .inputs.maxReplicas }}' - targetCPUUtilizationPercentage: "70" - reconcile: true - when: - - field: data.image - exists: true - - pdb: - - name: '{{ .inputs.name }}-pdb' - namespace: '{{ .inputs.namespace }}' - minAvailable: "1" - reconcile: true - when: - - field: data.image - exists: true diff --git a/pkg/motif/orkestra-motifs/redis/motif.yaml b/pkg/motif/orkestra-motifs/redis/motif.yaml deleted file mode 100644 index 3b7c847c..00000000 --- a/pkg/motif/orkestra-motifs/redis/motif.yaml +++ /dev/null @@ -1,83 +0,0 @@ -apiVersion: orkestra.orkspace.io/v1 -kind: Motif -metadata: - name: redis - version: v7 - description: > - Redis StatefulSet with optional PVC, headless Service, and Redis Commander - management UI. Works with redis:6 through redis:7. - author: orkspace - license: Apache-2.0 - -inputs: - - name: image - description: Redis image (e.g. redis:7.2-alpine) - required: true - - - name: volumeSize - description: PVC storage size (omit for ephemeral) - required: false - - - name: replicas - description: Number of replicas - default: "1" - - - name: resourceProfile - description: CPU/memory profile (burst, standard, optimized) - default: "burst" - - - name: commanderImage - description: Redis Commander management UI image - default: "rediscommander/redis-commander:latest" - -resources: - statefulSets: - - name: "{{ .metadata.name }}-redis" - image: "{{ .inputs.image }}" - replicas: "{{ .inputs.replicas }}" - serviceName: "{{ .metadata.name }}-redis-headless" - port: 6379 - # volumeClaims: - # - name: data - # size: "{{ .inputs.volumeSize }}" - # mountPath: /data - # when: - # - field: inputs.volumeSize - # exists: true - resourceProfile: "{{ .inputs.resourceProfile }}" - reconcile: true - - services: - - name: "{{ .metadata.name }}-redis-headless" - headless: true - port: 6379 - targetPort: 6379 - reconcile: true - - name: "{{ .metadata.name }}-redis" - port: 6379 - targetPort: 6379 - reconcile: true - - name: "{{ .metadata.name }}-commander-svc" - port: 8081 - targetPort: 8081 - type: LoadBalancer - reconcile: true - - deployments: - - name: "{{ .metadata.name }}-commander" - image: "{{ .inputs.commanderImage }}" - env: - REDIS_HOSTS: - value: "{{ .metadata.name }}-redis:6379" - port: 8081 - resourceProfile: "{{ .inputs.resourceProfile }}" - reconcile: true - -status: - fields: - - path: redisReady - value: "{{ AllReplicasReady .children.statefulset }}" - - path: connectionString - value: "redis://{{ .metadata.name }}-redis.{{ .metadata.namespace }}.svc.cluster.local:6379" - - path: commanderUrl - value: "http://{{ .metadata.name }}-commander-svc.{{ .metadata.namespace }}.svc.cluster.local:8081" \ No newline at end of file diff --git a/pkg/notification/docs/04-developer-notifications.md b/pkg/notification/docs/04-developer-notifications.md index 1e01420f..ec57400f 100644 --- a/pkg/notification/docs/04-developer-notifications.md +++ b/pkg/notification/docs/04-developer-notifications.md @@ -31,7 +31,7 @@ operatorBox: message: > {{ .metadata.name }} is deploying but replicas are not ready yet. Check logs: kubectl logs -n {{ .metadata.namespace }} -l ork.io/app={{ .metadata.name }} --tail=50 - | Roll back if stuck: ork deploy rollback + | Roll back if stuck: ork doctor deploy rollback ``` The `replicasReady .children.deployment` check evaluates to `"false"` whenever the @@ -79,7 +79,7 @@ SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS / SMTP_FROM SLACK_WEBHOOK_URL ``` -`ork deploy` creates and applies this Secret automatically when `.env` contains +`ork doctor deploy` creates and applies this Secret automatically when `.env` contains `SMTP_*` or `SLACK_*` variables. --- @@ -95,7 +95,7 @@ To: alex@example.com my-api is deploying but replicas are not ready yet. Check logs: kubectl logs -n my-api-orkestra-ns -l ork.io/app=my-api --tail=50 -Roll back if stuck: ork deploy rollback +Roll back if stuck: ork doctor deploy rollback ``` **Slack** (when SLACK_WEBHOOK_URL is configured): @@ -103,7 +103,7 @@ Roll back if stuck: ork deploy rollback ``` my-api is deploying but replicas are not ready yet. Check logs: kubectl logs -n my-api-orkestra-ns -l ork.io/app=my-api --tail=50 -Roll back if stuck: ork deploy rollback +Roll back if stuck: ork doctor deploy rollback [Katalog: my-api] [Team: developer] ``` diff --git a/pkg/orkestra-registry/common/methods.go b/pkg/orkestra-registry/common/methods.go index 806fd4a4..e4a16abb 100644 --- a/pkg/orkestra-registry/common/methods.go +++ b/pkg/orkestra-registry/common/methods.go @@ -2,11 +2,26 @@ package common import ( "github.com/orkspace/orkestra/domain" + "github.com/orkspace/orkestra/pkg/logger" orktypes "github.com/orkspace/orkestra/pkg/types" corev1 "k8s.io/api/core/v1" "k8s.io/apimachinery/pkg/api/resource" ) +// BuildResourceRequirements converts an Orkestra ResourceRequirements spec into a +// Kubernetes corev1.ResourceRequirements object. +// +// The input uses plain string quantities (e.g. "100m", "256Mi") for both +// requests and limits. This helper parses those values into resource.Quantity +// and populates the corresponding ResourceList fields. +// +// Keys are preserved exactly as provided (e.g. "cpu", "memory", +// "ephemeral-storage", vendor-specific resources). Unknown or extended resource +// names are passed through without modification. +// +// This function is the canonical, shared implementation used by all resource +// builders (Deployments, StatefulSets, Jobs, HPAs, etc.) to ensure consistent, +// Kubernetes‑native resource handling across Orkestra. func BuildResourceRequirements(r *orktypes.ResourceRequirements) corev1.ResourceRequirements { req := corev1.ResourceRequirements{ Requests: corev1.ResourceList{}, @@ -32,6 +47,45 @@ func ResolveNamespace(owner domain.Object, namespace string) string { return "default" } +// ResolveResources resolves resource requirements: if resources.profile is set +// it expands to explicit requests/limits; otherwise the block is returned as-is. +// Returns nil when neither profile nor explicit values are declared. +func ResolveResources(r *orktypes.ResourceRequirements) *orktypes.ResourceRequirements { + if r == nil { + return nil + } + if r.Profile != "" { + expanded, err := ExpandResourceProfile(r.Profile) + if err != nil { + logger.Warn().Str("profile", r.Profile).Err(err).Msg("unknown resources.profile — skipping") + return nil + } + return expanded + } + if len(r.Requests) == 0 && len(r.Limits) == 0 { + return nil + } + return r +} + +// ResourceRequirementsEqual reports whether two ResourceRequirements are equivalent. +func ResourceRequirementsEqual(a, b corev1.ResourceRequirements) bool { + return resourceListEqual(a.Requests, b.Requests) && resourceListEqual(a.Limits, b.Limits) +} + +func resourceListEqual(a, b corev1.ResourceList) bool { + if len(a) != len(b) { + return false + } + for k, va := range a { + vb, ok := b[k] + if !ok || va.Cmp(vb) != 0 { + return false + } + } + return true +} + // ToPullSecrets converts a slice of string to a []corev1.LocalObjectReference // Acceptable as Pull secrets func ToPullSecrets(names []string) []corev1.LocalObjectReference { diff --git a/pkg/orkestra-registry/common/parse.go b/pkg/orkestra-registry/common/parse.go index ced1ca5a..16b96b66 100644 --- a/pkg/orkestra-registry/common/parse.go +++ b/pkg/orkestra-registry/common/parse.go @@ -2,6 +2,7 @@ package common import ( "fmt" + "strings" "time" orktypes "github.com/orkspace/orkestra/pkg/types" @@ -24,6 +25,56 @@ func ParsePort(s string) int { return p } +// ExpandResourceProfile converts a named resource profile into a +// ResourceRequirements struct. Returns an error for unknown profile names. +// Profiles: tiny, small, medium, large, burst, steady, compute-heavy, memory-heavy. +func ExpandResourceProfile(profile string) (*orktypes.ResourceRequirements, error) { + switch strings.ToLower(profile) { + case "tiny": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "25m", "memory": "64Mi"}, + Limits: map[string]string{"cpu": "100m", "memory": "128Mi"}, + }, nil + case "small": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "100m", "memory": "128Mi"}, + Limits: map[string]string{"cpu": "500m", "memory": "512Mi"}, + }, nil + case "medium": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "250m", "memory": "256Mi"}, + Limits: map[string]string{"cpu": "1", "memory": "1Gi"}, + }, nil + case "large": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "500m", "memory": "512Mi"}, + Limits: map[string]string{"cpu": "2", "memory": "2Gi"}, + }, nil + case "burst": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "200m", "memory": "256Mi"}, + Limits: map[string]string{"cpu": "2", "memory": "2Gi"}, + }, nil + case "steady": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "300m", "memory": "256Mi"}, + Limits: map[string]string{"cpu": "600m", "memory": "512Mi"}, + }, nil + case "compute-heavy": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "1", "memory": "512Mi"}, + Limits: map[string]string{"cpu": "2", "memory": "1Gi"}, + }, nil + case "memory-heavy": + return &orktypes.ResourceRequirements{ + Requests: map[string]string{"cpu": "250m", "memory": "1Gi"}, + Limits: map[string]string{"cpu": "500m", "memory": "2Gi"}, + }, nil + default: + return nil, fmt.Errorf("unknown resource profile: %q", profile) + } +} + // SleepIfNeeded parses an extended duration string and sleeps if non-zero. // Used by all operatorBox resources to inject artificial latency for // autoscaling tests, chaos engineering, and latency simulation. diff --git a/pkg/orkestra-registry/common/probes.go b/pkg/orkestra-registry/common/probes.go new file mode 100644 index 00000000..1a340d8c --- /dev/null +++ b/pkg/orkestra-registry/common/probes.go @@ -0,0 +1,112 @@ +// pkg/orkestra-registry/common/probes.go +package common + +import ( + corev1 "k8s.io/api/core/v1" + "k8s.io/apimachinery/pkg/util/intstr" + + orktypes "github.com/orkspace/orkestra/pkg/types" +) + +// probeTimings holds timing parameters for a probe profile. +type probeTimings struct { + InitialDelaySeconds int32 + PeriodSeconds int32 + FailureThreshold int32 + SuccessThreshold int32 + TimeoutSeconds int32 +} + +// probeProfiles maps profile names to their timing configuration. +// +// - fast: quick detection, low tolerance — good for responsive HTTP APIs +// - standard: balanced defaults — suitable for most web services +// - patient: tolerant of slow operations — good for batch workers +// - slow-start: 5-minute startup window — designed for startup probes on heavy apps +var probeProfiles = map[string]probeTimings{ + "fast": {InitialDelaySeconds: 5, PeriodSeconds: 10, FailureThreshold: 2, SuccessThreshold: 1, TimeoutSeconds: 5}, + "standard": {InitialDelaySeconds: 15, PeriodSeconds: 20, FailureThreshold: 3, SuccessThreshold: 1, TimeoutSeconds: 10}, + "patient": {InitialDelaySeconds: 30, PeriodSeconds: 30, FailureThreshold: 5, SuccessThreshold: 1, TimeoutSeconds: 10}, + "slow-start": {InitialDelaySeconds: 0, PeriodSeconds: 10, FailureThreshold: 30, SuccessThreshold: 1, TimeoutSeconds: 10}, +} + +var defaultTimings = probeTimings{InitialDelaySeconds: 15, PeriodSeconds: 20, FailureThreshold: 3, SuccessThreshold: 1, TimeoutSeconds: 10} + +// BuildProbe constructs a Kubernetes Probe from a ProbeConfig. +// containerPort is used as the probe target when cfg.Port is 0. +// Returns nil if cfg is nil or no probe type can be inferred. +func BuildProbe(cfg *orktypes.ProbeConfig, containerPort int32) *corev1.Probe { + if cfg == nil { + return nil + } + + isHTTP := cfg.Type == "http" || (cfg.Type == "" && cfg.Path != "") + isTCP := cfg.Type == "tcp" + + if !isHTTP && !isTCP { + return nil + } + + t := defaultTimings + if pt, ok := probeProfiles[cfg.Profile]; ok { + t = pt + } + + if cfg.InitialDelaySeconds != nil { + t.InitialDelaySeconds = *cfg.InitialDelaySeconds + } + if cfg.PeriodSeconds != nil { + t.PeriodSeconds = *cfg.PeriodSeconds + } + if cfg.FailureThreshold != nil { + t.FailureThreshold = *cfg.FailureThreshold + } + if cfg.SuccessThreshold != nil { + t.SuccessThreshold = *cfg.SuccessThreshold + } + if cfg.TimeoutSeconds != nil { + t.TimeoutSeconds = *cfg.TimeoutSeconds + } + + port := containerPort + if cfg.Port > 0 { + port = cfg.Port + } + + probe := &corev1.Probe{ + InitialDelaySeconds: t.InitialDelaySeconds, + PeriodSeconds: t.PeriodSeconds, + FailureThreshold: t.FailureThreshold, + SuccessThreshold: t.SuccessThreshold, + TimeoutSeconds: t.TimeoutSeconds, + } + + if isHTTP { + probe.ProbeHandler = corev1.ProbeHandler{ + HTTPGet: &corev1.HTTPGetAction{ + Path: cfg.Path, + Port: intstr.FromInt32(port), + }, + } + } else { + probe.ProbeHandler = corev1.ProbeHandler{ + TCPSocket: &corev1.TCPSocketAction{ + Port: intstr.FromInt32(port), + }, + } + } + + return probe +} + +// ApplyProbes sets startup, liveness, and readiness probes on c. +// containerPort is used for probes that do not declare their own port. +// No-op when probes is nil. +func ApplyProbes(c *corev1.Container, probes *orktypes.ProbesConfig, containerPort int32) { + if probes == nil { + return + } + c.StartupProbe = BuildProbe(probes.Startup, containerPort) + c.LivenessProbe = BuildProbe(probes.Liveness, containerPort) + c.ReadinessProbe = BuildProbe(probes.Readiness, containerPort) +} diff --git a/pkg/orkestra-registry/configmaps/configmap.go b/pkg/orkestra-registry/configmaps/configmap.go index 542a2f5d..4944071e 100644 --- a/pkg/orkestra-registry/configmaps/configmap.go +++ b/pkg/orkestra-registry/configmaps/configmap.go @@ -275,6 +275,7 @@ func Resolve(src orktypes.ConfigMapTemplateSource, ownerName string) ResolvedCon FromConfigMap: src.FromConfigMap, FromNamespace: src.FromNamespace, Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/cronjobs/cronjob.go b/pkg/orkestra-registry/cronjobs/cronjob.go index 716bec98..ff250878 100644 --- a/pkg/orkestra-registry/cronjobs/cronjob.go +++ b/pkg/orkestra-registry/cronjobs/cronjob.go @@ -65,6 +65,9 @@ type ResolvedCronJobSpec struct { // Labels — applied to CronJob and pod metadata. Labels map[string]string + // Resources — CPU and memory requests/limits. nil means no limits set. + Resources *orktypes.ResourceRequirements + // ImagePullSecrets is an optional list of references to secrets in the same namespace to use // for pulling any of the images used by this PodSpec. // If specified, these secrets will be passed to individual puller implementations for them to use. @@ -205,6 +208,14 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec container.Args = spec.Args drifted = true } + if spec.Resources != nil { + desiredRes := common.BuildResourceRequirements(spec.Resources) + if !common.ResourceRequirementsEqual(container.Resources, desiredRes) { + container.Resources = desiredRes + drifted = true + logger.Info().Str("cronjob", spec.Name).Msg("cronjob resources drifted") + } + } } if !drifted { @@ -287,6 +298,8 @@ func Resolve(src orktypes.CronJobTemplateSource, ownerName string) ResolvedCronJ Command: src.Command, Args: src.Args, Labels: make(map[string]string), + Resources: common.ResolveResources(src.Resources), + Sleep: src.Sleep, } if spec.Name == "" { @@ -387,12 +400,7 @@ func buildCronJob(owner domain.Object, spec ResolvedCronJobSpec, namespace strin ImagePullSecrets: common.ToPullSecrets(spec.ImagePullSecrets), RestartPolicy: corev1.RestartPolicyOnFailure, Containers: []corev1.Container{ - { - Name: spec.Name, - Image: spec.Image, - Command: spec.Command, - Args: spec.Args, - }, + buildContainer(spec), }, }, }, @@ -404,6 +412,19 @@ func buildCronJob(owner domain.Object, spec ResolvedCronJobSpec, namespace strin return cj } +func buildContainer(spec ResolvedCronJobSpec) corev1.Container { + c := corev1.Container{ + Name: spec.Name, + Image: spec.Image, + Command: spec.Command, + Args: spec.Args, + } + if spec.Resources != nil { + c.Resources = common.BuildResourceRequirements(spec.Resources) + } + return c +} + func validateSpec(spec ResolvedCronJobSpec) error { var missing []string if spec.Name == "" { diff --git a/pkg/orkestra-registry/deployments/deployment.go b/pkg/orkestra-registry/deployments/deployment.go index 21576676..b692f3e5 100644 --- a/pkg/orkestra-registry/deployments/deployment.go +++ b/pkg/orkestra-registry/deployments/deployment.go @@ -89,6 +89,7 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec drifted := false updated := existing.DeepCopy() + // Replicas if existing.Spec.Replicas == nil || *existing.Spec.Replicas != spec.Replicas { replicas := spec.Replicas updated.Spec.Replicas = &replicas @@ -99,6 +100,7 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec Msg("deployment replicas drifted") } + // Image if len(existing.Spec.Template.Spec.Containers) > 0 && existing.Spec.Template.Spec.Containers[0].Image != spec.Image { updated.Spec.Template.Spec.Containers[0].Image = spec.Image @@ -109,6 +111,22 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec Msg("deployment image drifted") } + // Resources + if spec.Resources != nil { + desiredRes := common.BuildResourceRequirements(spec.Resources) + var existingRes corev1.ResourceRequirements + if len(existing.Spec.Template.Spec.Containers) > 0 { + existingRes = existing.Spec.Template.Spec.Containers[0].Resources + } + if !common.ResourceRequirementsEqual(existingRes, desiredRes) { + updated.Spec.Template.Spec.Containers[0].Resources = desiredRes + drifted = true + logger.Info(). + Str("deployment", spec.Name). + Msg("deployment resources drifted") + } + } + if !drifted { logger.Debug(). Str("deployment", spec.Name). @@ -189,11 +207,13 @@ func Resolve(src orktypes.DeploymentTemplateSource, staticReplicas int, ownerNam Name: src.Name, Image: src.Image, Namespace: src.Namespace, - Resources: src.Resources, + Resources: common.ResolveResources(src.Resources), Labels: make(map[string]string), Annotations: make(map[string]string), Env: make(map[string]orktypes.EnvVarSource), EnvFrom: src.EnvFrom, + Probes: src.Probes, + Sleep: src.Sleep, } // Default name @@ -306,6 +326,9 @@ func buildDeployment(owner domain.Object, spec ResolvedDeploymentSpec, namespace d.Spec.Template.Spec.Containers[0].Resources = common.BuildResourceRequirements(spec.Resources) } + // Probes + common.ApplyProbes(&d.Spec.Template.Spec.Containers[0], spec.Probes, spec.Port) + // Env if len(spec.Env) > 0 { d.Spec.Template.Spec.Containers[0].Env = []corev1.EnvVar{} diff --git a/pkg/orkestra-registry/deployments/types.go b/pkg/orkestra-registry/deployments/types.go index d366a616..a5eed92a 100644 --- a/pkg/orkestra-registry/deployments/types.go +++ b/pkg/orkestra-registry/deployments/types.go @@ -53,6 +53,9 @@ type ResolvedDeploymentSpec struct { // If specified, these secrets will be passed to individual puller implementations for them to use. ImagePullSecrets []string + // Probes — startup, liveness, and readiness probe configuration. + Probes *orktypes.ProbesConfig + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). diff --git a/pkg/orkestra-registry/hpas/hpa.go b/pkg/orkestra-registry/hpas/hpa.go index 2e4cc55c..de99b075 100644 --- a/pkg/orkestra-registry/hpas/hpa.go +++ b/pkg/orkestra-registry/hpas/hpa.go @@ -176,6 +176,7 @@ func Resolve(src orktypes.HPATemplateSource, ownerName string) ResolvedHPASpec { MinReplicas: 1, MaxReplicas: 1, Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/ingresses/ingress.go b/pkg/orkestra-registry/ingresses/ingress.go index 3b6096f1..73c49cde 100644 --- a/pkg/orkestra-registry/ingresses/ingress.go +++ b/pkg/orkestra-registry/ingresses/ingress.go @@ -196,6 +196,7 @@ func Resolve(src orktypes.IngressTemplateSource, ownerName string) ResolvedIngre IngressClass: src.IngressClass, Labels: make(map[string]string), Annotations: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/jobs/job.go b/pkg/orkestra-registry/jobs/job.go index 3affaae7..30019b34 100644 --- a/pkg/orkestra-registry/jobs/job.go +++ b/pkg/orkestra-registry/jobs/job.go @@ -47,6 +47,9 @@ type ResolvedJobSpec struct { // If specified, these secrets will be passed to individual puller implementations for them to use. ImagePullSecrets []string + // Resources — CPU and memory requests/limits. nil means no limits set. + Resources *orktypes.ResourceRequirements + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). @@ -141,6 +144,8 @@ func Resolve(src orktypes.JobTemplateSource, backoffLimit int, ownerName string) Args: src.Args, BackoffLimit: backoffLimit, Labels: make(map[string]string), + Resources: common.ResolveResources(src.Resources), + Sleep: src.Sleep, } if spec.Name == "" { @@ -172,6 +177,9 @@ func buildJob(owner domain.Object, spec ResolvedJobSpec, namespace string) *batc Command: spec.Command, Args: spec.Args, } + if spec.Resources != nil { + container.Resources = common.BuildResourceRequirements(spec.Resources) + } job := &batchv1.Job{ ObjectMeta: metav1.ObjectMeta{ diff --git a/pkg/orkestra-registry/namespaces/namespace.go b/pkg/orkestra-registry/namespaces/namespace.go index b10d5416..9ee5bd9a 100644 --- a/pkg/orkestra-registry/namespaces/namespace.go +++ b/pkg/orkestra-registry/namespaces/namespace.go @@ -130,6 +130,7 @@ func Resolve(src orktypes.NamespaceTemplateSource, ownerName string) ResolvedNam Name: src.Name, Labels: make(map[string]string), Finalizers: src.Finalizers, + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/pdbs/pdb.go b/pkg/orkestra-registry/pdbs/pdb.go index 219eb401..e4fd948e 100644 --- a/pkg/orkestra-registry/pdbs/pdb.go +++ b/pkg/orkestra-registry/pdbs/pdb.go @@ -176,6 +176,7 @@ func Resolve(src orktypes.PDBTemplateSource, ownerName string) ResolvedPDBSpec { MaxUnavailable: src.MaxUnavailable, Selector: make(map[string]string), Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/pods/pod.go b/pkg/orkestra-registry/pods/pod.go index c0c5be7d..77ee5115 100644 --- a/pkg/orkestra-registry/pods/pod.go +++ b/pkg/orkestra-registry/pods/pod.go @@ -83,13 +83,27 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec return fmt.Errorf("pod.Update: getting pod %q: %w", spec.Name, err) } + needsRecreate := false if len(existing.Spec.Containers) > 0 && existing.Spec.Containers[0].Image != spec.Image { logger.Info(). Str("pod", spec.Name). Str("current", existing.Spec.Containers[0].Image). Str("desired", spec.Image). Msg("pod image drifted — deleting and recreating") - + needsRecreate = true + } + if !needsRecreate && spec.Resources != nil { + desiredRes := common.BuildResourceRequirements(spec.Resources) + var existingRes corev1.ResourceRequirements + if len(existing.Spec.Containers) > 0 { + existingRes = existing.Spec.Containers[0].Resources + } + if !common.ResourceRequirementsEqual(existingRes, desiredRes) { + logger.Info().Str("pod", spec.Name).Msg("pod resources drifted — deleting and recreating") + needsRecreate = true + } + } + if needsRecreate { if err := Delete(ctx, kube, owner, spec); err != nil { return err } @@ -176,6 +190,8 @@ func Resolve(src orktypes.PodTemplateSource, ownerName string) ResolvedPodSpec { spec.Image = src.Image spec.Namespace = src.Namespace spec.Resources = src.Resources + spec.Probes = src.Probes + spec.Sleep = src.Sleep if src.Port != "" { spec.Port = common.ParsePort(src.Port) @@ -238,6 +254,8 @@ func buildPod(owner domain.Object, spec ResolvedPodSpec, namespace string) *core pod.Spec.Containers[0].Resources = common.BuildResourceRequirements(spec.Resources) } + common.ApplyProbes(&pod.Spec.Containers[0], spec.Probes, int32(spec.Port)) + return pod } diff --git a/pkg/orkestra-registry/pods/types.go b/pkg/orkestra-registry/pods/types.go index b1528c6b..63c385b3 100644 --- a/pkg/orkestra-registry/pods/types.go +++ b/pkg/orkestra-registry/pods/types.go @@ -47,6 +47,9 @@ type ResolvedPodSpec struct { // If specified, these secrets will be passed to individual puller implementations for them to use. ImagePullSecrets []string + // Probes — startup, liveness, and readiness probe configuration. + Probes *orktypes.ProbesConfig + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). diff --git a/pkg/orkestra-registry/pvcs/pvc.go b/pkg/orkestra-registry/pvcs/pvc.go index 110488b0..b1cc6cba 100644 --- a/pkg/orkestra-registry/pvcs/pvc.go +++ b/pkg/orkestra-registry/pvcs/pvc.go @@ -129,6 +129,7 @@ func Resolve(src orktypes.PVCTemplateSource, ownerName string) ResolvedPVCSpec { VolumeMode: src.VolumeMode, VolumeName: src.VolumeName, Labels: make(map[string]string), + Sleep: src.Sleep, } if len(spec.AccessModes) == 0 { diff --git a/pkg/orkestra-registry/pvs/pv.go b/pkg/orkestra-registry/pvs/pv.go index b095f33e..9f93da6f 100644 --- a/pkg/orkestra-registry/pvs/pv.go +++ b/pkg/orkestra-registry/pvs/pv.go @@ -127,6 +127,7 @@ func Resolve(src orktypes.PVTemplateSource, ownerName string) ResolvedPVSpec { CSIDriver: src.CSIDriver, CSIVolumeHandle: src.CSIVolumeHandle, Labels: make(map[string]string), + Sleep: src.Sleep, } if len(spec.AccessModes) == 0 { diff --git a/pkg/orkestra-registry/replicasets/replicaset.go b/pkg/orkestra-registry/replicasets/replicaset.go index 404f46a8..daea8c8d 100644 --- a/pkg/orkestra-registry/replicasets/replicaset.go +++ b/pkg/orkestra-registry/replicasets/replicaset.go @@ -108,6 +108,20 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec Msg("replicaset image drifted") } + // Resources drift + if spec.Resources != nil { + desiredRes := common.BuildResourceRequirements(spec.Resources) + var existingRes corev1.ResourceRequirements + if len(existing.Spec.Template.Spec.Containers) > 0 { + existingRes = existing.Spec.Template.Spec.Containers[0].Resources + } + if !common.ResourceRequirementsEqual(existingRes, desiredRes) { + updated.Spec.Template.Spec.Containers[0].Resources = desiredRes + drifted = true + logger.Info().Str("replicaset", spec.Name).Msg("replicaset resources drifted") + } + } + if !drifted { logger.Debug(). Str("replicaset", spec.Name). @@ -183,11 +197,13 @@ func Resolve(src orktypes.ReplicaSetTemplateSource, staticReplicas int, ownerNam Name: src.Name, Image: src.Image, Namespace: src.Namespace, - Resources: src.Resources, + Resources: common.ResolveResources(src.Resources), Labels: make(map[string]string), Annotations: make(map[string]string), Env: make(map[string]orktypes.EnvVarSource), EnvFrom: src.EnvFrom, + Probes: src.Probes, + Sleep: src.Sleep, } if spec.Name == "" { @@ -301,6 +317,8 @@ func buildReplicaSet(owner domain.Object, spec ResolvedReplicaSetSpec, namespace rs.Spec.Template.Spec.Containers[0].Resources = common.BuildResourceRequirements(spec.Resources) } + common.ApplyProbes(&rs.Spec.Template.Spec.Containers[0], spec.Probes, spec.Port) + if len(spec.Env) > 0 { rs.Spec.Template.Spec.Containers[0].Env = []corev1.EnvVar{} for k, src := range spec.Env { diff --git a/pkg/orkestra-registry/replicasets/types.go b/pkg/orkestra-registry/replicasets/types.go index dd2e6c1e..252eea6c 100644 --- a/pkg/orkestra-registry/replicasets/types.go +++ b/pkg/orkestra-registry/replicasets/types.go @@ -53,6 +53,9 @@ type ResolvedReplicaSetSpec struct { // If specified, these secrets will be passed to individual puller implementations for them to use. ImagePullSecrets []string + // Probes — startup, liveness, and readiness probe configuration. + Probes *orktypes.ProbesConfig + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). diff --git a/pkg/orkestra-registry/rolebindings/rolebinding.go b/pkg/orkestra-registry/rolebindings/rolebinding.go index 9c645e50..87593cce 100644 --- a/pkg/orkestra-registry/rolebindings/rolebinding.go +++ b/pkg/orkestra-registry/rolebindings/rolebinding.go @@ -165,6 +165,7 @@ func Resolve(src orktypes.RoleBindingTemplateSource, ownerName string) ResolvedR Name: src.Name, Namespace: src.Namespace, Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/roles/role.go b/pkg/orkestra-registry/roles/role.go index 26733572..17899a9d 100644 --- a/pkg/orkestra-registry/roles/role.go +++ b/pkg/orkestra-registry/roles/role.go @@ -155,6 +155,7 @@ func Resolve(src orktypes.RoleTemplateSource, ownerName string) ResolvedRoleSpec Name: src.Name, Namespace: src.Namespace, Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/secrets/secret.go b/pkg/orkestra-registry/secrets/secret.go index a406c5bf..f194fe3f 100644 --- a/pkg/orkestra-registry/secrets/secret.go +++ b/pkg/orkestra-registry/secrets/secret.go @@ -288,6 +288,7 @@ func Resolve(src orktypes.SecretTemplateSource, ownerName string) ResolvedSecret Type: src.Type, StringData: src.Data, // declared as strings in YAML Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/serviceaccounts/serviceaccount.go b/pkg/orkestra-registry/serviceaccounts/serviceaccount.go index 3f4c2610..bc96972a 100644 --- a/pkg/orkestra-registry/serviceaccounts/serviceaccount.go +++ b/pkg/orkestra-registry/serviceaccounts/serviceaccount.go @@ -136,6 +136,7 @@ func Resolve(src orktypes.ServiceAccountTemplateSource, ownerName string) Resolv Name: src.Name, Namespace: src.Namespace, Labels: make(map[string]string), + Sleep: src.Sleep, } if spec.Name == "" { diff --git a/pkg/orkestra-registry/services/services.go b/pkg/orkestra-registry/services/services.go index b447ce47..b9176b38 100644 --- a/pkg/orkestra-registry/services/services.go +++ b/pkg/orkestra-registry/services/services.go @@ -184,6 +184,7 @@ func Resolve(src orktypes.ServiceTemplateSource, ownerName string) ResolvedServi } spec.Namespace = src.Namespace + spec.Sleep = src.Sleep spec.Type = src.Type if spec.Type == "" { diff --git a/pkg/orkestra-registry/statefulsets/example_katalog.yaml b/pkg/orkestra-registry/statefulsets/example_katalog.yaml new file mode 100644 index 00000000..a0fbc4bb --- /dev/null +++ b/pkg/orkestra-registry/statefulsets/example_katalog.yaml @@ -0,0 +1,92 @@ +apiVersion: orkestra.orkspace.io/v1 +kind: Katalog +metadata: + name: database-operator + version: 0.1.0 + description: Manages PostgreSQL StatefulSets with persistent storage + +spec: + crds: + database: + apiTypes: + group: db.orkestra.io + version: v1alpha1 + kind: Database + plural: databases + allowedNamespaces: + - databases + + operatorBox: + onCreate: + statefulSets: + - name: "{{ .metadata.name }}" + namespace: "{{ .metadata.namespace }}" + image: "{{ .spec.image }}" + replicas: "{{ .spec.replicas | default \"1\" }}" + port: "5432" + serviceName: "{{ .metadata.name }}-headless" + resources: + profile: "{{ .spec.resourceProfile | default \"small\" }}" + reconcile: true + when: + - field: spec.image + exists: true + volumeClaimTemplates: + - name: data + storageClass: '{{ .spec.storageClass | default "standard" }}' + storageSize: '{{ .spec.storageSize | default "10Gi" }}' + mountPath: /var/lib/postgresql/data + - name: wal + storageClass: '{{ .spec.storageClass | default "standard" }}' + storageSize: '{{ .spec.walSize | default "5Gi" }}' + mountPath: /var/lib/postgresql/wal + env: + POSTGRES_DB: + value: '{{ .spec.database | default "app" }}' + POSTGRES_USER: + secretKeyRef: + name: "{{ .metadata.name }}-creds" + key: username + POSTGRES_PASSWORD: + secretKeyRef: + name: "{{ .metadata.name }}-creds" + key: password + + # Headless service required by StatefulSet for pod DNS + services: + - name: "{{ .metadata.name }}-headless" + namespace: "{{ .metadata.namespace }}" + port: "5432" + headless: true + reconcile: true + + # Regular service for client connections + - name: "{{ .metadata.name }}" + namespace: "{{ .metadata.namespace }}" + port: "5432" + reconcile: true + + secrets: + - name: "{{ .metadata.name }}-creds" + namespace: "{{ .metadata.namespace }}" + data: + username: '{{ .spec.username | default "postgres" }}' + password: "{{ .spec.password }}" + reconcile: true + when: + - field: spec.password + exists: true + + status: + fields: + - path: phase + value: "Pending" + when: + - field: spec.image + notExists: true + + - path: phase + value: "Ready" + when: + - field: spec.image + exists: true diff --git a/pkg/orkestra-registry/statefulsets/statefulset.go b/pkg/orkestra-registry/statefulsets/statefulset.go index f548c5cd..ee39bcb8 100644 --- a/pkg/orkestra-registry/statefulsets/statefulset.go +++ b/pkg/orkestra-registry/statefulsets/statefulset.go @@ -84,6 +84,19 @@ func Update(ctx context.Context, kube *kubeclient.Kubeclient, owner domain.Objec drifted = true } + if spec.Resources != nil { + desiredRes := common.BuildResourceRequirements(spec.Resources) + var existingRes corev1.ResourceRequirements + if len(existing.Spec.Template.Spec.Containers) > 0 { + existingRes = existing.Spec.Template.Spec.Containers[0].Resources + } + if !common.ResourceRequirementsEqual(existingRes, desiredRes) { + updated.Spec.Template.Spec.Containers[0].Resources = desiredRes + drifted = true + logger.Info().Str("statefulset", spec.Name).Msg("statefulset resources drifted") + } + } + if !drifted { logger.Debug().Str("statefulset", spec.Name).Msg("statefulset in sync — no update needed") return nil @@ -134,19 +147,35 @@ func DeleteIfOwned(ctx context.Context, kube *kubeclient.Kubeclient, owner domai // Resolve builds a ResolvedStatefulSetSpec from a StatefulSetTemplateSource. func Resolve(src orktypes.StatefulSetTemplateSource, ownerName string) ResolvedStatefulSetSpec { spec := ResolvedStatefulSetSpec{ - Name: src.Name, - Namespace: src.Namespace, - Image: src.Image, - ServiceName: src.ServiceName, - StorageClass: src.StorageClass, - StorageSize: src.StorageSize, - MountPath: src.MountPath, - Replicas: 1, - Labels: make(map[string]string), - Annotations: make(map[string]string), - Env: src.Env, - EnvFrom: src.EnvFrom, - Resources: src.Resources, + Name: src.Name, + Namespace: src.Namespace, + Image: src.Image, + ServiceName: src.ServiceName, + Replicas: 1, + Labels: make(map[string]string), + Annotations: make(map[string]string), + Env: src.Env, + EnvFrom: src.EnvFrom, + Resources: common.ResolveResources(src.Resources), + Probes: src.Probes, + Sleep: src.Sleep, + } + + for _, vct := range src.VolumeClaimTemplates { + resolved := ResolvedVolumeClaimTemplate{ + Name: vct.Name, + StorageClass: vct.StorageClass, + StorageSize: vct.StorageSize, + MountPath: vct.MountPath, + AccessModes: vct.AccessModes, + } + if resolved.Name == "" { + resolved.Name = "data" + } + if resolved.MountPath == "" { + resolved.MountPath = "/data" + } + spec.VolumeClaimTemplates = append(spec.VolumeClaimTemplates, resolved) } if spec.Name == "" { @@ -155,9 +184,6 @@ func Resolve(src orktypes.StatefulSetTemplateSource, ownerName string) ResolvedS if spec.ServiceName == "" { spec.ServiceName = spec.Name } - if spec.MountPath == "" { - spec.MountPath = "/data" - } if src.Tag != "" { spec.Image = src.Image + ":" + src.Tag @@ -184,6 +210,26 @@ func Resolve(src orktypes.StatefulSetTemplateSource, ownerName string) ResolvedS // ── Internal helpers ────────────────────────────────────────────────────────── +func resolveAccessModes(modes []string) []corev1.PersistentVolumeAccessMode { + if len(modes) == 0 { + return []corev1.PersistentVolumeAccessMode{corev1.ReadWriteOnce} + } + out := make([]corev1.PersistentVolumeAccessMode, 0, len(modes)) + for _, m := range modes { + switch m { + case "ReadWriteMany": + out = append(out, corev1.ReadWriteMany) + case "ReadOnlyMany": + out = append(out, corev1.ReadOnlyMany) + case "ReadWriteOncePod": + out = append(out, corev1.ReadWriteOncePod) + default: + out = append(out, corev1.ReadWriteOnce) + } + } + return out +} + func buildStatefulSet(owner domain.Object, spec ResolvedStatefulSetSpec, ns string) *appsv1.StatefulSet { apiVersion := "" kind := "" @@ -210,6 +256,8 @@ func buildStatefulSet(owner domain.Object, spec ResolvedStatefulSetSpec, ns stri container.Resources = common.BuildResourceRequirements(spec.Resources) } + common.ApplyProbes(&container, spec.Probes, spec.Port) + for k, v := range spec.Env { ev := corev1.EnvVar{Name: k} if v.Value != "" { @@ -295,28 +343,33 @@ func buildStatefulSet(owner domain.Object, spec ResolvedStatefulSetSpec, ns stri }, } - // Add VolumeClaimTemplate when storage is declared. - if spec.StorageClass != "" && spec.StorageSize != "" { - storageQty := resource.MustParse(spec.StorageSize) - container.VolumeMounts = append(container.VolumeMounts, corev1.VolumeMount{ - Name: "data", - MountPath: spec.MountPath, - }) - sts.Spec.Template.Spec.Containers[0].VolumeMounts = container.VolumeMounts - sts.Spec.VolumeClaimTemplates = []corev1.PersistentVolumeClaim{ - { - ObjectMeta: metav1.ObjectMeta{Name: "data"}, - Spec: corev1.PersistentVolumeClaimSpec{ - AccessModes: []corev1.PersistentVolumeAccessMode{corev1.ReadWriteOnce}, - StorageClassName: &spec.StorageClass, - Resources: corev1.VolumeResourceRequirements{ - Requests: corev1.ResourceList{ - corev1.ResourceStorage: storageQty, - }, + for _, vct := range spec.VolumeClaimTemplates { + storageQty := resource.MustParse(vct.StorageSize) + name := vct.Name + if name == "" { + name = "data" + } + mountPath := vct.MountPath + if mountPath == "" { + mountPath = "/data" + } + accessModes := resolveAccessModes(vct.AccessModes) + sts.Spec.Template.Spec.Containers[0].VolumeMounts = append( + sts.Spec.Template.Spec.Containers[0].VolumeMounts, + corev1.VolumeMount{Name: name, MountPath: mountPath}, + ) + sts.Spec.VolumeClaimTemplates = append(sts.Spec.VolumeClaimTemplates, corev1.PersistentVolumeClaim{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: corev1.PersistentVolumeClaimSpec{ + AccessModes: accessModes, + StorageClassName: &vct.StorageClass, + Resources: corev1.VolumeResourceRequirements{ + Requests: corev1.ResourceList{ + corev1.ResourceStorage: storageQty, }, }, }, - } + }) } return sts diff --git a/pkg/orkestra-registry/statefulsets/types.go b/pkg/orkestra-registry/statefulsets/types.go index 10a6cf5a..8e98979c 100644 --- a/pkg/orkestra-registry/statefulsets/types.go +++ b/pkg/orkestra-registry/statefulsets/types.go @@ -3,6 +3,15 @@ package statefulsets import orktypes "github.com/orkspace/orkestra/pkg/types" +// ResolvedVolumeClaimTemplate is one resolved PVC template for a StatefulSet. +type ResolvedVolumeClaimTemplate struct { + Name string + StorageClass string + StorageSize string + MountPath string + AccessModes []string +} + // ResolvedStatefulSetSpec is the fully resolved StatefulSet specification. type ResolvedStatefulSetSpec struct { Name string @@ -12,10 +21,8 @@ type ResolvedStatefulSetSpec struct { Port int32 ServiceName string - // Storage — set when StorageClass is declared. - StorageClass string - StorageSize string - MountPath string + // VolumeClaimTemplates — resolved PVC templates (may be multiple). + VolumeClaimTemplates []ResolvedVolumeClaimTemplate Labels map[string]string Annotations map[string]string @@ -43,6 +50,9 @@ type ResolvedStatefulSetSpec struct { VolumeClaimRetentionPolicy VolumeClaimRetentionPolicy + // Probes — startup, liveness, and readiness probe configuration. + Probes *orktypes.ProbesConfig + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). diff --git a/pkg/orkestra-registry/template/resolver.go b/pkg/orkestra-registry/template/resolver.go index 1e3e8639..db23abf4 100644 --- a/pkg/orkestra-registry/template/resolver.go +++ b/pkg/orkestra-registry/template/resolver.go @@ -141,6 +141,7 @@ func (r *Resolver) ResolvePodTemplate(src orktypes.PodTemplateSource) (orktypes. resolved := orktypes.PodTemplateSource{ Version: src.Version, Resources: src.Resources, // static — not resolved + Probes: src.Probes, // static — passed through } var err error @@ -187,6 +188,7 @@ func (r *Resolver) ResolveDeploymentTemplate(src orktypes.DeploymentTemplateSour resolved := orktypes.DeploymentTemplateSource{ Version: src.Version, Resources: src.Resources, // static — not resolved + Probes: src.Probes, // static — passed through } var err error @@ -292,6 +294,7 @@ func (r *Resolver) ResolveReplicaSetTemplate(src orktypes.ReplicaSetTemplateSour resolved := orktypes.ReplicaSetTemplateSource{ Version: src.Version, Resources: src.Resources, // static — not resolved + Probes: src.Probes, // static — passed through } var err error @@ -494,6 +497,7 @@ func (r *Resolver) ResolveJobTemplate(src orktypes.JobTemplateSource) (orktypes. resolved := orktypes.JobTemplateSource{ Version: src.Version, BackoffLimit: src.BackoffLimit, + Resources: src.Resources, } var err error @@ -728,7 +732,8 @@ func (r *Resolver) ResolveConfigMapTemplate(src orktypes.ConfigMapTemplateSource // ResolveCronJobTemplate resolves all template expressions in a CronJobTemplateSource. func (r *Resolver) ResolveCronJobTemplate(src orktypes.CronJobTemplateSource) (orktypes.CronJobTemplateSource, error) { resolved := orktypes.CronJobTemplateSource{ - Version: src.Version, + Version: src.Version, + Resources: src.Resources, } var err error @@ -1071,6 +1076,7 @@ func (r *Resolver) ResolveStatefulSetTemplate(src orktypes.StatefulSetTemplateSo resolved := orktypes.StatefulSetTemplateSource{ Version: src.Version, Resources: src.Resources, + Probes: src.Probes, // static — passed through } var err error @@ -1096,14 +1102,21 @@ func (r *Resolver) ResolveStatefulSetTemplate(src orktypes.StatefulSetTemplateSo if resolved.ServiceName, err = r.Resolve(src.ServiceName); err != nil { return resolved, fmt.Errorf("statefulset.serviceName: %w", err) } - if resolved.StorageClass, err = r.Resolve(src.StorageClass); err != nil { - return resolved, fmt.Errorf("statefulset.storageClass: %w", err) - } - if resolved.StorageSize, err = r.Resolve(src.StorageSize); err != nil { - return resolved, fmt.Errorf("statefulset.storageSize: %w", err) - } - if resolved.MountPath, err = r.Resolve(src.MountPath); err != nil { - return resolved, fmt.Errorf("statefulset.mountPath: %w", err) + for i, vct := range src.VolumeClaimTemplates { + rv := orktypes.VolumeClaimTemplateSource{AccessModes: vct.AccessModes} + if rv.Name, err = r.Resolve(vct.Name); err != nil { + return resolved, fmt.Errorf("statefulset.volumeClaimTemplates[%d].name: %w", i, err) + } + if rv.StorageClass, err = r.Resolve(vct.StorageClass); err != nil { + return resolved, fmt.Errorf("statefulset.volumeClaimTemplates[%d].storageClass: %w", i, err) + } + if rv.StorageSize, err = r.Resolve(vct.StorageSize); err != nil { + return resolved, fmt.Errorf("statefulset.volumeClaimTemplates[%d].storageSize: %w", i, err) + } + if rv.MountPath, err = r.Resolve(vct.MountPath); err != nil { + return resolved, fmt.Errorf("statefulset.volumeClaimTemplates[%d].mountPath: %w", i, err) + } + resolved.VolumeClaimTemplates = append(resolved.VolumeClaimTemplates, rv) } if resolved.Sleep, err = r.Resolve(src.Sleep); err != nil { return resolved, fmt.Errorf("statefulset.sleep: %w", err) diff --git a/pkg/reconciler/run_foreach.go b/pkg/reconciler/run_foreach.go index b45b11e7..7309ecca 100644 --- a/pkg/reconciler/run_foreach.go +++ b/pkg/reconciler/run_foreach.go @@ -675,9 +675,14 @@ func expandForEachStatefulSets( expanded.Replicas, _ = ir.Resolve(src.Replicas) expanded.Port, _ = ir.Resolve(src.Port) expanded.ServiceName, _ = ir.Resolve(src.ServiceName) - expanded.StorageClass, _ = ir.Resolve(src.StorageClass) - expanded.StorageSize, _ = ir.Resolve(src.StorageSize) - expanded.MountPath, _ = ir.Resolve(src.MountPath) + for i, vct := range src.VolumeClaimTemplates { + rv := src.VolumeClaimTemplates[i] + rv.StorageClass, _ = ir.Resolve(vct.StorageClass) + rv.StorageSize, _ = ir.Resolve(vct.StorageSize) + rv.MountPath, _ = ir.Resolve(vct.MountPath) + rv.Name, _ = ir.Resolve(vct.Name) + expanded.VolumeClaimTemplates[i] = rv + } if len(src.Labels) > 0 { expanded.Labels = make([]orktypes.ResourceLabel, 0, len(src.Labels)) diff --git a/pkg/tunnel/README.md b/pkg/tunnel/README.md index d0fcfb03..79109821 100644 --- a/pkg/tunnel/README.md +++ b/pkg/tunnel/README.md @@ -1,6 +1,6 @@ # pkg/tunnel -The tunnel package exposes local Kubernetes services to the public internet without touching DNS, firewalls, or cloud infrastructure. It is used by `ork deploy --expose` and `ork tunnel expose` to make an Orkestra app or the Control Center reachable from outside the cluster. +The tunnel package exposes local Kubernetes services to the public internet without touching DNS, firewalls, or cloud infrastructure. It is used by `ork doctor deploy --expose` and `ork tunnel expose` to make an Orkestra app or the Control Center reachable from outside the cluster. ## What lives here diff --git a/pkg/tunnel/cloudflare.go b/pkg/tunnel/cloudflare.go index 078888ec..262cabdd 100644 --- a/pkg/tunnel/cloudflare.go +++ b/pkg/tunnel/cloudflare.go @@ -119,7 +119,9 @@ func (c *CloudflaredProvider) Stop(pid int) error { // instance writes to its own file. func cloudflaredLogPath(localPort int) string { home, _ := os.UserHomeDir() - return filepath.Join(home, ".orkestra", fmt.Sprintf("cloudflared-%d.log", localPort)) + dir := filepath.Join(home, ".orkestra", "doctor", "cloudflare") + _ = os.MkdirAll(dir, 0o755) + return filepath.Join(dir, fmt.Sprintf("cloudflared-%d.log", localPort)) } // tailLogForURL polls a log file and sends the tunnel URL only after cloudflared diff --git a/pkg/tunnel/docs/01-providers.md b/pkg/tunnel/docs/01-providers.md index 2ccf303c..1ef3acd1 100644 --- a/pkg/tunnel/docs/01-providers.md +++ b/pkg/tunnel/docs/01-providers.md @@ -29,7 +29,7 @@ The daemon must outlive the CLI process that launched it. See [05 — Process Su **Authenticate** is a no-op for cloudflared. Quick tunnels are anonymous. -**Why cloudflared is the default**: zero friction for local development. A developer can run `ork deploy --expose` on a fresh machine and get a working public URL without signing up anywhere. +**Why cloudflared is the default**: zero friction for local development. A developer can run `ork doctor deploy --expose` on a fresh machine and get a working public URL without signing up anywhere. **Log file**: `~/.orkestra/cloudflared-.log`. Each tunnel instance writes to its own file keyed by local port so concurrent tunnels never intermix output. @@ -60,7 +60,7 @@ Auto-selection order: 2. Ngrok (if binary found in PATH) 3. Cloudflared (fallback — it can install itself on demand) -The `Expose` function calls `p.Install(ctx)` when `!p.Available()`, so a user who has never run `ork deploy --expose` before gets cloudflared downloaded and installed transparently. +The `Expose` function calls `p.Install(ctx)` when `!p.Available()`, so a user who has never run `ork doctor deploy --expose` before gets cloudflared downloaded and installed transparently. --- Next -> [02-state.md](02-state.md) \ No newline at end of file diff --git a/pkg/tunnel/expose.go b/pkg/tunnel/expose.go index 04b62791..39fbb77d 100644 --- a/pkg/tunnel/expose.go +++ b/pkg/tunnel/expose.go @@ -1,6 +1,6 @@ // pkg/tunnel/expose.go // -// High-level Expose function used by `ork deploy --expose` and +// High-level Expose function used by `ork doctor deploy --expose` and // `ork tunnel expose`. Detects the local port, starts the tunnel, // and persists state under a named key. package tunnel @@ -178,11 +178,16 @@ func startPortForward(tunnelName, serviceName, namespace, servicePort string) (i } pid := cmd.Process.Pid - // Poll until the local port is ready (up to 8 seconds). - deadline := time.Now().Add(8 * time.Second) + addrStr := fmt.Sprintf("127.0.0.1:%d", localPort) + portAlive := func() bool { + return cmd.Process.Signal(syscall.Signal(0)) == nil + } + + // Phase 1: wait for the port-forward to bind the local port (up to 10s). + deadline := time.Now().Add(10 * time.Second) + bound := false for time.Now().Before(deadline) { - // Detect early exit (pod not running, service has no endpoints, etc.) - if err := cmd.Process.Signal(syscall.Signal(0)); err != nil { + if !portAlive() { return 0, 0, fmt.Errorf( "kubectl port-forward for svc/%s in %s exited — is the pod running?\n"+ " Check: kubectl get pods -n %s", @@ -190,20 +195,49 @@ func startPortForward(tunnelName, serviceName, namespace, servicePort string) (i ) } if isTCPListening(localPort) { - return localPort, pid, nil + bound = true + break } time.Sleep(150 * time.Millisecond) } + if !bound { + if !portAlive() { + return 0, 0, fmt.Errorf( + "kubectl port-forward for svc/%s in %s exited — is the pod running?\n"+ + " Check: kubectl get pods -n %s", + serviceName, namespace, namespace, + ) + } + // Port-forward is alive but port still not bound — continue anyway. + return localPort, pid, nil + } - // Port-forward is still alive but port isn't bound yet — return and let - // cloudflared wait for the origin to become available. - if err := cmd.Process.Signal(syscall.Signal(0)); err != nil { - return 0, 0, fmt.Errorf( - "kubectl port-forward for svc/%s in %s exited — is the pod running?\n"+ - " Check: kubectl get pods -n %s", - serviceName, namespace, namespace, - ) + // Phase 2: warm-probe — verify the port-forward path reaches a live backend. + // kubectl port-forward accepts TCP connections immediately after binding, but + // closes them right away when the pod is not yet ready. A read timeout means + // the connection stayed open → backend is live and ready for cloudflared. + warmDeadline := time.Now().Add(10 * time.Second) + for time.Now().Before(warmDeadline) { + if !portAlive() { + break + } + conn, err := net.DialTimeout("tcp", addrStr, 500*time.Millisecond) + if err != nil { + time.Sleep(300 * time.Millisecond) + continue + } + conn.SetDeadline(time.Now().Add(300 * time.Millisecond)) + buf := make([]byte, 1) + _, readErr := conn.Read(buf) + conn.Close() + // A timeout means the connection stayed open — backend is live. + if netErr, ok := readErr.(net.Error); ok && netErr.Timeout() { + return localPort, pid, nil + } + // Connection was closed by kubectl — backend not ready yet. Retry. + time.Sleep(300 * time.Millisecond) } + return localPort, pid, nil } diff --git a/pkg/tunnel/ngrok.go b/pkg/tunnel/ngrok.go index 78f938d8..aea92a5f 100644 --- a/pkg/tunnel/ngrok.go +++ b/pkg/tunnel/ngrok.go @@ -31,7 +31,7 @@ func (n *NgrokProvider) Install(_ context.Context) error { return fmt.Errorf( "ngrok is not installed\n" + " Install: https://ngrok.com/download\n" + - " Then run: ork deploy --expose --tunnel-provider ngrok", + " Then run: ork doctor deploy --expose --tunnel-provider ngrok", ) } @@ -40,7 +40,7 @@ func (n *NgrokProvider) Authenticate(_ context.Context, token string) error { if token == "" { return fmt.Errorf( "ngrok auth token required — get yours at https://dashboard.ngrok.com/get-started/your-authtoken\n" + - " Then run: ork deploy --expose --tunnel-provider ngrok --tunnel-token ", + " Then run: ork doctor deploy --expose --tunnel-provider ngrok --tunnel-token ", ) } cmd := exec.Command("ngrok", "config", "add-authtoken", token) diff --git a/pkg/tunnel/state.go b/pkg/tunnel/state.go index 99de0d43..b21946c8 100644 --- a/pkg/tunnel/state.go +++ b/pkg/tunnel/state.go @@ -1,6 +1,6 @@ // pkg/tunnel/state.go // -// Multi-tunnel daemon state — persisted to ~/.orkestra/tunnel-state.json +// Multi-tunnel daemon state — persisted to ~/.orkestra/doctor/tunnel/tunnel-state.json // as a map[name]State so multiple tunnels (per app, controlcenter) coexist. package tunnel @@ -26,7 +26,9 @@ type State struct { func stateFile() string { home, _ := os.UserHomeDir() - return filepath.Join(home, ".orkestra", "tunnel-state.json") + dir := filepath.Join(home, ".orkestra", "doctor", "tunnel") + _ = os.MkdirAll(dir, 0o755) + return filepath.Join(dir, "tunnel-state.json") } // SaveTunnelState writes or updates the named tunnel entry. diff --git a/pkg/types/hooks_probes.go b/pkg/types/hooks_probes.go new file mode 100644 index 00000000..c6231ad5 --- /dev/null +++ b/pkg/types/hooks_probes.go @@ -0,0 +1,103 @@ +package types + +import ( + "fmt" + "strings" +) + +// ProbeProfileEntry describes a single probe profile reference found in a +// HookTemplates resource. Used by validation to fail fast on unknown profiles +// and to enforce mutual exclusivity between profile and explicit timing fields. +type ProbeProfileEntry struct { + Phase string // "onCreate", "onReconcile", "onDelete" + Resource string // e.g. "Deployment", "StatefulSet" + ResourceName string // template name field (may be empty) + ProbeType string // "startup", "liveness", "readiness" + Profile string // raw profile name as written in the katalog + Mixed bool // true when profile is set alongside explicit timing overrides +} + +// prober is a tiny interface satisfied by resources that carry a ProbesConfig. +type prober interface { + GetProbes() *ProbesConfig +} + +// GetProbes returns the probe configuration for each supported workload type. +// Value receivers so the method is available on both values and pointers. +func (t DeploymentTemplateSource) GetProbes() *ProbesConfig { return t.Probes } +func (t ReplicaSetTemplateSource) GetProbes() *ProbesConfig { return t.Probes } +func (t StatefulSetTemplateSource) GetProbes() *ProbesConfig { return t.Probes } +func (t PodTemplateSource) GetProbes() *ProbesConfig { return t.Probes } + +// CollectProbeProfileEntries returns all probe profile references declared for +// this CRD across OnCreate, OnReconcile, and OnDelete. +// Only entries with a non-empty Profile string are returned — omitted profiles +// (which fall back to "standard") are not surfaced for validation. +func (c *CRDEntry) CollectProbeProfileEntries() []ProbeProfileEntry { + if !c.HasAnyHooks() { + return nil + } + + var out []ProbeProfileEntry + + collect := func(phase string, ht *HookTemplates) { + if ht == nil { + return + } + ht.VisitResources(func(res interface{}) { + pb, ok := res.(prober) + if !ok { + return + } + probes := pb.GetProbes() + if probes == nil { + return + } + + // Derive friendly names + var rname string + if n, ok := res.(namer); ok { + rname = n.GetName() + } + rtype := fmt.Sprintf("%T", res) + if i := strings.LastIndex(rtype, "."); i >= 0 { + rtype = rtype[i+1:] + } + + for probeType, cfg := range map[string]*ProbeConfig{ + "startup": probes.Startup, + "liveness": probes.Liveness, + "readiness": probes.Readiness, + } { + if cfg == nil || cfg.Profile == "" { + continue + } + mixed := cfg.InitialDelaySeconds != nil || + cfg.PeriodSeconds != nil || + cfg.FailureThreshold != nil || + cfg.SuccessThreshold != nil || + cfg.TimeoutSeconds != nil + out = append(out, ProbeProfileEntry{ + Phase: phase, + Resource: rtype, + ResourceName: rname, + ProbeType: probeType, + Profile: cfg.Profile, + Mixed: mixed, + }) + } + }) + } + + if c.HasOnCreate() { + collect("onCreate", c.OperatorBox.OnCreate) + } + if c.HasOnReconcile() { + collect("onReconcile", c.OperatorBox.OnReconcile) + } + if c.HasOnDelete() { + collect("onDelete", c.OperatorBox.OnDelete) + } + + return out +} diff --git a/pkg/types/hooks_resources.go b/pkg/types/hooks_resources.go new file mode 100644 index 00000000..469323b1 --- /dev/null +++ b/pkg/types/hooks_resources.go @@ -0,0 +1,88 @@ +package types + +import ( + "fmt" + "strings" +) + +// ResourceProfileEntry describes a single resources.profile reference found in a +// HookTemplates resource. Used by validation to fail fast on unknown profiles +// and to enforce mutual exclusivity between profile and explicit resource fields. +type ResourceProfileEntry struct { + Phase string // "onCreate", "onReconcile", "onDelete" + Resource string // e.g. "Deployment", "StatefulSet" + ResourceName string // template name field (may be empty) + Profile string // raw profile name as written in the katalog + Mixed bool // true when profile is set alongside explicit requests/limits +} + +// resourced is a tiny interface satisfied by resources that carry a ResourceRequirements block. +type resourced interface { + GetResources() *ResourceRequirements +} + +// GetResources returns the resource requirements for each supported workload type. +func (t DeploymentTemplateSource) GetResources() *ResourceRequirements { return t.Resources } +func (t ReplicaSetTemplateSource) GetResources() *ResourceRequirements { return t.Resources } +func (t StatefulSetTemplateSource) GetResources() *ResourceRequirements { return t.Resources } +func (t PodTemplateSource) GetResources() *ResourceRequirements { return t.Resources } +func (t JobTemplateSource) GetResources() *ResourceRequirements { return t.Resources } +func (t CronJobTemplateSource) GetResources() *ResourceRequirements { return t.Resources } + +// CollectResourceProfileEntries returns all resources.profile references declared for +// this CRD across OnCreate, OnReconcile, and OnDelete. +// Only entries with a non-empty Profile string are returned. +func (c *CRDEntry) CollectResourceProfileEntries() []ResourceProfileEntry { + if !c.HasAnyHooks() { + return nil + } + + var out []ResourceProfileEntry + + collect := func(phase string, ht *HookTemplates) { + if ht == nil { + return + } + ht.VisitResources(func(res interface{}) { + rd, ok := res.(resourced) + if !ok { + return + } + spec := rd.GetResources() + if spec == nil || spec.Profile == "" { + return + } + + var rname string + if n, ok := res.(namer); ok { + rname = n.GetName() + } + rtype := fmt.Sprintf("%T", res) + if i := strings.LastIndex(rtype, "."); i >= 0 { + rtype = rtype[i+1:] + } + + mixed := len(spec.Requests) > 0 || len(spec.Limits) > 0 + + out = append(out, ResourceProfileEntry{ + Phase: phase, + Resource: rtype, + ResourceName: rname, + Profile: spec.Profile, + Mixed: mixed, + }) + }) + } + + if c.HasOnCreate() { + collect("onCreate", c.OperatorBox.OnCreate) + } + if c.HasOnReconcile() { + collect("onReconcile", c.OperatorBox.OnReconcile) + } + if c.HasOnDelete() { + collect("onDelete", c.OperatorBox.OnDelete) + } + + return out +} diff --git a/pkg/types/katalog.go b/pkg/types/katalog.go index 38ed4e5e..18edd2e5 100644 --- a/pkg/types/katalog.go +++ b/pkg/types/katalog.go @@ -125,6 +125,34 @@ type ProjectInfo struct { // ConfigCount is the number of config variables (derived). ConfigCount int `yaml:"configCount,omitempty" json:"configCount,omitempty"` + + // Namespace is the Kubernetes namespace this project is deployed into. + // Written by ork doctor at deploy time so the Control Center can + // display the internal service URL without an additional API call. + Namespace string `yaml:"namespace,omitempty" json:"namespace,omitempty"` + + // CurrentImage is the fully-qualified image reference that was last + // deployed for this project (e.g. docker.io/myorg/app:abc123). + // Written by ork doctor after a successful deploy. + CurrentImage string `yaml:"currentImage,omitempty" json:"currentImage,omitempty"` +} + +// HasSecrets reports whether ork doctor discovered any secret +// environment variables in the project (.env where IsCfg == false). +func (p *ProjectInfo) HasSecrets() bool { + return len(p.Secrets) > 0 +} + +// HasConfig reports whether ork doctor discovered any config +// environment variables in the project (.env where IsCfg == true). +func (p *ProjectInfo) HasConfig() bool { + return len(p.Config) > 0 +} + +// HasCreds reports whether the project contains *either* secrets or config. +// Useful for high‑level checks (e.g., does this project need a ConfigMap or Secret?). +func (p *ProjectInfo) HasCreds() bool { + return p.HasSecrets() || p.HasConfig() } // KatalogMeta holds identifying metadata for a Katalog. @@ -187,7 +215,7 @@ type KatalogMeta struct { // developer intent, project structure, and local context travel with the // Katalog — enabling richer automation, better defaults, and a more intuitive // experience across the entire lifecycle. - ProjectInfo ProjectInfo `yaml:"projectInfo,omitempty" json:"projectInfo,omitempty"` + // ProjectInfo ProjectInfo `yaml:"projectInfo,omitempty" json:"projectInfo,omitempty"` // Projects holds the aggregated ProjectInfo entries for every application // participating in this Komposer workspace. Each entry represents the diff --git a/pkg/types/methods.go b/pkg/types/methods.go index c6010184..0636b735 100644 --- a/pkg/types/methods.go +++ b/pkg/types/methods.go @@ -335,16 +335,6 @@ func (c *CRDEntry) AutoScaleProfile() string { return c.OperatorBox.Autoscale.Profile } -// HasResourceProfile reports whether this crd defined autoscale profile -func (c *CRDEntry) HasResourceProfile() bool { - return c.OperatorBox.Autoscale != nil && c.OperatorBox.Autoscale.Profile != "" -} - -// ResourceProfile returns the string value of the autoscale profile -func (c *CRDEntry) ResourceProfile() string { - return c.OperatorBox.Autoscale.Profile -} - // UpdateCRDCaBundle reports whether this CRD declares an updateCRD field // Used to update the crd when certificate is autogenerted by orkestra func (c *CRDEntry) UpdateCRDCaBundle() bool { diff --git a/pkg/types/types.go b/pkg/types/types.go index 5672093d..59516242 100644 --- a/pkg/types/types.go +++ b/pkg/types/types.go @@ -209,7 +209,11 @@ func (m SelectorMap) String() string { // Values are static Kubernetes quantity strings — template expressions // are not supported here. // e.g. requests: {cpu: "100m", memory: "128Mi"} +// +// Profile is mutually exclusive with Requests and Limits. When Profile is set, +// it expands into a complete ResourceRequirements at reconcile time. type ResourceRequirements struct { + Profile string `yaml:"profile,omitempty" json:"profile,omitempty" validate:"omitempty"` Requests map[string]string `yaml:"requests" json:"requests,omitempty" validate:"omitempty"` Limits map[string]string `yaml:"limits" json:"limits,omitempty" validate:"omitempty"` } @@ -276,6 +280,62 @@ type ConfigMapKeyRef struct { // Set → pins to a specific OrkestraRegistry release tag for stability. // e.g. version: v1.2.0 +// ── Probes ──────────────────────────────────────────────────────────────────── + +// ProbeConfig configures a single Kubernetes probe (startup, liveness, or readiness). +// Supports HTTP GET and TCP socket checks, with timing driven by named profiles or +// explicit field overrides. +// +// Examples: +// +// probes: +// startup: +// type: http +// path: /health +// profile: slow-start +// liveness: +// type: http +// path: /health +// profile: standard +// readiness: +// type: http +// path: /ready +// profile: standard +// +// probes: +// liveness: +// type: tcp +// profile: standard +type ProbeConfig struct { + // Type — probe mechanism. "http" uses an HTTP GET, "tcp" opens a TCP socket. + // When path is set and type is omitted, http is assumed. + Type string `yaml:"type,omitempty" json:"type,omitempty"` + + // Path — HTTP GET path. Required when type is "http". + Path string `yaml:"path,omitempty" json:"path,omitempty"` + + // Port — override port for the probe. Defaults to the container's declared port. + Port int32 `yaml:"port,omitempty" json:"port,omitempty"` + + // Profile — timing profile name. Allowed values: fast, standard, patient, slow-start. + // Defaults to "standard" when omitted. + Profile string `yaml:"profile,omitempty" json:"profile,omitempty"` + + // Explicit timing overrides — use when profiles are not granular enough. + InitialDelaySeconds *int32 `yaml:"initialDelaySeconds,omitempty" json:"initialDelaySeconds,omitempty"` + PeriodSeconds *int32 `yaml:"periodSeconds,omitempty" json:"periodSeconds,omitempty"` + FailureThreshold *int32 `yaml:"failureThreshold,omitempty" json:"failureThreshold,omitempty"` + SuccessThreshold *int32 `yaml:"successThreshold,omitempty" json:"successThreshold,omitempty"` + TimeoutSeconds *int32 `yaml:"timeoutSeconds,omitempty" json:"timeoutSeconds,omitempty"` +} + +// ProbesConfig groups startup, liveness, and readiness probe declarations. +type ProbesConfig struct { + Startup *ProbeConfig `yaml:"startup,omitempty" json:"startup,omitempty"` + Liveness *ProbeConfig `yaml:"liveness,omitempty" json:"liveness,omitempty"` + Readiness *ProbeConfig `yaml:"readiness,omitempty" json:"readiness,omitempty"` +} + // ── Deployment ──────────────────────────────────────────────────────────────── // DeploymentTemplateSource declares one Deployment to be managed by Orkestra. @@ -293,7 +353,8 @@ type ConfigMapKeyRef struct { // - image: nginx:1.25 // replicas: "3" // port: "8080" -// resourceProfile: burst # Use orkestra's burst resource configuration +// resources: +// profile: burst # Use orkestra's burst resource configuration // // Full example — dynamic values from the CR: // @@ -361,19 +422,10 @@ type DeploymentTemplateSource struct { Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty" validate:"omitempty"` // Resources — CPU and memory requests/limits for the primary container. - // Values are static Kubernetes quantity strings. - // Template expressions are not supported in resource quantities. + // Set resources.profile for a named preset, or resources.requests/limits for + // explicit values. Profile and explicit values are mutually exclusive. Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"` - // ResourceProfile — semantic CPU/memory preset for the primary container. - // Profiles expand into a complete ResourceRequirements struct during katalog - // enrichment. Allowed values: tiny, small, medium, large, burst, steady, - // compute-heavy, memory-heavy. - // - // When resourceProfile is set, manual resources.requests/limits must not be - // provided. Profiles are atomic and fully define resource behavior. - ResourceProfile string `yaml:"resourceProfile" json:"resourceProfile,omitempty" validate:"omitempty"` - // Env — environment variables for the primary container. // Keys are env var names. Values support template expressions. // Example: @@ -440,6 +492,9 @@ type DeploymentTemplateSource struct { // a checked-out repository path. WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"` + // Probes — startup, liveness, and readiness probe configuration. + Probes *ProbesConfig `yaml:"probes,omitempty" json:"probes,omitempty"` + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). @@ -528,19 +583,10 @@ type ReplicaSetTemplateSource struct { Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty" validate:"omitempty"` // Resources — CPU and memory requests/limits for the primary container. - // Values are static Kubernetes quantity strings. - // Template expressions are not supported in resource quantities. + // Set resources.profile for a named preset, or resources.requests/limits for + // explicit values. Profile and explicit values are mutually exclusive. Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"` - // ResourceProfile — semantic CPU/memory preset for the primary container. - // Profiles expand into a complete ResourceRequirements struct during katalog - // enrichment. Allowed values: tiny, small, medium, large, burst, steady, - // compute-heavy, memory-heavy. - // - // When resourceProfile is set, manual resources.requests/limits must not be - // provided. Profiles are atomic and fully define resource behavior. - ResourceProfile string `yaml:"resourceProfile" json:"resourceProfile,omitempty" validate:"omitempty"` - // Env — environment variables for the primary container. // Keys are env var names. Values support template expressions. Env map[string]EnvVarSource `yaml:"env" json:"env,omitempty"` @@ -576,6 +622,9 @@ type ReplicaSetTemplateSource struct { // WorkingDirectory sets the container's working directory (container.WorkingDir). WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"` + // Probes — startup, liveness, and readiness probe configuration. + Probes *ProbesConfig `yaml:"probes,omitempty" json:"probes,omitempty"` + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). @@ -730,18 +779,11 @@ type PodTemplateSource struct { // Annotations — applied to Pod metadata. Values support template expressions. Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty" validate:"omitempty"` - // Resources — static CPU and memory requests/limits. + // Resources — CPU and memory requests/limits for the primary container. + // Set resources.profile for a named preset, or resources.requests/limits for + // explicit values. Profile and explicit values are mutually exclusive. Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"` - // ResourceProfile — semantic CPU/memory preset for the primary container. - // Profiles expand into a complete ResourceRequirements struct during katalog - // enrichment. Allowed values: tiny, small, medium, large, burst, steady, - // compute-heavy, memory-heavy. - // - // When resourceProfile is set, manual resources.requests/limits must not be - // provided. Profiles are atomic and fully define resource behavior. - ResourceProfile string `yaml:"resourceProfile" json:"resourceProfile,omitempty" validate:"omitempty"` - // NodeSelector is a selector which must be true for the pod to fit on a node. // Selector which must match a node's labels for the pod to be scheduled on that node. // More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ @@ -786,6 +828,9 @@ type PodTemplateSource struct { // Works alongside the existing Conditions (when:) field which uses AND semantics. AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"` + // Probes — startup, liveness, and readiness probe configuration. + Probes *ProbesConfig `yaml:"probes,omitempty" json:"probes,omitempty"` + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). @@ -903,6 +948,11 @@ type JobTemplateSource struct { // a checked-out repository path. WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"` + // Resources — CPU and memory requests/limits for the container. + // Set resources.profile for a named preset, or resources.requests/limits for + // explicit values. Profile and explicit values are mutually exclusive. + Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"` + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y). @@ -1001,6 +1051,11 @@ type CronJobTemplateSource struct { ConcurrencyPolicy string `yaml:"concurrencyPolicy,omitempty" json:"concurrencyPolicy,omitempty"` StartingDeadlineSeconds string `yaml:"startingDeadlineSeconds,omitempty" json:"startingDeadlineSeconds,omitempty"` + // Resources — CPU and memory requests/limits for the container. + // Set resources.profile for a named preset, or resources.requests/limits for + // explicit values. Profile and explicit values are mutually exclusive. + Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"` + // ForEach declares dynamic expansion over a list field. // When set, one source declaration becomes N declarations — one per list element. // .item and . are available in template expressions within this declaration. @@ -1594,6 +1649,25 @@ type PDBTemplateSource struct { } // StatefulSetTemplateSource declares one StatefulSet to be managed by Orkestra. +// VolumeClaimTemplateSource declares one PersistentVolumeClaim template for a StatefulSet. +// Each StatefulSet pod receives its own PVC created from this template. +type VolumeClaimTemplateSource struct { + // Name — PVC template name. Default: "data". + Name string `yaml:"name" json:"name,omitempty"` + + // StorageClass — storage class to provision from. Required. + StorageClass string `yaml:"storageClass" json:"storageClass"` + + // StorageSize — requested storage size (e.g. "10Gi"). Required. + StorageSize string `yaml:"storageSize" json:"storageSize"` + + // MountPath — path inside the container to mount this volume. Default: "/data". + MountPath string `yaml:"mountPath" json:"mountPath,omitempty"` + + // AccessModes — defaults to ["ReadWriteOnce"]. + AccessModes []string `yaml:"accessModes" json:"accessModes,omitempty"` +} + type StatefulSetTemplateSource struct { Version string `yaml:"version" json:"version,omitempty"` @@ -1624,14 +1698,8 @@ type StatefulSetTemplateSource struct { // Default: same as Name. ServiceName string `yaml:"serviceName" json:"serviceName,omitempty"` - // StorageClass — storage class for auto-generated VolumeClaimTemplates. - StorageClass string `yaml:"storageClass" json:"storageClass,omitempty"` - - // StorageSize — size of each volume claim (e.g. "10Gi"). Required when StorageClass is set. - StorageSize string `yaml:"storageSize" json:"storageSize,omitempty"` - - // MountPath — mount path for the storage volume inside the container. Default: "/data". - MountPath string `yaml:"mountPath" json:"mountPath,omitempty"` + // VolumeClaimTemplates — one or more PVC templates; each pod gets its own volume per entry. + VolumeClaimTemplates []VolumeClaimTemplateSource `yaml:"volumeClaimTemplates" json:"volumeClaimTemplates,omitempty"` // NodeSelector is a selector which must be true for the pod to fit on a node. // Selector which must match a node's labels for the pod to be scheduled on that node. @@ -1651,24 +1719,18 @@ type StatefulSetTemplateSource struct { EnvFrom []EnvFromSource `yaml:"envFrom,omitempty" json:"envFrom,omitempty"` // Resources — CPU and memory requests/limits for the primary container. - // Values are static Kubernetes quantity strings. - // Template expressions are not supported in resource quantities. + // Set resources.profile for a named preset, or resources.requests/limits for + // explicit values. Profile and explicit values are mutually exclusive. Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"` - // ResourceProfile — semantic CPU/memory preset for the primary container. - // Profiles expand into a complete ResourceRequirements struct during katalog - // enrichment. Allowed values: tiny, small, medium, large, burst, steady, - // compute-heavy, memory-heavy. - // - // When resourceProfile is set, manual resources.requests/limits must not be - // provided. Profiles are atomic and fully define resource behavior. - ResourceProfile string `yaml:"resourceProfile" json:"resourceProfile,omitempty" validate:"omitempty"` - Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty"` Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"` AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"` ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"` + // Probes — startup, liveness, and readiness probe configuration. + Probes *ProbesConfig `yaml:"probes,omitempty" json:"probes,omitempty"` + // Sleep injects an artificial delay into the reconcile of this resource. // Useful for autoscale testing, latency simulation, and chaos engineering. // Accepts extended duration units (s, m, h, d, w, mo, y).