Skip to content

docs(specs): add OpenShell branch build spec for kind-openshell-up #148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
squizzi wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs(specs): add OpenShell branch build spec for kind-openshell-up #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
28babbc
docs(specs): add OpenShell branch build spec for kind-openshell-up
squizzi Aug 18, 2026
3941e2c
fix(specs): address openshell-branch-build spec review feedback
squizzi Aug 18, 2026
ed76512
Merge branch 'main' into squizzi/kind-openshell-pr-deploy
squizzi Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions specs/index.spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Machine-readable index for autonomous reconciliation (`/reconcile` skill).
| `security/rbac-enforcement.spec.md` | security | User, Role, RoleBinding, RBAC middleware | API | data-model |
| `standards/security/security.spec.md` | standards | - | ALL | - |
| `platform/local-development.spec.md` | platform | Kind cluster, images, Make targets | ALL | cross-cutting, security |
| `platform/openshell-branch-build.spec.md` | platform | OpenShell branch builds, dev gateway provisioning | ALL | local-development, openshell-gateway |
| `platform/oidc-integration.spec.md` | platform | API JWT validation, BFF OIDC session, IdP client config, Kind opt-in | API, WEB, CP | local-development, openshell-gateway-oidc, web-console/architecture |
| `platform/e2e-testing.spec.md` | platform | Infra drivers, e2e test suite, CI workflow, deploy overlays | ALL | local-development, control-plane, openshell-gateway-routing |
| `platform/api-server-observability.spec.md` | platform | API OTel SDK bootstrap, HTTP/gRPC server spans, W3C trace continuation, request metrics | API | web-console/tracing, security, local-development, e2e-testing |
Expand Down
3 changes: 3 additions & 0 deletions specs/platform/data-model.spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,12 +179,15 @@ A Gateway SHALL include provisioning configuration fields that the control plane
|---|---|---|
| `image` | string | Gateway container image reference (e.g., `ghcr.io/nvidia/openshell/gateway:21da343c9f838bd9ac85dc61bf44889de1a72873`) |
| `supervisor_image` | string | Supervisor sidecar container image (default: `ghcr.io/nvidia/openshell/supervisor:0.0.109`) |
| `sandbox_image` | string | Sandbox base image the gateway uses when launching sandboxes (default: `ghcr.io/nvidia/openshell-community/sandboxes/base:latest`). See [`openshell-gateway.spec.md`](./openshell-gateway.spec.md) |

@jsell-rh jsell-rh Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Minor] Default uses :latest. Same determinism concern as in openshell-branch-build.spec.md - a mutable default here means sandbox_image is not reproducible unless every caller overrides it.

Cross-PR: #201 configures the sandbox base globally via a GATEWAY_SANDBOX_IMAGE env var (images.DefaultSandboxImage()), whereas this PR adds it as a per-Gateway field. Maintainers should decide whether the sandbox base is a global default, a per-Gateway field, or both (env default + field override).

| `server_dns_names` | string[] | DNS names for TLS certificate SANs |
| `oidc` | JSONB | OIDC authentication config: `{issuer, audience, jwks_ttl, roles_claim, admin_role, user_role, scopes_claim}` |
| `route` | JSONB | Route exposure config for GRPCRoute provisioning: `{host}` |
| `route_address` | text | Read-only external address populated by the control plane (e.g., `grpcs://hostname:443`) |
| `database` | JSONB | Database backend config: `{storageSize, image, externalSecretRef}` |
| `credential_driver` | JSONB | Credential storage driver config: `{type, kubernetes_secrets, vault}`. See [`openshell-gateway-credentials.spec.md`](./openshell-gateway-credentials.spec.md) |
| `dev_build` | boolean | Marks this Gateway as a dev/branch build (default: false). Control plane copies to `hypershell.redhat.io/openshell-dev-build` label on K8s resources. See [`openshell-branch-build.spec.md`](./openshell-branch-build.spec.md) |

