|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## What This Repository Is |
| 6 | + |
| 7 | +The Kubeflow Manifests repository provides production-ready Kubernetes manifests for deploying the complete Kubeflow AI platform. The primary mechanism is Kustomize; everything can be installed with a single `kustomize build example | kubectl apply` invocation, or component by component via individual overlays. |
| 8 | + |
| 9 | +## Commands |
| 10 | + |
| 11 | +### Linting |
| 12 | + |
| 13 | +Pre-commit hooks are the primary linting mechanism. They are scoped to non-upstream code only (`**/upstream/**` is excluded from all hooks). |
| 14 | + |
| 15 | +```bash |
| 16 | +# Install hooks (once) |
| 17 | +pip install pre-commit |
| 18 | +pre-commit install |
| 19 | + |
| 20 | +# Run all hooks against staged files |
| 21 | +pre-commit run |
| 22 | + |
| 23 | +# Run all hooks against the entire repository |
| 24 | +pre-commit run --all-files |
| 25 | +``` |
| 26 | + |
| 27 | +Individual linters: |
| 28 | +```bash |
| 29 | +# YAML (common/, example/, hack/, tests/, .github/) |
| 30 | +yamllint --config-file=.yamllint.yaml <file> |
| 31 | + |
| 32 | +# Python (common/, example/ only) |
| 33 | +black --check common/ example/ |
| 34 | + |
| 35 | +# Bash (everything except applications/ and upstream) |
| 36 | +shellcheck <script.sh> |
| 37 | +``` |
| 38 | + |
| 39 | +### Building / Rendering Manifests |
| 40 | + |
| 41 | +```bash |
| 42 | +# Render the full platform |
| 43 | +kustomize build example |
| 44 | + |
| 45 | +# Render a single component |
| 46 | +kustomize build applications/jupyter/notebook-controller/upstream/base |
| 47 | + |
| 48 | +# Apply to a cluster (with retry — resources may have ordering dependencies) |
| 49 | +while ! kustomize build example | kubectl apply --server-side --force-conflicts -f -; do |
| 50 | + echo "Retrying to apply resources" |
| 51 | + sleep 20 |
| 52 | +done |
| 53 | +``` |
| 54 | + |
| 55 | +### Installation Testing (E2E) |
| 56 | + |
| 57 | +Tests live in `tests/`. Each script installs one component and waits for it to become ready. Run them in order: |
| 58 | + |
| 59 | +```bash |
| 60 | +./tests/install_KinD_create_KinD_cluster_install_kustomize.sh # cluster + kustomize |
| 61 | +./tests/cert_manager_install.sh |
| 62 | +./tests/istio-cni_install.sh |
| 63 | +./tests/oauth2-proxy_install.sh |
| 64 | +./tests/dex_install.sh |
| 65 | +./tests/multi_tenancy_install.sh |
| 66 | +./tests/central_dashboard_install.sh |
| 67 | +# ... component scripts as needed |
| 68 | +``` |
| 69 | + |
| 70 | +### Helm / Kustomize Comparison |
| 71 | + |
| 72 | +```bash |
| 73 | +./tests/helm_kustomize_compare.sh <component> <scenario> |
| 74 | +# e.g.: katib, model-registry, kserve-models-web-app, notebook-controller |
| 75 | +``` |
| 76 | + |
| 77 | +## Architecture |
| 78 | + |
| 79 | +### Directory Layout |
| 80 | + |
| 81 | +``` |
| 82 | +applications/ # Per-component manifests (dashboard, jupyter, pipeline, kserve, …) |
| 83 | +common/ # Shared infrastructure (Istio, Knative, Dex, OAuth2-Proxy, cert-manager, …) |
| 84 | +experimental/ # Third-party integrations not yet in the main platform (Ray, Helm charts) |
| 85 | +example/ # Single kustomization.yaml composing the full platform |
| 86 | +tests/ # E2E installation scripts and Helm/Kustomize comparison tooling |
| 87 | +scripts/ # Upstream synchronization scripts |
| 88 | +releases/ # Release handbook and versioning notes |
| 89 | +proposals/ # Architecture proposals |
| 90 | +``` |
| 91 | + |
| 92 | +### Kustomize Structure Pattern |
| 93 | + |
| 94 | +Every component follows the same layered pattern: |
| 95 | + |
| 96 | +``` |
| 97 | +<component>/ |
| 98 | + upstream/ # Verbatim copy of the upstream project's manifests (do NOT edit) |
| 99 | + base/ # Minimal overlay on top of upstream |
| 100 | + overlays/ # Cluster-specific variants (gke, eks, aks, kind, …) |
| 101 | + components/ # Optional reusable Kustomize components |
| 102 | +``` |
| 103 | + |
| 104 | +`upstream/` directories are excluded from linting and are regenerated by the synchronization scripts in `scripts/`. |
| 105 | + |
| 106 | +### Deployment Ordering |
| 107 | + |
| 108 | +`example/kustomization.yaml` lists resources in a specific order that Kubernetes requires: |
| 109 | + |
| 110 | +1. Namespaces, ResourceQuotas, StorageClasses |
| 111 | +2. CRDs |
| 112 | +3. Mutating / Validating Webhooks |
| 113 | +4. RBAC (ServiceAccounts, Roles, ClusterRoles, Bindings) |
| 114 | +5. ConfigMaps, Secrets |
| 115 | +6. Services, Deployments, StatefulSets |
| 116 | +7. Validating Webhooks (must be last) |
| 117 | + |
| 118 | +This order matters; the retry loop in CI works around Kubernetes not guaranteeing CRD availability before dependents. |
| 119 | + |
| 120 | +### Authentication Flow |
| 121 | + |
| 122 | +Default: Dex (OIDC provider) → OAuth2-Proxy → Istio AuthorizationPolicy → application. |
| 123 | + |
| 124 | +Default credentials (`user@example.com` / `12341234`) are in `common/dex/` and **must** be changed for any non-local deployment. |
| 125 | + |
| 126 | +## Coding Standards |
| 127 | + |
| 128 | +These come from `.github/copilot-instructions.md` and apply to all code, commit messages, and PR descriptions in this repository: |
| 129 | + |
| 130 | +- **No abbreviations.** Use the full word: `application` not `app`, `dependencies` not `dep` or `deps`, `repository` not `repo`, `synchronization` not `sync`, `development` not `dev`, `production` not `prod`, `temporary` not `temp`/`tmp`, `authentication` or `authorization` (never bare `auth`), `deployment` not `deploy`, `credentials` not `cred`, `documentation` not `doc`, `difference` not `diff`. Well-known acronyms (OIDC, API, CPU, GPU) are fine. |
| 131 | +- **Trunk-based development** on the `master` branch. |
| 132 | +- **Linux only** — no macOS or Windows compatibility concerns. |
| 133 | +- **What is not tested is not supported.** |
| 134 | + |
| 135 | +## Upstream Synchronization |
| 136 | + |
| 137 | +Components track upstream releases. To update a component, use the corresponding script: |
| 138 | + |
| 139 | +```bash |
| 140 | +# Example — update notebook manifests |
| 141 | +./scripts/synchronize-notebooks-manifests.sh <upstream-tag> |
| 142 | +``` |
| 143 | + |
| 144 | +These scripts fetch the upstream release, place it under `upstream/`, and open a PR. Never hand-edit files under `upstream/`. |
0 commit comments