kubeflow
/
community
mirror of https://github.com/kubeflow/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
community/guidelines/application_requirements.md

7.8 KiB
Raw Permalink Blame History

Guidelines for Application Requirements

Authors: chasm@google.com, jlewi@google.com, kam.d.kasravi@intel.com

Objective

The purpose of this doc is to define requirements and recommendations aimed at graduating applications (e.g. controller and web apps) in Kubeflow to 1.0.

The main goals are to:

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

Scope

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

  1. Custom resources and controllers
  2. Web applications

This document is not intended to cover SDKs (e.g. fairing) or client side tools (like kfctl).

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 the application should be listed in one or more kustomization.yaml files
  • This facilitates mirroring the images to different docker registries
Upgradeability Required
  • Applications 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
Supports status subresource Required
  • Status subresource documented here
CRD schema validation Required
Training operators follow kubeflow/common conventions Required

Logging and monitoring

Description Category Explanation
Liveness/Readiness signals Required
  • The application should expose liveness and/or readiness signals as appropriate for the application
Prometheus metrics Required
  • Applications should export suitable application level metrics (e.g. number of jobs) using prometheus
Json logging Recommended
  • Applications 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, e.g. you can follow these instructions to get licenses of dependencies for Golang images

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