@jsell-rh jsell-rh Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cross-PR coordination (#151). #151 adds Gateway generation tracking and enumerates the desired-spec fields that bump generation in desiredStateChanged(). sandbox_image (added above) is a desired-spec field and must be included there, or a sandbox-image change won't trigger re-provisioning - which would also break this spec's "branch tip advances -> rebuild -> redeploy" behavior when only the sandbox image differs. dev_build/dev_build_metadata are metadata; decide explicitly whether they should advance generation.

| `dev_build_metadata` | JSONB | Dev build provenance: `{ref, sha, repo}`. Control plane copies to annotations on K8s resources. See [`openshell-branch-build.spec.md`](./openshell-branch-build.spec.md) |

See [`openshell-gateway.spec.md`](./openshell-gateway.spec.md) and its sub-specs for full provisioning details.

Expand Down
4 changes: 4 additions & 0 deletions specs/platform/local-development.spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -783,6 +783,9 @@ The system SHALL deploy a Jaeger all-in-one instance in the local environment an
| `CLOUD_PROVIDER_KIND_REPO` | (pinned in Makefile) | Git repository URL for cloud-provider-kind fork (BackendTLSPolicy + ALPN h2 support) |
| `CLOUD_PROVIDER_KIND_REF` | (pinned in Makefile) | Exact commit SHA of the cloud-provider-kind fork to build (deterministic; idempotent-by-SHA rebuild) |
| `CLOUD_PROVIDER_KIND_BRANCH` | (unset) | Optional testing override: build from a branch tip or arbitrary git ref instead of the pinned SHA; always rebuilds when set |
| `OPENSHELL_REPO` | (canonical upstream OpenShell repo) | Git repository URL to build OpenShell from for `make kind-openshell-up`; override to target a fork |
| `OPENSHELL_BRANCH` | (unset) | OpenShell git ref (branch, tag, or commit) to build gateway/supervisor/sandbox images from for `make kind-openshell-up` |
| `OPENSHELL_PR` | (unset) | Convenience for `make kind-openshell-up`: OpenShell pull request number, resolved to its head ref |
| `KIND_RESTART_CPK` | (unset) | Set to `true` to force `make kind-up` to restart cloud-provider-kind (republishes ephemeral LB ports; otherwise the running instance is reused to keep ports stable) |
| `CERT_MANAGER_VERSION` | `v1.21.1` | cert-manager release version |
| `CNPG_VERSION` | `v1.30.0` | CloudNativePG operator release version |
Expand All @@ -801,6 +804,7 @@ All targets operate on `KIND_NAMESPACE` (default: `hypershell-system`).
| `make kind-teardown` | Destroy the Kind cluster + stop cloud-provider-kind + stop CoreDNS + flush port forwarding rules + revert resolver |
| `make kind-status` | Show cluster info, pods, services, hostnames, DNS status, port forwarding status, and active component swaps |
| `make kind-fix-ports` | Re-establish host port forwarding (443 + 8080) after a cloud-provider-kind restart; re-discovers ephemeral ports and re-runs the stop-then-start flush |
| `make kind-openshell-up` | Build OpenShell (gateway + supervisor + sandbox base) from `OPENSHELL_BRANCH`/`OPENSHELL_PR` + load into cluster (creating it if needed) + seed a dev-labeled gateway running those images. See [`openshell-branch-build.spec.md`](./openshell-branch-build.spec.md) |

@squizzi squizzi Aug 18, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Major] local-development still says this target builds the sandbox base

The follow-up correctly dropped sandbox from the OpenShell checkout. This row (and OPENSHELL_BRANCH at L678) still says “gateway + supervisor + sandbox base.” Implementers of kind-openshell-up will rebuild the contradiction we just closed.

Fix both rows to: build gateway and supervisor from OPENSHELL_BRANCH/OPENSHELL_PR; use the published community sandbox image.

Confidence: High

@squizzi squizzi Aug 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Major] local-development still says this target builds the sandbox base

When make kind-openshell-up runs with OPENSHELL_BRANCH or OPENSHELL_PR set, this row (and OPENSHELL_BRANCH at L787) still says the target builds a sandbox base image. openshell-branch-build.spec.md now says the sandbox image is the published community image and is not built from the OpenShell checkout. Implementers of this Make target will rebuild a contradiction that the follow-up already closed.

Fix both rows to: build gateway and supervisor from OPENSHELL_BRANCH/OPENSHELL_PR; set sandbox_image to the published community image.

Confidence: High

| `make kind-api-server-up` | Build api-server from working tree + load + replace deployment + wait (cluster must exist; idempotent - rebuilds and replaces on every call) |
| `make kind-api-server-down` | Revert api-server to baseline image + restart + wait |
| `make kind-control-plane-up` | Build control-plane from working tree + load + replace deployment + wait (cluster must exist; idempotent - rebuilds and replaces on every call) |
Expand Down
Loading