Skip to content

Commit

Permalink
Merge pull request #107 from josejulio/cleanup-docs
Browse files Browse the repository at this point in the history
Cleaning  up API documentation format
  • Loading branch information
jmelis authored Sep 10, 2024
2 parents 525f9ec + a0b6393 commit da4f435
Showing 1 changed file with 67 additions and 52 deletions.
119 changes: 67 additions & 52 deletions api/kessel/inventory/v1beta1/documentation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,53 +8,57 @@ This document does not supersede any information in the API specification. This
## Reporting a New Resource to Asset Inventory

A management service creates, modifies or deletes a managed resource in its local inventory. To aid in the integration of the Red Hat Hybrid Cloud Management solution, they will report all of these operations to the management fabric via the Asset Inventory APIs. With the Asset Inventory APIs, these services are referenced as Reporters.
<br><br>When a new resource is created in the Reporter’s private inventory, the Reporter will issue a POST to the managemnt fabric. The endpoint is structured as follows:
…/api/inventory/”_api-version_”/resources/”_resource-type_”.
<br><br>When a new resource is created in the Reporter’s private inventory, the Reporter will issue a POST to the managemnt fabric. The endpoint is structured as follows: `/api/inventory/{api-version}/resources/{resource-type}`.

An example would be: /api/inventory/v1beta1/resources/k8s-clusters.
An example would be: `/api/inventory/v1beta1/resources/k8s-clusters`.


### The Request Body
The request body is the resource type. This top level json object is comprised of 3 objects: metadata, reporter_data and resource_data, i.e.
<br> &nbsp;&nbsp; {
<br> &nbsp;&nbsp;&nbsp;&nbsp; resource\_type : {
<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “metdata”: { },
<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “reporter\_data”: { },
<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “resource\_data”: { }
<br> &nbsp;&nbsp;&nbsp;&nbsp; }
<br>}
The request body is the resource type. This top level json object is comprised of 3 objects: metadata, reporter_data and resource_data, i.e.
```json
{
"resource_type":{
"metadata":{},
"reporter_data":{},
"resource_data":{}
}
}
```

Required data is marked with an asterisk (*).

#### Metadata
This object represents the attributes that are common for all resources, no matter the type. Most of the metadata is generated by the Asset Inventory service, i.e.
- **_id_** - this is the GUID for the resource instance
- **_resource\_type_** - this is derived from the top level object of the request body.
- **_first_reported_**
- **_last\_reported_**
- **_first\_reported\_by_**
- **_last\_reported\_by_**
- ___id___ - this is the GUID for the resource instance
- ___resource_type___ - this is derived from the top level object of the request body.
- ___first_reported___
- ___last_reported___
- ___first_reported_by___
- ___last_reported_by___

The only metadata that a Reporter can provide is:
- **_workspace_**
- **_labels_**
- ___workspace*___
- ___labels___
#### Reporter_data

This object represents data that is specific to the reporter who called the Asset Inventory API in order to report on this resource. The information that a reporter provides for this object is:
- **_reporter\_type_**
- **_reporter\_version_**
- **_local\_resource\_id_**
- **_console\_href_**
- **_api\_href_**
- ___reporter_type*___
- ___reporter_version___
- ___local_resource_id*___
- ___console_href___
- ___api_href___

The _reporter\_type_ and _reporter\_version_, along with the system generated _reporter\_instance\_id_, help to identify the reporter.
The _reporter_type_ and _reporter_version_, along with the system generated _reporter_instance_id_, help to identify the reporter.

The _local\_resource\_id_ is the identification of the resource within the Reporter’s domain.
The _local_resource_id_ is the identification of the resource within the Reporter’s domain.

The two hrefs are used if a consumer of an event (or query) from Asset Inventory and they wanted to consume additional domain-specific information about the resource. For example, ACM reports on a cluster. One could use an href to query into ACM to find out some health information of that cluster.
<br><br>NOTE: These hrefs only provide how to access this information. One still has to have the appropriate credentials of the Reporter in order to access the data referenced by these URLs.
<br><br>
Similar to the metadata, some of this information is created by the Asset Inventory service, i.e.
- **_reporter\_instance\_id_** - created from attributes in the authentication token
- **_first\_reported_**
- **_last\_reported_**
- ___reporter_instance_id___ - created from attributes in the authentication token
- ___first_reported___
- ___last_reported___


##### Multiple Reporters
Expand All @@ -65,36 +69,36 @@ Internally, the reporter_data is an array, keeping track of this information per


