Skip to main content

Architecture Overview

This section contains architecture diagrams and documentation for Flyte.

Available Diagrams​

Flyte System Context Diagram​

This system context diagram illustrates the high-level architecture of the Overview backend service and its interactions with users and external systems.

The central component is the Flyte Backend Service, which is implemented as a unified service (as seen in the manager package) providing a gRPC/Connect API for all operations. Users interact with this service primarily through the FlyteConsole (UI) and the flytectl (CLI).

The service maintains its state and workflow metadata in a relational Database (supporting both PostgreSQL and SQLite). Workflow artifacts, including inputs and outputs, are stored in Cloud Storage (supporting AWS S3, Google Cloud Storage, and Azure Blob Storage via the stow library).

Workflow execution is orchestrated on a Kubernetes Cluster, where the Workflow Executor (part of the backend service) manages the lifecycle of tasks, often leveraging specialized operators for Spark, Ray, and Dask.

For performance and security, the system integrates with Redis for caching and external Secret Managers (AWS, GCP, or Azure) for sensitive credentials. Observability is provided through integration with Prometheus for metrics and Jaeger/OTLP for distributed tracing.

Key Architectural Findings:

  • The Flyte backend is structured as a unified service (Manager) that bundles multiple sub-services like RunService, AppService, and DataProxy.
  • The system uses the Connect RPC framework, making its API compatible with both gRPC and standard HTTP/1.1 clients.
  • Database support is flexible, with PostgreSQL used for production and SQLite available for local development and testing.
  • Cloud storage abstraction (via the stow library) allows Flyte to work across AWS, GCP, and Azure.
  • The Workflow Executor component uses the Kubernetes controller-runtime to manage task execution as native Kubernetes resources.
  • Secret management is delegated to cloud-native services like AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault.

Flyte Internal Component Architecture​

The Flyte internal architecture is centered around a unified manager that orchestrates several modular services. The runs.service acts as the primary entry point for users, managing the lifecycle of workflow runs and persisting state to a database. It delegates the execution of individual tasks to the actions.service, which translates them into Kubernetes Custom Resources (TaskActions).

The executor.pkg.controller is a Kubernetes-based reconciler that watches these TaskAction resources. It leverages the Task Plugin System machinery to execute the actual work, whether it's a standard Kubernetes Pod or a specialized job like Spark or Ray. During execution, the executor reports progress and terminal states through the events.service, which proxies these updates back to the runs service to maintain a consistent view of the system.

Data management is handled by flytestdlib.storage, providing a unified interface for interacting with object stores (S3, GCS, etc.). The dataproxy service facilitates log streaming and data movement, while the cache_service optimizes execution by managing task output memoization. This modular design allows Flyte to scale execution across Kubernetes clusters while maintaining a centralized management plane.

Key Architectural Findings:

  • The 'manager' is a unified entry point that initializes and mounts all sub-services (runs, actions, events, cache, dataproxy, executor).
  • The 'runs.service' implements both public workflow APIs and an 'InternalRunService' used for recording execution events.
  • The 'actions.service' acts as a bridge between the Flyte API and Kubernetes, managing 'TaskAction' CRDs.
  • The 'executor' is a Kubernetes controller that uses 'flyteplugins' to execute tasks and 'events.service' to report status back to the 'runs.service'.
  • 'flytestdlib.storage' provides a common 'DataStore' abstraction used by the API, executor, and plugins for input/output handling.

Workflow Execution and Event Flow​

This sequence diagram traces the lifecycle of a workflow run from its initial creation through execution and event logging.

The flow begins with a runs.service receiving a CreateRun request. It persists the initial run state in the flytestdlib.database and then enqueues the root action via the ActionsService. The ActionsClient (part of the Actions service) creates a TaskAction Custom Resource (CR) in Kubernetes.

The executor (specifically the TaskActionReconciler) watches for these TaskAction resources. During reconciliation, it invokes a plugin (e.g., Kubernetes Resource Plugins) to manage the actual execution (like creating a Pod). As the execution progresses, the executor reports events back to the EventsRecorder (implemented as EventsProxyService), which forwards them to the runs.service to be recorded in the flytestdlib.database.

Simultaneously, the ActionsClient watches for status updates on the TaskAction CR and synchronizes these changes back to the runs.service, ensuring the database reflects the current phase of execution.

