sigs.k8s.io/cluster-api@v1.7.1/docs/scope-and-objectives.md (about)

     1  ---
     2  title: Cluster API Scope and Objectives
     3  authors:
     4    - "@vincepri"
     5    - "@ncdc"
     6    - "@detiber"
     7  reviewers:
     8    - "@timothysc"
     9    - "@justinsb"
    10  creation-date: 2019-04-08
    11  last-updated: 2019-04-08
    12  ---
    13  
    14  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
    15  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
    16  
    17  - [Cluster API Scope and Objectives](#cluster-api-scope-and-objectives)
    18    - [Table of Contents](#table-of-contents)
    19    - [Summary](#summary)
    20        - [What is Cluster API?](#what-is-cluster-api)
    21    - [Glossary](#glossary)
    22    - [Motivation](#motivation)
    23      - [Goals](#goals)
    24      - [Non-goals](#non-goals)
    25    - [Requirements](#requirements)
    26        - [Foundation](#foundation)
    27        - [User Experience](#user-experience)
    28        - [Organization](#organization)
    29        - [Validation](#validation)
    30        - [Extension](#extension)
    31  
    32  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    33  
    34  
    35  # Cluster API Scope and Objectives
    36  
    37  This is a living document that is refined over time. It serves as guard rails for what is in and out of scope for Cluster API. As new ideas or designs take shape over time, this document can and should be updated.
    38  
    39  ## Table of Contents
    40  
    41  * [Cluster API Scope and Objectives](#cluster-api-scope-and-objectives)
    42    * [Table of Contents](#table-of-contents)
    43    * [Summary](#summary)
    44      * [What is Cluster API?](#what-is-cluster-api)
    45    * [Glossary](#glossary)
    46    * [Motivation](#motivation)
    47      * [Goals](#goals)
    48      * [Non-goals](#non-goals)
    49    * [Requirements](#requirements)
    50      * [Foundation](#foundation)
    51      * [User Experience](#user-experience)
    52      * [Organization](#organization)
    53      * [Validation](#validation)
    54      * [Extension](#extension)
    55  
    56  ## Summary
    57  
    58  We are building a set of Kubernetes cluster management APIs to enable common cluster lifecycle operations (create, scale, upgrade, destroy) across infrastructure providers.
    59  
    60  #### What is Cluster API?
    61  
    62  - An API definition for managing Kubernetes Clusters declaratively.
    63  - A reference implementation for the core logic.
    64  - An API definition for cluster lifecycle management action extension points.
    65  
    66  ## Glossary
    67  
    68  [See ./book/GLOSSARY.md](./book/src/reference/glossary.md)
    69  
    70  - __Cluster API__: Unless otherwise specified, this refers to the project as a whole.
    71  - __Infrastructure provider__: Refers to the source of computational resources (e.g. machines, networking, etc.). Examples for cloud include AWS, Azure, Google, etc.; for bare metal include VMware, MAAS, etc. When there is more than one way to obtain resources from the same infrastructure provider (e.g. EC2 vs. EKS) each way is referred to as a variant.
    72  - __Provider implementation__: Existing Cluster API implementations consist of generic and infrastructure provider-specific logic. The infrastructure provider-specific logic is currently maintained in infrastructure provider repositories.
    73  - __Kubernetes-conformant__: A cluster that passes the Kubernetes conformance tests.
    74  - __Scaling__: Unless otherwise specified, this refers to horizontal scaling.
    75  - __Control plane__:
    76     - __Self-provisioned__: A Kubernetes control plane consisting of pods or machines wholly managed by a single Cluster API deployment.
    77     - __External__: A control plane offered and controlled by some system other than Cluster API (e.g., GKE, AKS, EKS, IKS).
    78  - __Core Add-ons__: Addons that are required to deploy a Kubernetes-conformant cluster: DNS, kube-proxy, CNI.
    79  - __Additional Add-ons__: Addons that are not required for a Kubernetes-conformant cluster (e.g. metrics/Heapster, Dashboard).
    80  - __Management cluster__: The cluster where one or more Cluster API providers run, and where resources (e.g. Machines) are stored.
    81  - __Workload cluster__: A cluster whose lifecycle is managed by the Management cluster.
    82  - __Operating system__: A generically understood combination of a kernel and system-level userspace interface, such as Linux or Windows, as opposed to a particular distribution.
    83  - __Manage a cluster__: Create, scale, upgrade, destroy.
    84  - __Default implementation__: A feature implementation offered as part of Cluster API project, infrastructure providers can swap it out for a different one.
    85  
    86  ## Motivation
    87  
    88  Kubernetes has a common set of APIs (see the [Kubernetes API Conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md)) to orchestrate containers regardless of deployment mechanism or cloud provider. Kubernetes also has APIs for handling some infrastructure, like load-balancers, ingress rules, or persistent volumes, but not for creating new machines.
    89  As a result, existing popular deployment mechanisms that manage Kubernetes clusters each have unique APIs and implementations for how to handle lifecycle events like cluster creation or deletion, control plane upgrades, and node upgrades.
    90  
    91  
    92  <!-- ANCHOR: Goals -->
    93  
    94  ### Goals
    95  
    96  - To manage the lifecycle (create, scale, upgrade, destroy) of Kubernetes-conformant clusters using a declarative API.
    97  - To work in different environments, both on-premises and in the cloud.
    98  - To define common operations, provide a default implementation, and provide the ability to swap out implementations for alternative ones.
    99  - To reuse and integrate existing ecosystem components rather than duplicating their functionality (e.g. node-problem-detector, cluster autoscaler, SIG-Multi-cluster).
   100  - To provide a transition path for Kubernetes lifecycle products to adopt Cluster API incrementally. Specifically, existing cluster lifecycle management tools should be able to adopt Cluster API in a staged manner, over the course of multiple releases, or even adopting a subset of Cluster API.
   101  
   102  ### Non-goals
   103  
   104  - To add these APIs to Kubernetes core (kubernetes/kubernetes).
   105     -  This API should live in a namespace outside the core and follow the best practices defined by api-reviewers, but is not subject to core-api constraints.
   106  - To manage the lifecycle of infrastructure unrelated to the running of Kubernetes-conformant clusters.
   107  - To force all Kubernetes lifecycle products (kOps, Kubespray, GKE, AKS, EKS, IKS etc.) to support or use these APIs.
   108  - To manage non-Cluster API provisioned Kubernetes-conformant clusters.
   109  - To manage a single cluster spanning multiple infrastructure providers.
   110  - To configure a machine at any time other than create or upgrade.
   111  - To duplicate functionality that exists or is coming to other tooling, e.g., updating kubelet configuration (c.f. dynamic kubelet configuration), or updating apiserver, controller-manager, scheduler configuration (c.f. component-config effort) after the cluster is deployed.
   112  
   113  <!-- ANCHOR_END: Goals -->
   114  
   115  ## Requirements
   116  
   117  #### Foundation
   118  
   119  - Cluster API MUST be able to be deployed and run on Kubernetes.
   120  
   121  - Cluster API MUST provide runtime and state isolation between providers within the same Management Cluster
   122  
   123  - Cluster API MUST support multiple infrastructure providers, including both on-prem and cloud providers.
   124  
   125  - Cluster API MUST be able to manage groups/sets of Kubernetes nodes that support scaling and orchestrated upgrades.
   126  
   127  - Cluster API, through a single installation, MUST be able to manage (create, scale, upgrade, destroy) clusters on multiple providers.
   128  
   129  - Cluster API SHOULD support all operating systems in scope for Kubernetes conformance.
   130  
   131  #### User Experience
   132  
   133  - Cluster API MUST be able to provide the versions of Kubernetes and related components of a Node that it manages.
   134  
   135  - Cluster API MUST be able to provide sufficient information for a consumer to directly use the API server of the provisioned workload cluster.
   136  
   137  #### Organization
   138  
   139  - Cluster API MUST NOT have code specific to a particular provider within the main repository, defined as sigs.k8s.io/cluster-api.
   140  
   141  #### Validation
   142  
   143  - Cluster API MUST enable infrastructure providers to validate configuration data.
   144  
   145  - Cluster API MUST test integrations that it claims will work.
   146  
   147  - Cluster API MUST deploy clusters that pass Kubernetes conformance tests.
   148  
   149  - Cluster API MUST document how to bootstrap itself and MAY provide tooling to do so.
   150  
   151  - Cluster API MUST document requirements for machine images and SHOULD reference default tools to prepare machine images.
   152  
   153  - Cluster API MUST have conformance tests to ensure that Cluster API and a given provider fulfill the expectations of users/automation.
   154  
   155  #### Extension
   156  
   157  - Cluster API SHOULD allow default implementations to be pluggable/extensible.
   158     - Cluster API SHOULD offer default implementations for generic operations.
   159     - Users MAY use different provider implementations for different sets of operations.
   160  
   161  - 🔌 Cluster API MUST be able to provide information as to which versions of Kubernetes it can install.
   162  
   163  - 🔌 Cluster API MUST be able to bootstrap a new Kubernetes control plane.
   164  
   165  - 🔌 Cluster API MUST provide a generic image lookup mechanism that can filter on characteristics such as kubernetes version, container runtime, kernel version, etc.
   166  
   167  - 🔌 Cluster API MUST be able to provide a consistent (across providers) way to prepare, configure, and join nodes to a cluster.
   168  
   169  - 🔌 Cluster API MUST be able to scale a self-provisioned control plane up from and down to one replica.
   170  
   171  - 🔌 Cluster API MUST provide high-level orchestration for Kubernetes upgrades (control plane and non-control plane).
   172  
   173  - 🔌 Cluster API MUST define and document configuration elements that it exclusively manages and take corrective actions if these elements are modified by external actors.
   174  
   175  - 🔌 Cluster API MUST provide the ability to receive the health status of a Kubernetes Node from an external source.
   176  
   177  - 🔌 Cluster API provider implementations SHOULD allow customization of machine, node, or operating system image.