[asset_manager] Add /related endpoint (#154541)

Exposes a `/related` endpoint that can be called to retrieve any
supported asset relationship (`ancestors|descendants|references`).

Note that this is a first draft to get a functioning endpoint available.
Further optimizations (performances, typing..) will be implemented as
follow ups or when we get feedback from actual use cases.

Follow ups:
- We're currently doing two sequential requests to retrieve the related
assets, one for the _directly_ referenced of the primary (in
`assets.children|parents..`) and another for _indirectly_ referenced
that lists the primary in `asset.children|parents...`. These two
predicates can be packed in a single query
- The size is difficult to enforce at the query level if a `type` filter
is provided. If we're looking at a `depth > 1` and we apply the size
limit to the queries at `depth < maxDistance` we may miss edges to the
requested type. Similarly the `type` filter can't be enforced at `depth
< maxDistance`

To do:

- [x] Add filtering by type
- [ ] ~Limit by size~
- [x] Add sample assets which use references
- [x] Add integration tests that validate each type of relation query
- [x] Add documentation and sample requests/responses for each relation
type
- [x] Handle circular references. In what situations can that happens,
references ?

Closes #153471
Closes #153473
Closes #153482

---------

Co-authored-by: kibanamachine <[email protected]>
Co-authored-by: klacabane <[email protected]>
Co-authored-by: Kevin Lacabane <[email protected]>
Co-authored-by: Carlos Crespo <[email protected]>

x-pack/plugins/asset_manager/common/types_api.ts

@@ -5,8 +5,16 @@
  * 2.0.
  */
 
+import { schema } from '@kbn/config-schema';
+
+export const assetTypeRT = schema.oneOf([
+  schema.literal('k8s.pod'),
+  schema.literal('k8s.cluster'),
+  schema.literal('k8s.node'),
+]);
+export type AssetType = typeof assetTypeRT.type;
+
 export type AssetKind = 'unknown' | 'node';
-export type AssetType = 'k8s.pod' | 'k8s.cluster' | 'k8s.node';
 export type AssetStatus =
   | 'CREATING'
   | 'ACTIVE'
@@ -52,6 +60,7 @@ export interface Asset extends ECSDocument {
   'asset.status'?: AssetStatus;
   'asset.parents'?: string | string[];
   'asset.children'?: string | string[];
+  'asset.references'?: string | string[];
   'asset.namespace'?: string;
 }
 
@@ -120,3 +129,15 @@ export interface AssetFilters {
   from?: string;
   to?: string;
 }
+
+export const relationRT = schema.oneOf([
+  schema.literal('ancestors'),
+  schema.literal('descendants'),
+  schema.literal('references'),
+]);
+
+export type Relation = typeof relationRT.type;
+export type RelationField = keyof Pick<
+  Asset,
+  'asset.children' | 'asset.parents' | 'asset.references'
+>;