#### Resource_data
This object represents data that is specific to the *resource\_type* for this resource instance. For example, if the resource was of type k8sCluster, this would have attributes that are specific to a kube cluster. If this was a RHEL host, this would have attributes that were specific to a RHEL host.
This object represents data that is specific to the *resource_type* for this resource instance. For example, if the resource was of type k8sCluster, this would have attributes that are specific to a kube cluster. If this was a RHEL host, this would have attributes that were specific to a RHEL host.
<br><br>
This information is passed in from the Reporter. There are no attributes in which the Asset Inventory Service creates.

### Resource Deduplication

Given that a resource can be reported by more than one Reporter, Asset Inventory needs to determine if the resource from one Reporter (data source) is the same as a resource from another Reporter (data source). Thus, there has to be defined comparison points in which the correlation algorithm leverages for this determination. The more comparison points, the better the deduplication results will be.

The comparison points are unique to each resource type. For example, for k8sClusters, the *kube\_vendor* and the *external\_cluster\_id* will be used for correlation. A Reporter might report on a cluster with *kube\_vendor* = *OpenShift* and *external\_cluster\_id* = 44028166-3196-4d96-8e60-b07249eb95d1. Given that the *external\_cluster\_id* is the openshift guid, any other Reporter that reports on this same OpenShift cluster would correlate with this guid.
The comparison points are unique to each resource type. For example, for k8sClusters, the *kube_vendor* and the *external_cluster_id* will be used for correlation. A Reporter might report on a cluster with *kube_vendor* = *OpenShift* and *external_cluster_id* = 44028166-3196-4d96-8e60-b07249eb95d1. Given that the *external_cluster_id* is the openshift guid, any other Reporter that reports on this same OpenShift cluster would correlate with this guid.

From a Reporter’s perspective, the result of a valid POST will be a return code of 200, even if the resource was already reported from another Reporter. If there are more than one Reporter of the resource, an array of Reporters will be kept for this resource. Thus, on a query (GET), one can determine who all reported on the same resource.

Any subsequent POSTs or PUTs for a resource will update the attributes for that resource. In other words, the values for the attributes of the latest update will supersede previous values. For example, if _Reporter-A_ POSTed a policy with an attribute of _disabled=true_ and some time later _Reporter-B_ POSTed the same policy but with the attribute of _disabled=false_, the current attribute for the resource in Asset Inventory would be _disabled=false_.
Any subsequent POSTs or PUTs for a resource will update the attributes for that resource. In other words, the values for the attributes of the latest update will supersede previous values. For example, if _Reporter-A_ POSTed a policy with an attribute of _disabled=true_ and some time later _Reporter-B_ POSTed the same policy but with the attribute of _disabled=false_, the current attribute for the resource in Asset Inventory would be _disabled=false_.

If the Reporter issued a POST for a resource in which it was the Reporter that created the resource prior, they would get a 405, i.e. Method Not Allowed. They would be expected to be issuing a PUT to update the resource in which they originally reported.


## Resource Lifecycle
The above talked about reporting data about a new resource to the Asset Inventory service. These resources can change and the metadata which is stored in Asset Inventory needs to reflect the current state of the resources. This can be anything from a label change, a workspace change or a resource-specific attribute change, e.g. _cluster\_status_.
The above talked about reporting data about a new resource to the Asset Inventory service. These resources can change and the metadata which is stored in Asset Inventory needs to reflect the current state of the resources. This can be anything from a label change, a workspace change or a resource-specific attribute change, e.g. _cluster_status_.
<br><br>
Reporters will send a PUT request to the Asset Inventory service, pointing to the URI of the specific resource to update with the data in the request body. When the API server receives the PUT request, it checks if the resource already exists. If the resource exists, then the API updates the resource with the data enclosed in the PUT request. If the resource doesn’t exist, then the API creates that resource with the data supplied.
<br><br>
Similarly, when a Management Domain service deletes the resource, or takes it out of management, the Reporting for that Management Domain will send a DELETE request to the Asset Inventory service pointing to the URI of the specific resource to delete.
### Resource Identification
Typically in a RESTful api, the client will issue a POST and the service will return a REST ID for the newly created resource. This ID is then used for subsequent API calls, e.g. PUTs, DELETEs and GETs to reference this resource. This approach requires a Reporter to persist the ID; thus, increasing the cost of adoption/exploitation. Thus, as an alternative, a Reporter can use their existing knowledge in order to reference the resource. In order to get to a unique identifier which is an alias of the ID, we use the following:
- A Reporter has an identifier that is unique within their realm.This identifier is the _local\_reource\_id_.
- If you scope this id with the reporter_type, i.e. *reporter\_type:local\_resource\_id*, you avoid collisions with other reporter types.
- However, there can be multiple instances of the same reporter type which could introduce collisions on this identifier. By introducing a unique identifier for the Reporter instance, i.e. the *reporter\_instance\_id*, you now have a unique identifier, i.e. *reporter\_type:reporter\_instance\_id:local\_resource_id*.
- A Reporter has an identifier that is unique within their realm.This identifier is the _local_reource_id_.
- If you scope this id with the reporter_type, i.e. *reporter_type:local_resource_id*, you avoid collisions with other reporter types.
- However, there can be multiple instances of the same reporter type which could introduce collisions on this identifier. By introducing a unique identifier for the Reporter instance, i.e. the *reporter_instance_id*, you now have a unique identifier, i.e. *reporter_type:reporter_instance_id:local_resource_id*.

