first commit

README.md

@@ -0,0 +1,125 @@
+# ocdp-workload-manifests
+
+Standalone Kubernetes manifests for OCDP workloads.
+
+This repository is intentionally just a Git repository of app manifests. There is
+no global catalog index and no dependency on the Gitea API. `ocdp-server` can
+read a workload by building a Kustomize target directly from Git.
+
+## Architecture
+
+OCDP keeps the responsibilities split:
+
+```text
+Git repo
+  apps/<app>/base
+  apps/<app>/components
+
+ocdp-server PostgreSQL
+  WorkloadTemplate metadata
+  WorkloadTemplate source.repositoryUrl/ref/path
+  user-facing values schema / parameters
+  environment overlay/profile metadata
+  access bindings
+  no WorkloadClaim instance storage
+
+target cluster
+  WorkloadClaim CR as the canonical user claim
+  Workload CR
+  runtime Kubernetes resources
+```
+
+This repository stores only the Git base and reusable components. It does not
+store `WorkloadTemplate` records and does not store user `WorkloadClaim`
+instances.
+
+An admin creates or updates a `WorkloadTemplate` in `ocdp-server`. That template
+can point at one of these Git paths:
+
+```yaml
+templateType: kustomize
+source:
+  type: gitKustomize
+  repositoryUrl: https://gitea.example.com/ocdp/ocdp-workload-manifests.git
+  ref: code-server-v0.1.0
+  path: apps/code-server/base
+```
+
+After the template is stored in PostgreSQL and assigned to users or groups, users
+call `ocdp-server` to create a claim by submitting `templateId`, `workspaceId`,
+and values. `ocdp-server` resolves the template from PostgreSQL, reads the Git
+base, generates any temporary source files or runtime specs outside this repo,
+then writes a `WorkloadClaim` CR into the target Kubernetes cluster. The final
+user-created claim lives in Kubernetes, not in PostgreSQL.
+
+## Layout
+
+```text
+apps/
+  code-server/
+    base/
+    components/
+  vllm-server/
+    base/
+    components/
+  litellm/
+    base/
+    components/
+tests/
+  kustomize/
+```
+
+## Server Usage
+
+`ocdp-server` should store a normal `gitKustomize` reference:
+
+```yaml
+source:
+  type: gitKustomize
+  repositoryUrl: https://gitea.example.com/ocdp/ocdp-workload-manifests.git
+  ref: code-server-v0.1.0
+  path: apps/code-server/base
+```
+
+For one deployment, `ocdp-server` should generate temporary source files outside
+this repository. Those files can point at the Git base and add generated
+Secrets, ConfigMaps, components, and patches.
+
+## Exposure
+
+Base services are `ClusterIP`. User-facing exposure choices such as
+`clusterip`, `nodeport`, and `loadbalancer` belong in the WorkloadTemplate
+values schema. `ocdp-server` can translate that value into runtime Service
+configuration or a generated patch.
+
+Reusable components are still useful implementation building blocks:
+
+- `components/ingress`: keep the app Service internal and route through an
+  ingress controller.
+- `components/service-loadbalancer`: change the app Service to `LoadBalancer`.
+- `components/service-nodeport`: change the app Service to `NodePort`.
+
+When `nodeport` is selected by the user, `ocdp-server` may generate an instance
+patch or runtime Service field for an explicit port:
+
+```yaml
+- op: add
+  path: /spec/ports/0/nodePort
+  value: 30080
+```
+
+Do not hard-code shared NodePort values in app bases or reusable components.
+
+Environment overlays are different from user choices. They are selected by the
+platform from cluster, workspace, or customer profile information and can carry
+things like StorageClass, IngressClass, GPU runtime class, registry prefix,
+pull-secret wiring, node selectors, tolerations, and site-specific labels.
+
+## Validate
+
+```bash
+make validate
+```
+
+`make validate` runs `kubectl kustomize` against non-user test overlays under
+`tests/kustomize`.