Add V2 docs for flyte core deployment - #1556
Conversation
…e-core pages
The AWS deployment guide only ever covered the flyte-binary chart, but the
repo also ships flyte-core — the distributed chart that runs one Deployment
per component (runs, actions, events, cache, dataproxy, secret, executor,
app). Nothing in content/ documented it.
Turn aws-deployment into a section with a landing page that picks between the
two charts, keeping the existing /oss-deployment/aws-deployment URL:
- aws-deployment/_index.md: chart comparison and the warning that the two
values schemas are not interchangeable.
- aws-deployment/flyte-binary.md: the previous page, moved. Fixes the one-off
{{< WARNING >}} shortcode (no other page in the repo uses that form; every
other notice is > [!WARNING]) and moves the trailing "Next:" pointer, which
sat ~150 lines before the end of the page, to the actual end.
- aws-deployment/flyte-core.md: new, mirroring the flyte-binary structure step
for step, plus a values-differences table.
Every YAML block on the flyte-core page was validated with `helm template`
against charts/flyte-core; the full EKS example renders 8 Deployments and a
15-path fan-out ingress. Notable things the chart does differently and the
page calls out: configuration.runs.storagePrefix (not
flyte-core-components.runs.storagePrefix), the service account being named
flyte-service-account rather than flyte, the executor being pinned to one
replica, and configuration.inline shipping a non-empty default-env-vars that
a user-supplied list silently replaces.
Not done: overview.md still describes only the single-binary architecture.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PfQZ6UXpmynAtFsAHwJnyz
Signed-off-by: Alex Wu <c.alexwu@gmail.com>
Signed-off-by: Alex Wu <c.alexwu@gmail.com>
GHA build & deploy previewBuilt by
Updated automatically on every push. |
There was a problem hiding this comment.
🟡 Changes recommended
There are minor but user-facing documentation clarity/wording issues to address before the new two-chart deployment structure is fully consistent for readers.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds Flyte v2 documentation for deploying the flyte-core Helm chart on AWS (multi-pod / one Deployment per component) and reorganizes the AWS deployment docs to clearly present both flyte-binary and flyte-core paths within the OSS deployment section.
Changes:
- Added a new
flyte-coreAWS deployment guide and an AWS deployment landing page to select between charts. - Updated the existing AWS deployment guide to be explicitly
flyte-binary, including updated cross-links and admonition formatting. - Normalized internal links across OSS deployment pages to point at the new AWS deployment section index.
File summaries
| File | Description |
|---|---|
| content/oss-deployment/overview.md | Updates the AWS deployment link target to the new AWS section index. |
| content/oss-deployment/kind-deployment/_index.md | Updates references to AWS deployment to point at the new AWS section index. |
| content/oss-deployment/aws-deployment/flyte-core.md | Adds a new, detailed AWS deployment guide for the flyte-core chart (multi-Deployment topology). |
| content/oss-deployment/aws-deployment/flyte-binary.md | Renames/reframes the existing AWS deployment guide as flyte-binary and updates cross-links/admonitions. |
| content/oss-deployment/aws-deployment/_index.md | Adds a new landing page for AWS deployments to choose between flyte-binary and flyte-core. |
| content/oss-deployment/app-serving.md | Updates AWS deployment prerequisite link to point at the new AWS section index. |
| content/oss-deployment/_index.md | Updates the platform deployment overview to describe both Helm chart options and links accordingly. |
Review details
- Files reviewed: 7/7 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| Both charts read the same underlying Flyte configuration and expose the same API, so | ||
| the choice is about operations, not features. The `flyte-core` guide is written to | ||
| mirror the `flyte-binary` one step for step, so you can compare them side by side. |
There was a problem hiding this comment.
F10 agreed. Folded into the F5 suggestion on this file, which rewrites that sentence.
| When you're ready, continue to the | ||
| [Kind deployment](./kind-deployment/_index) to try Flyte on a kind cluster, | ||
| or the [AWS deployment](./aws-deployment) guide for a real deployment. | ||
| or the [AWS deployment](./aws-deployment/_index) guide for a real deployment. |
There was a problem hiding this comment.
F9 confirmed, and it goes further than the link. overview.md is single-binary throughout: "Flyte runs as a single unified binary ... one process" (L17), a mermaid node labelled Flyte binary (unified) (L39), and an image table keyed to deployment.image (L150), which is a flyte-binary values path. Both new pages send readers there for prerequisites.
One thing that makes the fix easier than it looks: every flyte-core component runs the same cr.flyte.org/flyteorg/flyte-binary-v2 image. So the accurate note is that the binary is unchanged and only the pod topology differs, not that there are two architectures.
ppiegaze
left a comment
ppiegaze
left a comment
There was a problem hiding this comment.
Reviewed at 661b9bfd against flyteorg/flyte@origin/main and the rendered charts. The chart facts hold up well: the component set, the ingress route table, the executor replica pin, and the default-env-vars replacement warning are all exactly right, and the minimal values file installs clean. 14 changes, 4 blocking, one of which is only merge ordering against flyte-agent-plugins#42.
| ID | Finding | Where | Blocking |
|---|---|---|---|
| F1 | TIP depends on flyte-agent-plugins#42, still open | flyte-core.md:26 | yes |
| F2 | Ingress snippet omits the health-check path; ALB 503s | flyte-core.md:208 | yes |
| F3 | Executor has no 8080; probes are on 8081 | flyte-core.md:276 | yes |
| F4 | extraInlineSecretRefs key must end .yaml or it is ignored |
flyte-core.md:529 | yes |
| F5 | "expose the same API" is not accurate | _index.md:23 | no |
| F6 | defaultK8sServiceAccount is a pass-through, not a values key |
flyte-core.md:553 | no |
| F7 | Schema incompatibility is one-directional | _index.md:30 | no |
| F8 | Uninstall deletes the TaskAction CRD | flyte-core.md:293 | no |
| F9 | overview.md is single-binary throughout |
overview.md | no |
| F10 | "step for step" hyphenation | _index.md:25 | no |
| F11 | 13 deep anchors on the old URL stop resolving | section move | no |
| F12 | Em-dash density vs the rest of the section | flyte-core.md | no |
| F13 | Children listed twice on the landing page | _index.md:36 | no |
| F14 | _U_EP_OVERRIDE could use the chart's tpl expression |
flyte-core.md:479 | no |
— docsy · automated docs agent · run report
| > [!TIP] Deploy this with an AI assistant | ||
| > [`flyte-agent-plugins`](https://github.com/flyteorg/flyte-agent-plugins) — a | ||
| > portable agent harness plugin for Claude Code, Codex, OpenCode, and other | ||
| > harnesses — includes a `flyte-deploy-aws-core` skill that provisions a Flyte v2 |
There was a problem hiding this comment.
F1 blocking on ordering: flyte-deploy-aws-core is added by flyteorg/flyte-agent-plugins#42, which is still open. Until that merges this TIP points at a skill readers cannot install. Either land #42 first, or drop the TIP and add it back after.
| host: <flyte.example.com> | ||
| # Your cloud's native ingress class, e.g. alb (EKS), gce (GKE), | ||
| # azure-application-gateway (AKS). See the Deployment overview for the options. | ||
| ingressClassName: <ingress-class> |
There was a problem hiding this comment.
F2 blocking: with no health-check annotation the ALB probes each target group at /, and nothing serves it. Only /healthz and /readyz are registered (flytestdlib/app/app.go:95), so all six API target groups go unhealthy and the ALB returns 503. The annotation appears only in the full example at the foot of the page.
| ingressClassName: <ingress-class> | |
| ingressClassName: <ingress-class> | |
| httpAnnotations: | |
| # Components serve /healthz, not /. Without this the ALB probes / and marks | |
| # every API target group unhealthy. | |
| alb.ingress.kubernetes.io/healthcheck-path: /healthz |
| Every component serves `/healthz` and `/readyz` on its own port 8080, and the chart | ||
| wires both into the pod's liveness and readiness probes — so `Running` **and** ready | ||
| across all of them is the health check: |
There was a problem hiding this comment.
F3 blocking: the executor has no port 8080. Its ports are 9443, 9444, 10254 and health, and both probes point at health, which is configuration.executor.healthProbePort, default 8081 (executor/deployment.yaml:110).
| Every component serves `/healthz` and `/readyz` on its own port 8080, and the chart | |
| wires both into the pod's liveness and readiness probes — so `Running` **and** ready | |
| across all of them is the health check: | |
| Seven of the eight components serve `/healthz` and `/readyz` on their API port (8080 by | |
| default). The executor is a controller with no API port: it serves both on | |
| `configuration.executor.healthProbePort`, default 8081. The chart wires them into each | |
| pod's liveness and readiness probes, so `Running` **and** ready across all of them is | |
| the health check: |
| To keep the **database password** out of the values file too, leave | ||
| `configuration.database.postgres.password` empty and either: | ||
|
|
||
| - reference an existing Kubernetes Secret with `configuration.extraInlineSecretRefs`, or |
There was a problem hiding this comment.
F4 blocking: this silently does nothing as written. The Secret is projected whole into /etc/flyte/config.d, which every component loads as *.yaml (values.yaml:23), so the Secret's key has to end in .yaml and hold a config fragment. A Secret with key password is never read: the password stays empty and flyte-runs fails to reach the database with nothing in the logs. Same applies at L537.
| - reference an existing Kubernetes Secret with `configuration.extraInlineSecretRefs`, or | |
| - reference an existing Kubernetes Secret with `configuration.extraInlineSecretRefs` | |
| (the Secret is projected whole into `/etc/flyte/config.d` and loaded as `*.yaml`, so | |
| its key must end in `.yaml` and hold a config fragment, for example a key | |
| `012-db-secret.yaml` setting `database.postgres.password`; a key named `password` is | |
| never read), or |
| Both charts read the same underlying Flyte configuration and expose the same API, so | ||
| the choice is about operations, not features. The `flyte-core` guide is written to | ||
| mirror the `flyte-binary` one step for step, so you can compare them side by side. |
There was a problem hiding this comment.
F5 nit: the API surfaces are not identical. flyte-binary's ingress routes RunLogsService and SettingsService; flyte-core routes neither, from any component. The bundled connector also differs: flyte-core sets flyteconnector.enabled: false, while flyte-binary has no such key, so the dependency renders by default. F10 folded in here.
| Both charts read the same underlying Flyte configuration and expose the same API, so | |
| the choice is about operations, not features. The `flyte-core` guide is written to | |
| mirror the `flyte-binary` one step for step, so you can compare them side by side. | |
| Both charts read the same underlying Flyte configuration and run the same binary image, | |
| so the choice is mostly about operations. The API surfaces are close but not identical: | |
| `flyte-core`'s ingress routes neither `RunLogsService` nor `SettingsService`, and the | |
| bundled connector is enabled by default only on `flyte-binary`. The `flyte-core` guide | |
| is written to mirror the `flyte-binary` one step-for-step, so you can compare them side | |
| by side. |
| | Run storage prefix | `flyte-core-components.runs.storagePrefix` | `configuration.runs.storagePrefix` | | ||
| | Task-pod namespace | `flyte-core-components.actions.kubernetes.namespace` | `configuration.kubernetes.namespace` | | ||
| | Data proxy upload/download | `flyte-core-components.dataproxy.*` | `configuration.dataproxy.*` | | ||
| | Task service account | `configuration.inline.executor.defaultK8sServiceAccount` | `configuration.executor.defaultK8sServiceAccount` (a real values key) | |
There was a problem hiding this comment.
F6 nit: defaultK8sServiceAccount is not in flyte-core/values.yaml. It reaches the config only because executor/configmap.yaml:23 dumps all of configuration.executor into the executor: section, and there is no values.schema.json to catch a typo. It works, but it will not show up in helm show values.
| | Task service account | `configuration.inline.executor.defaultK8sServiceAccount` | `configuration.executor.defaultK8sServiceAccount` (a real values key) | | |
| | Task service account | `configuration.inline.executor.defaultK8sServiceAccount` | `configuration.executor.defaultK8sServiceAccount` (a pass-through, not in `values.yaml`) | |
| > [!NOTE] The values schemas are not interchangeable | ||
| > The two charts organize their values differently — `flyte-binary` nests service | ||
| > settings under `flyte-core-components`, `flyte-core` under `configuration` and | ||
| > `components`. A `values.yaml` written for one chart will not install the other. |
There was a problem hiding this comment.
F7 nit: this holds in one direction only. flyte-core values on flyte-binary fail loudly with a template error. flyte-binary values on flyte-core render fine and install, silently ignoring flyte-core-components, deployment, enabled_plugins and configuration.logging.plugins. The silent direction is the one worth the warning.
| > `components`. A `values.yaml` written for one chart will not install the other. | |
| > `components`. A `values.yaml` written for `flyte-core` fails loudly on `flyte-binary`, | |
| > but one written for `flyte-binary` installs on `flyte-core` and silently ignores every | |
| > `flyte-core-components`, `deployment` and `enabled_plugins` setting in it. |
|
|
||
| ```bash | ||
| helm uninstall flyte -n flyte | ||
| kubectl delete namespace flyte |
There was a problem hiding this comment.
F8 nit: helm uninstall also deletes the taskactions.flyte.org CRD and cascades to every TaskAction in the cluster. The CRD is an ordinary template rather than a crds/ entry, so Helm owns it. Worth a sentence here, next to the note that the external dependencies survive.
|
Four non-blocking nits, no reply needed on any of them. F11 the old URL keeps returning 200 but its content becomes the signpost, so 13 heading anchors on it ( F12 em-dashes run at 4.8 per 100 lines in F13 F14 — docsy · automated docs agent · run report |
Goal
V2 support flyte core helm charts to do multi pods deployment now. This PR add a doc to guild user to do so.