kserve/docs/guidelines/kubeflow_kfserving_requirements.md

KFServing Requirements for Kubeflow 1.0

• KFServing Authors: [email protected]
• Kubeflow Authors: [email protected], [email protected], [email protected]

Objective

The purpose of this doc is to define requirements and recommendations aimed at graduating KFServing in Kubeflow to 1.0.

The main goals are to:

1. Establish criteria for graduating a KFServing to a supported Kubeflow application; i.e. 1.0
2. Set clear expectations for users regarding KFServing for Kubeflow 1.0

Scope

This document is intended to cover KFServing deployed in the Kubernetes cluster as part of Kubeflow and in particular:

Requirements

Configuration and deployment

Description	Category	Explanation
Kustomize package	Required	Kubeflow has standardized on Kustomize for configuring and deploying packages
Application CR	Required	Kubeflow has standardized on using the Kubernetes Application CR to provide consistent metadata and monitoring about applications Application CR should be an owner of all resources so that deleting the application CR uninstalls the application
app.kubernetes.io labels on every resource	Required	Every resource that is part of the application should include the labels recommended by Kubernetes, currently: app.kubernetes.io/name app.kubernetes.io/instance app.kubernetes.io/version app.kubernetes.io/component app.kubernetes.io/part-of app.kubernetes.io/managed-by See example here
Images listed in kustomization.yaml	Required	All docker images used by KFServing should be listed in one or more kustomization.yaml files This facilitates mirroring the images to different docker registries
Upgradeability	Required	KFServing must support upgrading between consecutive major and minor releases
Separate cluster scoped and namespace scoped resources	Recommended	To the extent possible cluster scoped resources should be installable separately (e.g. via a separate kustomize package) This allows cluster admins to install only the cluster scoped resources Clear documentation of cluster and namespace scoped behavior
Kustomize package should be deployable on its own	Recommended	To the extent possible users should be able to run kustomize build

Custom Resources

Description	Category	Explanation
Version stability	Required	No deprecative API changes
Multi Version Support	Required	Serves multiple versions of the CR per K8s docs
Supports status subresource	Required	Status subresource documented here
CRD schema validation	Required	Validation documented here Example: TFJob
Training operators follow kubeflow/common conventions	Required	Conventions defined here Examples: TFJob and PyTorchJob

Logging and monitoring

Description	Category	Explanation
Liveness/Readiness signals	Required	KFServing should expose liveness and/or readiness signals as appropriate for the application
Prometheus metrics	Required	KFServing should export suitable application level metrics (e.g. number of jobs) using prometheus
Json logging	Recommended	KFServing should optionally emit structured logs with suitable metadata to facilitate debugging e.g. CR controllers should annotate log messages with the name of the resource involved so it's easy to filter logs to all messages about a resource

Docker Images

Description	Category	Explanation
Vulnerability Scanning	Required	Docker images must be scanned for vulnerabilities and known vulnerabilities published
Licensing	Required	Docker images must provide a list of all OSS licenses used by the image and its transitive dependencies

CI/CD

Description	Category	Explanation
E2E tests	Required	E2E tests should be run on presubmit, postsubmit, and periodically Tests should cover deployment (kustomize packages) As well as the application functionality
Scalability / load testing	Required	Applications must have scalability and or load testing demonstrating that the application meets appropriate requirements for the application (e.g. # of concurrent CRs)
Continuous building of docker images	Recommended	On post-submit, docker images should be automatically built and pushed
Continuous updating of Kustomize manifests	Recommended	On post-submit, kustomize packages should be automatically updated to point to latest images

Docs

Description	Category	Explanation
API Reference docs	Required	Applications exposing APIs (e.g. CRs) need reference docs documenting the API
Application docs	Required	There must be docs on kubeflow.org explaining what an application is used for and how to use it

Ownership/Maintenance

Description	Category	Explanation
Healthy number of committers and commits	Required	Committers are listed as approvers in owners files Number to be determined by TOC based on size and scope of application
At least 2 different organizations are committers	Required

Adoption

Description	Category	Explanation
List of users running the application	Recommended	Suggest listing adopters willing to be identified publicly in ADOPTERS.md

Reference

• TFJob and PyTorch 1.0 exit criterion
• CNCF Graduation Criteria
• Core Infrastructure Best Practices
• Kubeflow v1.0 Docs and Processes
• Application CR Issue related to dependencies and health monitoring