From 9b0f4735ba6ec8305694c94be4f931d6866d2719 Mon Sep 17 00:00:00 2001 From: Randy George Date: Fri, 18 Oct 2024 09:38:51 -0500 Subject: [PATCH 1/3] Create resource-Identification-history.md --- .../resource-Identification-history.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 src/content/docs/start-here/resource-Identification-history.md diff --git a/src/content/docs/start-here/resource-Identification-history.md b/src/content/docs/start-here/resource-Identification-history.md new file mode 100644 index 0000000..7aa3e5f --- /dev/null +++ b/src/content/docs/start-here/resource-Identification-history.md @@ -0,0 +1,41 @@ +The following is a list of scenarios that impact how resource history is maintained. + +### Resource Identification +The identification of a resource, i.e. _local_resource_id_, can not be assumed to be globally unique. However, this id can be assumed to be unique within the scope of the reporter for that resource type. In other words, a reporter can not have a host with the same id as another host, a cluster with the same id as another cluster, etc. + +Thus, in order to identify a resource, when a reporter does a POST, the POST must include the following: + +- resource_type +- local_resource_id +- reporter_type + +This says that the above tuple provides a unique identification of a resource. This is not quite the case. + +When we say that a resource id is unique within the scope of the reporter, we really mean an instance of the reporter. If a reporter can have more than one instance, e.g. one can have multiple ACM hub clusters, then we must be able to distinguish between instances to ensure uniqueness. Thus, by capturing the reporter_instance_id, we can ensure uniqueness with the tuple: + +- reporter_type +- reporter_instance_id +- resource_type +- local_resource_id + +### Resource Identification and lifecycle +The above ensures that the identification of a resource is unique within the lifecycle of that managed resource. With respect to maintaining history of a resource, there are a couple of nuances that need to be considered: + +1. Once a reporter issues a delete of a resource, the reporter might reuse ids. For example, a user creates a cluster Foo. After some time, they delete this cluster. At some future time, they decide to create a new cluster named Foo. Foo is still unique within the context of the reporter. However, Foo is not the same resource as the previous Foo. + + Thus, inventory can not just blindly link any resource with the same ..reporter_type/reporter_instance_id/resource_type/local_resource_id. Similarly to how deduplication works across reporters, a resource_type-specific correlator must be used to see if this is the same resource. In the example of a cluster, there is an external_cluster_id that is used for deduplication. In the example above, the first Foo and the second Foo would have different external_cluster_ids; thus, they are different clusters. + +2. A delete, i.e. rest operation, tells inventory to delete this resource as it no longer exists within the management domain. However, there are 2 different types of delete. Using a cluster example: + 1. One might issue a “destroy” which actually deletes the managed cluster. In this case, a delete would be issued to inventory. Any future creating of a cluster which could lead to conflict would be the same as #1 above. + + 2. One might issue a “detach” which removes the cluster from management but does not impact the actual cluster. Given that this cluster still exists, one could decide to bring this cluster back under management, i.e. import the cluster. In this case, the cluster could have a different local_resource_id, but the cluster is actually the same resource, i.e. it has the same external_resource_id. This case is very similar to having 2 different reporters reporting on the same resource where deduplication resolves that these are the same resource and we would link them in history. + +Given the above, without a correlator defined in the resource model, a specific resource_type can not have: + +- more than one reporter type +- more than one reporter instance +- a resource span across a delete in history, even if the delete is a “detach” + +Currently, the only resource model that has a correlator is a k8s-cluster. + + From be0fc502d305141f9c01eb298796607229a56dbf Mon Sep 17 00:00:00 2001 From: Randy George Date: Fri, 18 Oct 2024 09:44:00 -0500 Subject: [PATCH 2/3] Update resource-Identification-history.md --- .../docs/start-here/resource-Identification-history.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/start-here/resource-Identification-history.md b/src/content/docs/start-here/resource-Identification-history.md index 7aa3e5f..c1ffa8e 100644 --- a/src/content/docs/start-here/resource-Identification-history.md +++ b/src/content/docs/start-here/resource-Identification-history.md @@ -23,7 +23,13 @@ The above ensures that the identification of a resource is unique within the lif 1. Once a reporter issues a delete of a resource, the reporter might reuse ids. For example, a user creates a cluster Foo. After some time, they delete this cluster. At some future time, they decide to create a new cluster named Foo. Foo is still unique within the context of the reporter. However, Foo is not the same resource as the previous Foo. - Thus, inventory can not just blindly link any resource with the same ..reporter_type/reporter_instance_id/resource_type/local_resource_id. Similarly to how deduplication works across reporters, a resource_type-specific correlator must be used to see if this is the same resource. In the example of a cluster, there is an external_cluster_id that is used for deduplication. In the example above, the first Foo and the second Foo would have different external_cluster_ids; thus, they are different clusters. + Thus, inventory can not just blindly link any resource with the same tuple: + - reporter_type + - reporter_instance_id + - resource_type + - local_resource_id. + + Similarly to how deduplication works across reporters, a resource_type-specific correlator must be used to see if this is the same resource. In the example of a cluster, there is an _external_cluster_id_ that is used for deduplication. In the example above, the first Foo and the second Foo would have different _external_cluster_ids_; thus, they are different clusters. 2. A delete, i.e. rest operation, tells inventory to delete this resource as it no longer exists within the management domain. However, there are 2 different types of delete. Using a cluster example: 1. One might issue a “destroy” which actually deletes the managed cluster. In this case, a delete would be issued to inventory. Any future creating of a cluster which could lead to conflict would be the same as #1 above. From 3fe1cf514e986e9b254652fd8f7b5ba31ef2f4ba Mon Sep 17 00:00:00 2001 From: Randy George Date: Fri, 18 Oct 2024 09:49:11 -0500 Subject: [PATCH 3/3] Update resource-Identification-history.md --- .../docs/start-here/resource-Identification-history.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/start-here/resource-Identification-history.md b/src/content/docs/start-here/resource-Identification-history.md index c1ffa8e..ebd9aad 100644 --- a/src/content/docs/start-here/resource-Identification-history.md +++ b/src/content/docs/start-here/resource-Identification-history.md @@ -21,7 +21,7 @@ When we say that a resource id is unique within the scope of the reporter, we re ### Resource Identification and lifecycle The above ensures that the identification of a resource is unique within the lifecycle of that managed resource. With respect to maintaining history of a resource, there are a couple of nuances that need to be considered: -1. Once a reporter issues a delete of a resource, the reporter might reuse ids. For example, a user creates a cluster Foo. After some time, they delete this cluster. At some future time, they decide to create a new cluster named Foo. Foo is still unique within the context of the reporter. However, Foo is not the same resource as the previous Foo. +1. Once a reporter issues a delete of a resource, the reporter might reuse ids. For example, a user creates a cluster _Foo_. After some time, they delete this cluster. At some future time, they decide to create a new cluster named _Foo_. _Foo_ is still unique within the context of the reporter. However, _Foo_ is not the same resource as the previous _Foo_. Thus, inventory can not just blindly link any resource with the same tuple: - reporter_type @@ -29,10 +29,10 @@ The above ensures that the identification of a resource is unique within the lif - resource_type - local_resource_id. - Similarly to how deduplication works across reporters, a resource_type-specific correlator must be used to see if this is the same resource. In the example of a cluster, there is an _external_cluster_id_ that is used for deduplication. In the example above, the first Foo and the second Foo would have different _external_cluster_ids_; thus, they are different clusters. + Similarly to how deduplication works across reporters, a resource_type-specific correlator must be used to see if this is the same resource. In the example of a cluster, there is an _external_cluster_id_ that is used for deduplication. In the example above, the first _Foo_ and the second _Foo_ would have different _external_cluster_ids_; thus, they are different clusters. 2. A delete, i.e. rest operation, tells inventory to delete this resource as it no longer exists within the management domain. However, there are 2 different types of delete. Using a cluster example: - 1. One might issue a “destroy” which actually deletes the managed cluster. In this case, a delete would be issued to inventory. Any future creating of a cluster which could lead to conflict would be the same as #1 above. + 1. One might issue a “destroy” which actually deletes the managed cluster. In this case, a reporter would call the delete method. Any future creating of a cluster which could lead to conflict would be the same as #1 above. 2. One might issue a “detach” which removes the cluster from management but does not impact the actual cluster. Given that this cluster still exists, one could decide to bring this cluster back under management, i.e. import the cluster. In this case, the cluster could have a different local_resource_id, but the cluster is actually the same resource, i.e. it has the same external_resource_id. This case is very similar to having 2 different reporters reporting on the same resource where deduplication resolves that these are the same resource and we would link them in history.