Change AnyState to ControllerHistory

Author: Kenneth Owens

contributors/design-proposals/controller_history.md

@@ -118,17 +118,17 @@ Masters). This State Abstraction is a mutable, durable dictionary where keys
 and values are opaque strings. As controllers only need the capability to 
 persist an immutable point in time snapshot of target Object states to 
 implement a revision history, we propose to use an immutable durable dictionary, 
-and we introduce the AnyState object for this purpose.
+and we introduce the ControllerHistory object for this purpose.
 
 ``` golang
-// AnyState implements an immutable dictionary of state data to allow for a 
+// ControllerHistory implements an immutable dictionary of state data to allow for a 
 // point in time snapshot. Clients are responsible for serializing 
 // and deserializing the objects that contain their internal state and mapping 
 // them to a set of keys. 
-// Once an AnyState has been successfully created, it can not be updated. The 
+// Once an ControllerHistory has been successfully created, it can not be updated. The 
 // API Server will fail validation of all update requests that attempt to mutate 
-// the Data field. AnyStates may, however, be deleted.
-type AnyState struct {
+// the Data field. ControllerHistorys may, however, be deleted.
+type ControllerHistory struct {
     metav1.TypeMeta
     // +optional
     metav1.ObjectMeta
@@ -143,13 +143,13 @@ type AnyState struct {
 ```
 
 ## API Server
-The API Server must support the creation and deletion of AnyState objects.
+The API Server must support the creation and deletion of ControllerHistory objects.
 As we have no mechanism for declarative immutability, the API server must fail 
-any update request that updates the `.Data` field of an AnyState Object.
+any update request that updates the `.Data` field of an ControllerHistory Object.
 
 ## Controllers 
 This section is presented as a generalization of how an arbitrary controller 
-can use AnyState to persist a history of revisions to its specification type 
+can use ControllerHistory to persist a history of revisions to its specification type 
 Objects. The technique is applicable, without loss of generality, to the 
 existing Kuberentes controllers that have Pod as a generated type.
 
@@ -183,28 +183,28 @@ Object, a controller will do the following.
 
 1. The controller will serialize all the fields of the Object's target object 
 state using JSON encoding.
-1. The controller will populate the `.Data` of an AnyState object by 
+1. The controller will populate the `.Data` of an ControllerHistory object by 
 associating the serialized fields with keys that correspond to the fields' 
 names. 
    - e.g `PodTemplateSpecs` should be stored at the `"Template"` key.
 1. The controller will store the specification type Objects `.Generation` at the 
 `"ControllerGeneration"` key.
