Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Microsoft OpenPAI FrameworkController

Build Status Latest Release Docker Pulls License

As one standalone component of Microsoft OpenPAI, FrameworkController (FC) is built to orchestrate all kinds of applications on Kubernetes by a single controller, especially for DeepLearning applications.

These kinds of applications include but not limited to:

Why Need It


In the open source community, there are so many specialized Kubernetes Pod controllers which are built for a specific kind of application, such as Kubernetes StatefulSet Controller, Kubernetes Job Controller, KubeFlow TensorFlow Operator, KubeFlow PyTorch Operator. However, no one is built for all kinds of applications and combination of the existing ones still cannot support some kinds of applications. So, we have to learn, use, develop, deploy and maintain so many Pod controllers.


Build a General-Purpose Kubernetes Pod Controller: FrameworkController.

And then we can get below benefits from it:




Framework Feature

A Framework represents an application with a set of Tasks:

  1. Executed by Kubernetes Pod
  2. Partitioned to different heterogeneous TaskRoles which share the same lifecycle
  3. Ordered in the same homogeneous TaskRole by TaskIndex
  4. With consistent identity {FrameworkName}-{TaskRoleName}-{TaskIndex} as PodName
  5. With fine grained ExecutionType to Start/Stop the whole Framework
  6. With fine grained RetryPolicy for each Task and the whole Framework
  7. With fine grained FrameworkAttemptCompletionPolicy for each TaskRole
  8. With PodGracefulDeletionTimeoutSec for each Task to tune Consistency vs Availability
  9. With fine grained Status for each TaskAttempt/Task, each TaskRole and the whole FrameworkAttempt/Framework

Controller Feature

  1. Highly generalized as it is built for all kinds of applications
  2. Light-weight as it is only responsible for Pod orchestration
  3. Well-defined Framework Consistency vs Availability, State Machine and Failure Model
  4. Tolerate Pod/ConfigMap unexpected deletion, Node/Network/FrameworkController/Kubernetes failure
  5. Support to specify how to classify and summarize Pod failures
  6. Support to ScaleUp/ScaleDown Framework with Strong Safety Guarantee
  7. Support to expose Framework and Pod history snapshots to external systems
  8. Easy to leverage FrameworkBarrier to achieve light-weight Gang Execution and Service Discovery
  9. Easy to leverage HiveDScheduler to achieve GPU Topology-Aware, Multi-Tenant, Priority and Gang Scheduling
  10. Compatible with other Kubernetes features, such as Kubernetes Service, Gpu Scheduling, Volume, Logging
  11. Idiomatic with Kubernetes official controllers, such as Pod Spec
  12. Aligned with Kubernetes Controller Design Guidelines and API Conventions


  1. A Kubernetes cluster, v1.16.15 or above, on-cloud or on-premise.

Quick Start

  1. Run Controller
  2. Submit Framework


  1. User Manual
  2. Known Issue and Upcoming Feature
  3. FAQ
  4. Release Note

Official Image

Related Project

Third Party Controller Wrapper

A specialized wrapper can be built on top of FrameworkController to optimize for a specific kind of application:

Recommended Kubernetes Scheduler

FrameworkController can directly leverage many Kubernetes Schedulers and among them we recommend these best fits:

Similar Offering On Other Cluster Manager


This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.