From 472271dbd5fc0c14210080cc3a2ee900a9d9c9d0 Mon Sep 17 00:00:00 2001 From: Yash Mehrotra Date: Wed, 4 Sep 2024 12:20:13 +0530 Subject: [PATCH] chore: add topology crd in reference docs --- common/src/components/Fields.jsx | 2 +- .../docs/reference/topology/components.mdx | 190 ++++++++++++------ .../docs/reference/topology/crd.mdx | 141 +++++++++++++ .../docs/reference/topology/index.mdx | 74 +------ 4 files changed, 273 insertions(+), 134 deletions(-) create mode 100644 mission-control/docs/reference/topology/crd.mdx diff --git a/common/src/components/Fields.jsx b/common/src/components/Fields.jsx index b871b632..89485dca 100644 --- a/common/src/components/Fields.jsx +++ b/common/src/components/Fields.jsx @@ -62,7 +62,7 @@ export default function Fields({ common = [], rows = [], oneOf, anyOf, connectio return 1 } - return a.field.localeCompare(b.field) + return 0 } rows = rows.concat(common.filter(row => row.required)) rows.sort(fieldSorter); diff --git a/mission-control/docs/reference/topology/components.mdx b/mission-control/docs/reference/topology/components.mdx index 3ad4f820..727f33fd 100644 --- a/mission-control/docs/reference/topology/components.mdx +++ b/mission-control/docs/reference/topology/components.mdx @@ -2,65 +2,133 @@ title: Component --- -import Lookup from '@site/docs/reference/topology/_lookup.md' -import ForEach from '@site/docs/reference/topology/_forEach.md' - -Components are the building blocks of a Topology. The component specification provides a way for you to define the properties and characteristics of each Component in the Topology. - -# Component - -| Field | Description | Scheme | Required | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- | -| `checks` | Specify checks based on `inline` and `selector` | [`[]Check`](#check) | | -| `components` | RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or pre-compute a JSON encoding. | [`[]Component`](#component) | | -| `configs` | Specify selectors for config items that should be associated with this component. | [`[]Config`](#config-selector) | | -| `forEach` | Only applies when using lookup. When specified, the components and properties specified under ForEach will be templated using the components returned by the lookup. | [`ForEach`](#foreach) | | -| `icon` | Specify icon for component | `string` | | -| `id` | Specify unique ID for component | [`ID`](./index.mdx#id-selector) | | -| `labels` | Labels for the component | `map[string]string` | | -| `lifecycle` | The lifecycle state of the component e.g. production, staging, dev, etc. | `string` | | -| `lookup` | Lookup component definitions from an external source, use the `forEach` property to iterate over the results to further enrich each component. | [`Lookup`](#lookup) | | -| `name` | Set name for component | `string` | | -| `namespace` | Set namespace for component | `string` | | -| `order` | Set integer order value for component | `int` | | -| `owner` | Specify owner of component | `string` | | -| `properties` | Customize component properties as to be visualized on Mission control UI | [`[]Property`](./properties) | | -| `relationships` | Specify relationship of component | [`[]RelationshipSpec`](#relationshipspec) | | -| `selectors` | Specify component for topology based on `fieldSelector` and `labelSelector` | [`[]ResourceSelector`](../resource-selector) | | -| `tooltip` | Set tooltip outlining information pertaining to the component | `string` | | -| `type` | Set type of component e.g. service, API, website, library, database, etc. | `string` | | - -### RelationshipSpec - -| Field | Description | Scheme | Required | -| ------ | ---------------------------------------------------------------------------------------- | -------- | -------- | -| `ref` | Set reference for components relationship | `string` | | -| `type` | Set the type of relationship, e.g. dependsOn, subcomponentOf, providesApis, consumesApis | `string` | | - -### ForEach - - - -## Config Selector - -| Field | Description | Scheme | Required | -| ------------- | ----------------------------------------- | ------------------- | -------- | -| `id` | Specify the name of the config item. | `[]string` | | -| `name` | Specify the name of the config item. | `string` | | -| `namespace` | Specify the namespace of the config item. | `string` | | -| `type` | Specify type of config item. | `string` | | -| `class` | Specify type of config item. | `string` | | -| `external_id` | Specify type of config item. | `string` | | -| `tags` | Specify tags of config item. | `map[string]string` | | - -## Check - -| Field | Description | Scheme | Required | -| ---------- | -------------------------------- | ---------------------------------------------------- | -------- | -| `inline` | Define a new health check inline | [`CanarySpec`](/reference/canary-checker) | | -| `selector` | Select an existing health check | [`[]ResourceSelector`](/reference/resource-selector) | | - -## Lookup - - + diff --git a/mission-control/docs/reference/topology/crd.mdx b/mission-control/docs/reference/topology/crd.mdx new file mode 100644 index 00000000..b09be489 --- /dev/null +++ b/mission-control/docs/reference/topology/crd.mdx @@ -0,0 +1,141 @@ +--- +title: CRD +sidebar_position: 1 +--- + +import Lookup from '@site/docs/reference/topology/_lookup.md' + +import ForEach from '@site/docs/reference/topology/_forEach.md' + +This page defines the specification for Topology. There are few samples in the examples section. + +| Field | Description | Scheme | Required | +| ------------ | ------------------------------------------------------------------------------ | -------------------------------------------------- | -------- | +| `id` | Specify unique ID for topology | [`IDSelector`](#id-selector) | | +| `components` | Specify the topology fields for your service, application, check, etc. | [`[]Component`](#component) | | +| `configs` | Specify selectors for config items that should be related with this topology. | [`[]ConfigSelector`](#config-selector) | | +| `groupBy` | Specify the catalog tag (& optionally the tag selector) to group the topology. | [`[]GroupBy`](#group-by) | | +| `icon` | Set an icon class for topology. | [`Icon`](/reference/types#icon) | | +| `owner` | Specify owner for the topology. | `string` | | +| `properties` | Customize topology properties as to be visualized on Mission control UI. | [`[]Property`](./properties) | | +| `schedule` | Set schedule to update topology at the set interval. | `string` | | +| `text` | Set description or text of choice pertaining to topology. | `string` | | +| `tooltip` | Set tooltip outlining information pertaining to the topology. | `string` | | +| `type` | Set type of topology e.g. service, API, website, library, database, etc. | `string` | | +| `push` | Set type of topology e.g. service, API, website, library, database, etc. | [`HTTPConnection`](/reference/connections/http) | | + +### ID Selector + + + +### Group By + +A single topology definition can generate multiple distinct topologies by grouping the resources based on a config tag. +Grouping by tags provides a convenient way to manage and organize your topologies based on logical boundaries or dimensions, such as environment, region, or cluster. +For example, if you have configs scraped from three different clusters (aws, azure, gcp), grouping the topology by the `cluster` tag will generate three separate topologies, +one for each cluster tag value (aws, azure, gcp). + +This allows you to define a single topology that can automatically generate multiple topologies & stay up-to-date and aligned as your infrastructure grows and new clusters or environments are added without having to ever update the topology. + +:::info +It is important to understand that group by tag works only when a toplogy is built from catalog & config lookups/selectors. +Config tags are crucial to the functioning of grouping. +::: + + + +```yaml file=../../../modules/canary-checker/fixtures/topology/kubernetes-cluster-group-by.yaml + +``` + +Components are the building blocks of a Topology. The component specification provides a way for you to define the properties and characteristics of each Component in the Topology. + +## Component + +| Field | Description | Scheme | Required | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- | +| `checks` | Specify checks based on `inline` and `selector` | [`[]Check`](#check) | | +| `components` | RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or pre-compute a JSON encoding. | [`[]Component`](#component) | | +| `configs` | Specify selectors for config items that should be associated with this component. | [`[]Config`](#config-selector) | | +| `forEach` | Only applies when using lookup. When specified, the components and properties specified under ForEach will be templated using the components returned by the lookup. | [`ForEach`](#foreach) | | +| `icon` | Specify icon for component | `string` | | +| `id` | Specify unique ID for component | [`ID`](./index.mdx#id-selector) | | +| `labels` | Labels for the component | `map[string]string` | | +| `lifecycle` | The lifecycle state of the component e.g. production, staging, dev, etc. | `string` | | +| `lookup` | Lookup component definitions from an external source, use the `forEach` property to iterate over the results to further enrich each component. | [`Lookup`](#lookup) | | +| `name` | Set name for component | `string` | | +| `namespace` | Set namespace for component | `string` | | +| `order` | Set integer order value for component | `int` | | +| `owner` | Specify owner of component | `string` | | +| `properties` | Customize component properties as to be visualized on Mission control UI | [`[]Property`](./properties) | | +| `relationships` | Specify relationship of component | [`[]RelationshipSpec`](#relationshipspec) | | +| `selectors` | Specify component for topology based on `fieldSelector` and `labelSelector` | [`[]ResourceSelector`](../resource-selector) | | +| `tooltip` | Set tooltip outlining information pertaining to the component | `string` | | +| `type` | Set type of component e.g. service, API, website, library, database, etc. | `string` | | + +### RelationshipSpec + +| Field | Description | Scheme | Required | +| ------ | ---------------------------------------------------------------------------------------- | -------- | -------- | +| `ref` | Set reference for components relationship | `string` | | +| `type` | Set the type of relationship, e.g. dependsOn, subcomponentOf, providesApis, consumesApis | `string` | | + +### ForEach + + + +## Config Selector + +| Field | Description | Scheme | Required | +| ------------- | ----------------------------------------- | ------------------- | -------- | +| `id` | Specify the name of the config item. | `[]string` | | +| `name` | Specify the name of the config item. | `string` | | +| `namespace` | Specify the namespace of the config item. | `string` | | +| `type` | Specify type of config item. | `string` | | +| `class` | Specify type of config item. | `string` | | +| `external_id` | Specify type of config item. | `string` | | +| `tags` | Specify tags of config item. | `map[string]string` | | + +## Check + +| Field | Description | Scheme | Required | +| ---------- | -------------------------------- | ---------------------------------------------------- | -------- | +| `inline` | Define a new health check inline | [`CanarySpec`](/reference/canary-checker) | | +| `selector` | Select an existing health check | [`[]ResourceSelector`](/reference/resource-selector) | | + +## Lookup + + diff --git a/mission-control/docs/reference/topology/index.mdx b/mission-control/docs/reference/topology/index.mdx index 927caf64..7a242d58 100644 --- a/mission-control/docs/reference/topology/index.mdx +++ b/mission-control/docs/reference/topology/index.mdx @@ -3,76 +3,6 @@ title: Topology sidebar_position: 6 --- -This page defines the specification for Topology. There are few samples in the examples section. +import DocCardList from '@theme/DocCardList'; -| Field | Description | Scheme | Required | -| ------------ | ------------------------------------------------------------------------------ | -------------------------------------------------- | -------- | -| `id` | Specify unique ID for topology | [`IDSelector`](#id-selector) | | -| `components` | Specify the topology fields for your service, application, check, etc. | [`[]Component`](./components) | | -| `configs` | Specify selectors for config items that should be related with this topology. | [`[]ConfigSelector`](./components#config-selector) | | -| `groupBy` | Specify the catalog tag (& optionally the tag selector) to group the topology. | [`[]GroupBy`](./components#group-by) | | -| `icon` | Set an icon class for topology. | [`Icon`](/reference/types#icon) | | -| `owner` | Specify owner for the topology. | `string` | | -| `properties` | Customize topology properties as to be visualized on Mission control UI. | [`[]Property`](./properties) | | -| `schedule` | Set schedule to update topology at the set interval. | `string` | | -| `text` | Set description or text of choice pertaining to topology. | `string` | | -| `tooltip` | Set tooltip outlining information pertaining to the topology. | `string` | | -| `type` | Set type of topology e.g. service, API, website, library, database, etc. | `string` | | -| `push` | Set type of topology e.g. service, API, website, library, database, etc. | [`HTTPConnection`](/reference/connections/http) | | - -### ID Selector - - - -### Group By - -A single topology definition can generate multiple distinct topologies by grouping the resources based on a config tag. -Grouping by tags provides a convenient way to manage and organize your topologies based on logical boundaries or dimensions, such as environment, region, or cluster. -For example, if you have configs scraped from three different clusters (aws, azure, gcp), grouping the topology by the `cluster` tag will generate three separate topologies, -one for each cluster tag value (aws, azure, gcp). - -This allows you to define a single topology that can automatically generate multiple topologies & stay up-to-date and aligned as your infrastructure grows and new clusters or environments are added without having to ever update the topology. - -:::info -It is important to understand that group by tag works only when a toplogy is built from catalog & config lookups/selectors. -Config tags are crucial to the functioning of grouping. -::: - - - -```yaml file=../../../modules/canary-checker/fixtures/topology/kubernetes-cluster-group-by.yaml - -``` +