-   - This value provides providence for the created AnyState.
+   - This value provides providence for the created ControllerHistory.
 1. The controller will store a unique, monotonically increasing 
 [revision number](#revision-number-selection) in the Revision field.
-1. The controller will compute the [hash](#hashing) of the AnyState's `.Data`.
-1. The controller will attach a label to the AnyState so that it is selectable 
+1. The controller will compute the [hash](#hashing) of the ControllerHistory's `.Data`.
+1. The controller will attach a label to the ControllerHistory so that it is selectable 
 with a low probability of overlap.
     - ControllerRefs will be used as the authoritative test for ownership.
     - The specification type Object's `.Selector` should be used where 
     applicable. 
     - Alternatively, a Kind unique label may be set to the `.Name` of the 
     specification type Object.
 1. The controller will add a ControllerRef indicating the specification type 
-Object as the owner of the AnyState in the AnyState's `.OwnerReferences`.
+Object as the owner of the ControllerHistory in the ControllerHistory's `.OwnerReferences`.
 1. The controller will use the hash from above, along with a user identifiable 
-prefix, to [generate a unique `.Name`](#unique-name-generation) for the AnyState.
-1. The controller will persist the AnyState via the API Server.
+prefix, to [generate a unique `.Name`](#unique-name-generation) for the ControllerHistory.
+1. The controller will persist the ControllerHistory via the API Server.
     - Note that, in practice, creation occurs concurrently with 
     [collision resolution](#collision-resolution).
 
@@ -227,13 +227,13 @@ specification type Object's revision history.
 To reconstruct the history of a specification type Object, a controller will do 
 the following. 
 
-1. Select all AnyState Objects labeled as described 
+1. Select all ControllerHistory Objects labeled as described 
 [above](#version-snapshot-creation).
-1. Filter any AnyStates that do not have a ControllerRef in their 
+1. Filter any ControllerHistories that do not have a ControllerRef in their 
 `.OwnerReferences` indicating ownership by the Object.
-1. Sort the AnyStates by the value associated with the 
+1. Sort the ControllerHistories by the value associated with the 
 `"Revision"` key.
-1. This produces a strictly ordered set of AnyStates that comprises the ordered 
+1. This produces a strictly ordered set of ControllerHistories that comprises the ordered 
 revision history of the specification type Object.
 
 ### History Maintenance
@@ -246,12 +246,12 @@ specification type Object it will do the following.
 1. The controller will 
 [reconstruct the Object's revision history](#history-reconstruction).
     - Note that the process of reconstructing the Object's history filters any
-    AnyStates not owned by the Object.
-1. The controller will filter any AnyStates that represent a live version.
-1. If the number of remaining AnyStates is greater than the configured 
+    ControllerHistories not owned by the Object.
+1. The controller will filter any ControllerHistories that represent a live version.
+1. If the number of remaining ControllerHistories is greater than the configured 
 `RevisionHistoryLimit`, the controller will delete them, in order with respect 
 to the value mapped to their `.Revisions`, until the number 
-of remaining AnyStates is equal to the `RevisionHistoryLimit`.
+of remaining ControllerHistories is equal to the `RevisionHistoryLimit`.
 
 This ensures that the number of recorded, non-live revisions is less than or 
 equal to the configured `RevisionHistoryLimit`.
@@ -264,26 +264,26 @@ target state update or rollback. We propose two methods that controllers may
 use to track live versions and their association with generated Objects.
 
 1. The most straightforward method is labeling. In this method the generated 
-Objects are labeled with the `.Name` of the AnyState object that corresponds to 
+Objects are labeled with the `.Name` of the ControllerHistory object that corresponds to 
 the version of the target Object state that was used to generate them. As we 
-have taken care to ensure the uniqueness of the `.Names` of the AnyStates, 
+have taken care to ensure the uniqueness of the `.Names` of the ControllerHistories, 
 this approach is reasonable.
     - A revision is considered to be live while any generated Object labeled 
      with its `.Name` is live.
     - This method has the benefit of providing visibility, via the label, to 
     users with respect to the historical providence of a generated Object.
     - The primary drawback is the lack of support for using garbage collection 
     to ensure that only non-live version snapshots are collected.
-1. Controllers may also use the `OwnerReferences` field of the AnyState to 
+1. Controllers may also use the `OwnerReferences` field of the ControllerHistory to 
 record all Objects that are generated from target Object state version 
-represented by the AnyState as its owners.
+represented by the ControllerHistory as its owners.
    - A revision is considered to be live while any generated Object that owns 
    it is live.
    - This method allows for the implementation of generic garbage collection.
    - The primary drawback with this method is that the book keeping is complex, 
    and deciding if a generated Object corresponds to a particular revision 
    will require testing each Object for membership in the `OwnerReferences` 
-   of all AnyStates.
+   of all ControllerHistories.
 
 At the cost of the complexity of implementing both labeling and ownership, 
 controllers may use a combination of both approaches to mitigate the 
@@ -306,19 +306,19 @@ Since we [track the version of](#version-tracking) of generated Objects, this
 reduces to deciding if the version of the target Object state associated with 
 the generated Object is equivalent to the current target Object state.
 Even though  [hashing](#hashing) is used to generate the `.Name` of the 
-AnyStates used to encapsulate versions of the target Object state, as we do 
+ControllerHistories used to encapsulate versions of the target Object state, as we do 
 not require cryptographically strong collision resistance, and given we use a 
 [collision resolution](#collision-resolution) technique, we can't use the 
-[generated names](#unique-name-generation) of AnyStates to decide equality.
+[generated names](#unique-name-generation) of ControllerHistories to decide equality.
 
-We propose that two AnyStates can be considered equal if their `.Data` is 
+We propose that two ControllerHistories can be considered equal if their `.Data` is 
 equivalent, but that it is not sufficient to compare the serialized 
 representation of the their `.Data`. Consider that the addition of new fields 
 to the Objects that represent the target Object state may cause the serialized 
 representation of those Objects to be unequal even when they are semantically 
 equivalent.
 
-The controller should deserialize the values of the AnyStates representing their 
+The controller should deserialize the values of the ControllerHistories representing their 
 target Object state and perform a deep, semantic equality test. Here all 
 differences that do not constitute a mutation to the target Object state are 
 disregarded during the equivalence test.
@@ -373,11 +373,11 @@ contained at a particular revision.
 
 ## Tests
 
-1. Controllers can create an AnyState containing a revision of their target 
+1. Controllers can create an ControllerHistory containing a revision of their target 
 Object state.
 1. Controllers can reconstruct their revision history.
-1. Controllers can't update an AnyState's `.Data`.
-1. Controllers can delete an AnyState to maintain their history with respect to 
+1. Controllers can't update an ControllerHistory's `.Data`.
+1. Controllers can delete an ControllerHistory to maintain their history with respect to 
 the configured `RevisionHistoryLimit`.
 
 ## Appendix
@@ -408,7 +408,7 @@ will start with `n := 0` and compute `s' := H'(s,n)`, incrementing `n` when
 return `n,s'`.
 
 For our purposes, the implementation of the `exists` function will attempt to 
-create a `.Named` AnyState via the API Server using a 
+create a `.Named` ControllerHistory via the API Server using a 
 [unique name generation](#unique-name-generation). If creation fails, due to a 
 conflict, the method returns false.