sigs.k8s.io/cluster-api@v1.7.1/docs/proposals/20181121-machine-api.md (about)

     1  Minimalistic Machines API
     2  =========================
     3  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
     4  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
     5  
     6  - [Capabilities](#capabilities)
     7  - [Proposal](#proposal)
     8  - [In-place vs. Replace](#in-place-vs-replace)
     9  - [Omitted Capabilities](#omitted-capabilities)
    10    - [A provider-agnostic mechanism to request new nodes](#a-provider-agnostic-mechanism-to-request-new-nodes)
    11    - [Dynamic API endpoint](#dynamic-api-endpoint)
    12  - [Conditions](#conditions)
    13  - [Types](#types)
    14  
    15  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    16  
    17  This proposal is for a minimalistic start to a new Machines API, as part of the
    18  overall Cluster API project. It is intended to live outside of core Kubernetes
    19  and add optional machine management features to Kubernetes clusters.
    20  
    21  ## Capabilities
    22  
    23  This API strives to be able to add these capabilities:
    24  
    25  1. A new Node can be created in a declarative way, including Kubernetes version.
    26     It should also be able to specify provider-specific information such as OS image,
    27     instance type, disk configuration, etc., though this will not be portable.
    28  
    29  1. A specific Node can be deleted, freeing external resources associated with
    30     it.
    31  
    32  1. A specific Node can have its kubelet version upgraded or downgraded in a
    33     declarative way\*.
    34  
    35  1. A specific Node can have its OS image upgraded or downgraded in a declarative
    36     way\*.
    37  
    38  \*  It is an implementation detail of the provider if these operations are
    39  performed in-place or via Node replacement.
    40  
    41  ## Proposal
    42  
    43  This proposal introduces a new API type: Machine. See the full definition in
    44  [machine_types.go](https://github.com/kubernetes-sigs/cluster-api/blob/release-0.4/api/v1alpha4/machine_types.go).
    45  
    46  A "Machine" is the declarative spec for a Node, as represented in Kubernetes
    47  core. If a new Machine object is created, a provider-specific controller will
    48  handle provisioning and installing a new host to register as a new Node matching
    49  the Machine spec. If the Machine's spec is updated, a provider-specific
    50  controller is responsible for updating the Node in-place or replacing the host
    51  with a new one matching the updated spec. If a Machine object is deleted, the
    52  corresponding Node should have its external resources released by the
    53  provider-specific controller, and should be deleted as well.
    54  
    55  Fields like the kubelet version are modeled as fields on the Machine's spec.
    56  Any other information that is provider-specific, though, is part of an opaque
    57  ProviderSpec string that is not portable between different providers.
    58  
    59  The ProviderSpec is recommended to be a serialized API object in a format
    60  owned by that provider, akin to the [Component Config](https://goo.gl/opSc2o)
    61  pattern. This will allow the configuration to be strongly typed, versioned, and
    62  have as much nested depth as appropriate. These provider-specific API
    63  definitions are meant to live outside of the Machines API, which will allow them
    64  to evolve independently of it. Attributes like instance type, which network to
    65  use, and the OS image all belong in the ProviderSpec.
    66  
    67  ## In-place vs. Replace
    68  
    69  One simplification that might be controversial in this proposal is the lack of
    70  API control over "in-place" versus "replace" reconciliation strategies. For
    71  instance, if a Machine's spec is updated with a different version of kubelet
    72  than is actually running, it is up to the provider-specific controller whether
    73  the request would best be fulfilled by performing an in-place upgrade on the
    74  Node, or by deleting the Node and creating a new one in its place (or reporting
    75  an error if this particular update is not supported). One can force a Node
    76  replacement by deleting and recreating the Machine object rather than updating
    77  it, but no similar mechanism exists to force an in-place change.
    78  
    79  Another approach considered was that modifying an existing Machine should only
    80  ever attempt an in-place modification to the Node, and Node replacement should
    81  only occur by deleting and creating a new Machine. In that case, a provider
    82  would set an error field in the status if it wasn't able to fulfill the
    83  requested in-place change (such as changing the OS image or instance type in a
    84  cloud provider).
    85  
    86  The reason this approach wasn't used was because most cluster upgrade tools
    87  built on top of the Machines API would follow the same pattern:
    88  
    89      for machine in machines:
    90          attempt to upgrade machine in-place
    91          if error:
    92              create new machine
    93              delete old machine
    94  
    95  Since updating a Node in-place is likely going to be faster than completely
    96  replacing it, most tools would opt to use this pattern to attempt an in-place
    97  modification first, before falling back to a full replacement.
    98  
    99  It seems like a much more powerful concept to allow every tool to instead say:
   100  
   101      for machine in machines:
   102          update machine
   103  
   104  and allow the provider to decide if it is capable of performing an in-place
   105  update, or if a full Node replacement is necessary.
   106  
   107  ## Omitted Capabilities
   108  
   109  ### A provider-agnostic mechanism to request new nodes
   110  
   111  In this proposal, only certain attributes of Machines are provider-agnostic and
   112  can be operated on in a generic way. In other iterations of similar proposals,
   113  much care had been taken to allow the creation of truly provider-agnostic
   114  Machines that could be mapped to provider-specific attributes in order to better
   115  support usecases around automated Machine scaling. This introduced a lot of
   116  upfront complexity in the API proposals.
   117  
   118  This proposal starts much more minimalistic, but doesn't preclude the option of
   119  extending the API to support these advanced concepts in the future (see
   120  https://github.com/kubernetes-sigs/cluster-api/issues/22).
   121  
   122  ### Dynamic API endpoint
   123  
   124  This proposal lacks the ability to declaratively update the kube-apiserver
   125  endpoint for the kubelet to register with. This feature could be added later,
   126  but doesn't seem to have demand now. Rather than modeling the kube-apiserver
   127  endpoint in the Machine object, it is expected that the cluster installation
   128  tool resolves the correct endpoint to use, starts a provider-specific Machines
   129  controller configured with this endpoint, and that the controller injects the
   130  endpoint into any hosts it provisions.
   131  
   132  ## Conditions
   133  
   134  Brian Grant (@bgrant0607) and Eric Tune (@erictune) have indicated that the API pattern of having
   135  "Conditions" lists in object statuses is soon to be deprecated. These have
   136  generally been used as a timeline of state transitions for the object's
   137  reconciliation, and difficult to consume for clients that just want a meaningful
   138  representation of the object's current state. There are no existing examples of
   139  the new pattern to follow instead, just the guidance that we should use
   140  top-level fields in the status to represent meaningful information. We can
   141  revisit the specifics when new patterns start to emerge in core.
   142  
   143  ## Types
   144  
   145  Please see the full types [here](https://github.com/kubernetes-sigs/cluster-api/blob/release-0.4/api/v1alpha4/machine_types.go).