Key Architectural Findings:

  • The runs.service acts as the primary entry point for creating runs and managing their state in the database.
  • The ActionsService and its ActionsClient bridge the gap between the gRPC API and Kubernetes Custom Resources (TaskAction).
  • The executor is a Kubernetes controller that reconciles TaskAction resources using specialized plugins like flyteplugins.k8s.
  • Event logging is handled by the EventsProxyService, which synchronously forwards execution events from the executor to the run service.
  • State synchronization is bidirectional: the executor updates the TaskAction status, and the ActionsClient watches those updates to update the central database.

Flyte Domain Data Model​

The data model for Flyte centers around the Action entity, which serves as the base for both workflow runs and individual task executions. A Run is simply a root Action (where ParentActionName is null). Actions are linked to Task definitions and can be initiated by a Trigger. The lifecycle of an Action is tracked through ActionEvent records, which capture phase transitions and error information. Metadata such as secret and Workflow & Run Management definitions are scoped by Project and Domain. The model uses serialized protobuf messages (e.g., ActionSpec, ActionDetails) to store complex, versioned domain data while denormalizing key fields for efficient querying.

Key Architectural Findings:

  • 'Run' is a type alias for 'Action'; root actions represent workflow runs while child actions represent tasks or sub-workflows.
  • 'ActionEvent' provides an append-only history of phase transitions for an 'Action', enabling detailed observability.
  • 'Task' and 'Trigger' entities manage the definitions and automation rules for executable units.
  • 'Secret' entities are managed as Kubernetes secrets but are logically scoped to Flyte projects and domains.
  • The data model heavily relies on composite primary keys (Project, Domain, Name/RunName) to ensure uniqueness across the multi-tenant system.

Flyte Production Deployment Architecture​

The deployment architecture of Flyte is centered around a unified backend service and a web console, both typically deployed on a Using Kubernetes Secrets cluster.

The Flyte Binary is a single container that consolidates multiple microservices, including the Workflow & Run Management, Execution Engine, and Data Proxy and Translation Services. It acts as a Kubernetes controller, interacting with the K8s Control Plane to orchestrate Task Pods.

For data persistence, Flyte relies on an external PostgreSQL instance for metadata and Object Storage (such as AWS S3 or Google Cloud Storage) for large data artifacts.

The Flyte Console provides a web-based interface for users, communicating with the Flyte Binary via an Ingress layer that handles both HTTP and gRPC traffic.

Within the execution environment, Flyte Copilot is injected into user-defined Task Pods as both an init container (for downloading inputs) and a sidecar (for uploading outputs), ensuring seamless data movement between the task's local environment and the central object store.

Key Architectural Findings:

  • Flyte is primarily deployed as a unified binary (flyte-binary) that bundles multiple services like manager, runs, and executor into a single container.
  • The system uses a sidecar pattern called Flyte Copilot, which is injected into user task pods to handle data ingress and egress.
  • Metadata is stored in a PostgreSQL database, while workflow artifacts and user data are stored in cloud-native Object Storage (S3/GCS/Azure).
  • The Flyte Binary acts as a Kubernetes operator, managing the lifecycle of Task Pods and Custom Resource Definitions (CRDs) like TaskActions.
  • Traffic is routed through a Kubernetes Ingress, supporting both REST/HTTP and gRPC protocols for the console and CLI tools.

Workflow Run Lifecycle States​

The state architecture diagram illustrates the lifecycle of a Understanding Runs and Actions (represented as an Action in the system) as it transitions through various phases managed by the executor and external events.

The lifecycle begins in the Queued state upon creation. From there, it typically moves through WaitingForResources and Initializing as the system allocates compute resources and performs setup (like pulling container images). Once the task starts executing, it enters the Running state.

Terminal states include Succeeded, Failed, Aborted, and TimedOut. A run can transition to Succeeded directly from Queued if a cache hit is detected. Conversely, it may transition to Failed if validation fails or a permanent error occurs. Retryable failures trigger a transition from Running back to Queued, incrementing the attempt count until the maximum is reached.

Condition Actions introduce a Paused state, where the run awaits an external signal before proceeding to a terminal state. The diagram also captures the ability for a user to Abort a run from any non-terminal state.

Key Architectural Findings:

  • Workflow runs are internally represented as Actions, and their lifecycle is governed by the ActionPhase enum.
  • The initial state for any new run is ACTION_PHASE_QUEUED.
  • Transitions are managed by the TaskActionReconciler, which maps plugin-specific phases to the global ActionPhase.
  • Cache hits allow a run to short-circuit directly from Queued to Succeeded.
  • Retry logic is implemented by transitioning from Running back to Queued when a retryable failure occurs and attempts remain.
  • Terminal states are defined as Succeeded, Failed, Aborted, and TimedOut.
  • Condition actions utilize a Paused state to wait for external signals.