Given the above, a reporter can use *reporter\_type:local\_resource_id* for PUTs and DELETEs. The Asset Inventory service will include the *reporter\_instance\_id* in order to map to the service’s unique ID. The *reporter\_instance\_id* will be loaded from the identity of the caller, it won’t be required as a separate input.
Given the above, a reporter can use *reporter_type:local_resource_id* for PUTs and DELETEs. The Asset Inventory service will include the *reporter_instance_id* in order to map to the service’s unique ID. The *reporter_instance_id* will be loaded from the identity of the caller, it won’t be required as a separate input.



Expand All @@ -105,30 +109,41 @@ For example, there is a _k8s-policy_ (foo) in Asset Inventory with its set of at

When a new resource relationship is created in the Reporter’s private inventory, the Reporter will issue a POST to the management fabric. The endpoint are structured as follows:

/api/inventory/_api-version_/resource-relationships/_resource-relationship-type_”, where _resource-relationship-type_ is defined as “subject.relationship.object”.
`/api/inventory/{api-version}/resource-relationships/{relationship-type}` where _relationship-type_ is defined as “subject.relationship.object”.

An example would be: /api/inventory/v1beta1/resource-relationships/k8s-policy.is-propagated.to-k8s-cluster
An example would be: `/api/inventory/v1beta1/resource-relationships/k8s-policy.is-propagated.to-k8s-cluster`

The subject and object resources must both exist in Asset Inventory for the POST/PUT to be valid.

### The Request Body
TThe JSON for the resource-relationship is similar to resources, i.e.
<br> &nbsp;&nbsp; {
<br> &nbsp;&nbsp;&nbsp;&nbsp; resource\_relationship\_type : {
<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “metdata”: { },
<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “reporter\_data”: { },
<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “relationship\_data”: { }
<br> &nbsp;&nbsp;&nbsp;&nbsp; }
<br>}
The JSON for the resource-relationship is similar to resources, i.e.
```json
{
"resource_relationship_type" : {
"metadata": { },
"reporter_data": { },
"relationship_data": { }
}
}

```

#### Metadata
The metadata differs in that all of the metadata is generated by the Asset Inventory service.
The metadata differs in that all of the metadata is generated by the Asset Inventory service.

#### Reporter_data
The report_data differs in that there are no hrefs provided for the relationship. In addition, the Reporter must pass a _local\_resorce\_id_ for both the subject and the object resources in the relationship.
The report_data differs in that there are no hrefs provided for the relationship. In addition, the Reporter must pass a _local_resource_id_ for both the subject and the object resources in the relationship.

- ___reporter_type___
- ___reporter_version___
- ___subject_local_resource_id*___
- ___object_local_resource_id*___

##### Multiple Reporters
The semantics of multiple reporters is the same as with resources.

#### Relationship_data
Similar to resources, the attributes defined by this object vary by the _resource\_relationship\_type_.
### Relationship Lifecycle
The lifecycle for a resource_relationship is the same as with a resource itself. The main difference is that when one of the resources defined in a relationship, i.e. subject_resource or object_resource, is deleted, all relationships for that resource will be deleted as well.
Similar to resources, the attributes defined by this object vary by the _resource_relationship_type_.

### Relationship Lifecycle
The lifecycle for a resource_relationship is the same as with a resource itself. The main difference is that when one of the resources defined in a relationship, i.e. subject_resource or object_resource, is deleted, all relationships for that resource will be deleted as well.

0 comments on commit da4f435

Please sign in to comment.