diff --git a/components/schemas/billing/methods/sources/MethodSource.yml b/components/schemas/billing/methods/sources/MethodSource.yml index bc251f81..19c3934a 100644 --- a/components/schemas/billing/methods/sources/MethodSource.yml +++ b/components/schemas/billing/methods/sources/MethodSource.yml @@ -1,4 +1,5 @@ title: MethodSource +type: object description: The underlying source (credit card, bank account, etc) used by a payment method. discriminator: propertyName: type diff --git a/components/schemas/monitoring/Metric.yml b/components/schemas/monitoring/metrics/Metric.yml similarity index 97% rename from components/schemas/monitoring/Metric.yml rename to components/schemas/monitoring/metrics/Metric.yml index 146f3e63..9e9053be 100644 --- a/components/schemas/monitoring/Metric.yml +++ b/components/schemas/monitoring/metrics/Metric.yml @@ -8,7 +8,7 @@ required: properties: time: description: When the metric was submitted to the platform. - $ref: ../DateTime.yml + $ref: ../../DateTime.yml labels: type: object description: Additional key-values that can be used for querying in an aggregation pipeline. Often useful for filtering. @@ -26,7 +26,7 @@ properties: type: array items: anyOf: - - $ref: ../DateTime.yml + - $ref: ../../DateTime.yml - type: integer metadata: description: Information about this metric, such as the type of metric, the data it represents, and critical common information such as hub ID and associated cluster. @@ -111,10 +111,10 @@ properties: description: The originator of this metric. type: string hub_id: - $ref: ../ID.yml + $ref: ../../ID.yml component: description: The specific resource ID and type associated with this metric. - type: + type: - object - "null" required: @@ -122,11 +122,11 @@ properties: - type properties: id: - $ref: ../ID.yml + $ref: ../../ID.yml type: type: string cluster: description: "The cluster associated with this metric" - type: + type: - string - "null" diff --git a/components/schemas/monitoring/monitors/Monitor.yml b/components/schemas/monitoring/monitors/Monitor.yml new file mode 100644 index 00000000..38028758 --- /dev/null +++ b/components/schemas/monitoring/monitors/Monitor.yml @@ -0,0 +1,131 @@ +title: Monitor +description: > + A user-defined monitor that watches conditions on the platform and raises alarms + when configured rules trigger. Monitors have a scope that determines what they + observe (globally or against specific clusters) and a configuration that + defines their evaluation logic. +type: object +required: + - id + - hub_id + - identifier + - creator + - status + - name + - description + - scope + - config + - state + - events +properties: + id: + type: string + description: A unique identifier for this monitor. + hub_id: + type: string + description: The ID of the hub this monitor belongs to. + identifier: + $ref: "../../Identifier.yml" + creator: + $ref: "../../common/UserScope.yml" + description: The user or entity that created this monitor. + status: + type: string + enum: + - ok + - no-data + - alarm + description: > + The current evaluation status of the monitor. + - `ok` - the monitor is evaluating and its rules are not triggered. + - `no-data` - the monitor has not received enough data to evaluate. + - `alarm` - the monitor's rules have triggered and the monitor is in an alarm state. + name: + type: string + description: A human-readable name for this monitor. + description: + type: string + description: A longer description of what this monitor observes and why. + scope: + type: object + description: What this monitor observes. Either global or scoped to specific clusters. + required: + - global + - clusters + properties: + global: + type: boolean + description: When true, the monitor observes all clusters within the hub. + clusters: + type: array + description: Cluster identifiers this monitor is scoped to. Ignored when global is true. + items: + $ref: "../../Identifier.yml" + config: + $ref: "./MonitorConfig.yml" + description: The evaluation configuration for this monitor. + state: + title: MonitorStateInfo + type: object + description: The current runtime state of the monitor. + required: + - current + - changed + properties: + current: + type: string + enum: + - paused + - live + - deleting + - deleted + description: > + The current lifecycle state of the monitor. + - `paused` - the monitor exists but is not evaluating. + - `live` - the monitor is evaluating on its configured window. + - `deleting` - the monitor is being torn down. + - `deleted` - the monitor has been removed. + changed: + description: The timestamp of the most recent state transition. + $ref: "../../DateTime.yml" + error: + type: object + description: Details of the last error, if the monitor is in an error condition. + required: + - message + - time + properties: + message: + type: string + description: A description of the error. + time: + description: The timestamp at which the error was recorded. + $ref: "../../DateTime.yml" + events: + title: MonitorEvents + type: object + description: A collection of timestamps for events in the Monitor's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the monitor was created. + $ref: "../../DateTime.yml" + updated: + description: The timestamp of when the monitor was updated. + $ref: "../../DateTime.yml" + deleted: + description: The timestamp of when the monitor was deleted. + $ref: "../../DateTime.yml" + last_alarm: + description: The timestamp of the most recent alarm event. + $ref: "../../DateTime.yml" + last_check: + description: The timestamp of the most recent evaluation. + $ref: "../../DateTime.yml" + meta: + type: object + description: Additional metadata attached to the monitor response. + additionalProperties: true diff --git a/components/schemas/monitoring/monitors/MonitorAction.yml b/components/schemas/monitoring/monitors/MonitorAction.yml new file mode 100644 index 00000000..2c7b5104 --- /dev/null +++ b/components/schemas/monitoring/monitors/MonitorAction.yml @@ -0,0 +1,15 @@ +title: MonitorAction +description: > + An action taken when a monitor's rule set matches. The type discriminates + what runs; details carries the type-specific configuration. +type: object +required: + - type + - details +properties: + type: + type: string + description: The kind of action to take. Determines the shape of the details object. + details: + description: Type-specific configuration for the action. + additionalProperties: true diff --git a/components/schemas/monitoring/monitors/MonitorConfig.yml b/components/schemas/monitoring/monitors/MonitorConfig.yml new file mode 100644 index 00000000..14ee7ca3 --- /dev/null +++ b/components/schemas/monitoring/monitors/MonitorConfig.yml @@ -0,0 +1,25 @@ +title: MonitorConfig +description: > + Configuration that defines how a monitor evaluates. The window and cool down + govern timing, the rule set defines the conditions that trigger an alarm, + and the actions list what happens when one does. +type: object +required: + - window + - cool_down + - rule_set + - actions +properties: + window: + description: The evaluation window over which rules are checked. + $ref: "../../Duration.yml" + cool_down: + description: The minimum time between successive alarms. Suppresses re-triggering while an alarm state persists. + $ref: "../../Duration.yml" + rule_set: + $ref: "./rules/MonitorRuleSet.yml" + actions: + type: array + description: Actions taken when the rule set evaluates to an alarm state. + items: + $ref: "./MonitorAction.yml" diff --git a/components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml b/components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml new file mode 100644 index 00000000..c062cc84 --- /dev/null +++ b/components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml @@ -0,0 +1,92 @@ +title: ActionGroup +description: > + A named, reusable collection of actions. Monitors can reference an action group + so that a single set of alarm responses can be shared across many monitors and + updated in one place. +type: object +required: + - id + - hub_id + - identifier + - creator + - name + - description + - actions + - state + - events +properties: + id: + type: string + description: A unique identifier for this action group. + hub_id: + type: string + description: The ID of the hub this action group belongs to. + identifier: + $ref: "../../../Identifier.yml" + creator: + $ref: "../../../common/UserScope.yml" + description: The user or entity that created this action group. + name: + type: string + description: A human-readable name for this action group. + description: + type: string + description: A longer description of what this action group does and when it is used. + actions: + type: array + description: The actions run when this group is triggered. + items: + $ref: "../MonitorAction.yml" + state: + title: ActionGroupStateInfo + type: object + description: The current runtime state of the action group. + required: + - current + - changed + properties: + current: + type: string + enum: + - live + - deleting + - deleted + description: The current state of the action group. + changed: + description: The timestamp of the most recent state transition. + $ref: "../../../DateTime.yml" + error: + type: object + description: Details of the last error, if the action group is in an error condition. + required: + - message + - time + properties: + message: + type: string + description: A description of the error. + time: + description: The timestamp at which the error was recorded. + $ref: "../../../DateTime.yml" + events: + title: ActionGroupEvents + type: object + description: A collection of timestamps for events in the action group's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the action group was created. + $ref: "../../../DateTime.yml" + updated: + description: The timestamp of when the action group was updated. + $ref: "../../../DateTime.yml" + deleted: + description: The timestamp of when the action group was deleted. + $ref: "../../../DateTime.yml" + meta: + type: object + description: Additional metadata attached to the action group response. + additionalProperties: true diff --git a/components/schemas/monitoring/monitors/rules/MonitorEventRule.yml b/components/schemas/monitoring/monitors/rules/MonitorEventRule.yml new file mode 100644 index 00000000..2330c015 --- /dev/null +++ b/components/schemas/monitoring/monitors/rules/MonitorEventRule.yml @@ -0,0 +1,40 @@ +title: MonitorEventRule +description: > + An event-based rule. At least one of target, priority, or type must be set; + the rule matches when a platform event satisfies every set field. Occurrences + controls how many matching events within the monitor's window are required + for the rule to trigger. +type: object +required: + - type + - details +properties: + type: + type: string + enum: + - event + description: Identifies this as an event rule. + details: + type: object + required: + - occurrences + properties: + target: + oneOf: + - $ref: ./MonitorRuleTarget.yml + - type: "null" + description: The event target to match on. Null disables this filter. + priority: + oneOf: + - type: string + - type: "null" + description: The event priority to match on. Null disables this filter. + type: + oneOf: + - type: string + - type: "null" + description: The event type to match on. Null disables this filter. + occurrences: + type: integer + minimum: 1 + description: The minimum number of matching events within the monitor's window required to trigger. diff --git a/components/schemas/monitoring/monitors/rules/MonitorMetricRule.yml b/components/schemas/monitoring/monitors/rules/MonitorMetricRule.yml new file mode 100644 index 00000000..53364955 --- /dev/null +++ b/components/schemas/monitoring/monitors/rules/MonitorMetricRule.yml @@ -0,0 +1,52 @@ +title: MonitorMetricRule +description: > + A metric-based rule. Aggregates the target metric across the monitor's window + and compares the result to the threshold using the operator. +type: object +required: + - type + - details +properties: + type: + type: string + enum: + - metric + details: + type: object + required: + - target + - aggregation + - operator + - threshold + properties: + target: + $ref: ./MonitorRuleTarget.yml + description: The metric target to evaluate. + aggregation: + type: string + enum: + - avg + - sum + - max + - min + description: > + How the metric samples in the window are combined into a single value. + - `avg` - arithmetic mean. + - `sum` - total of all samples. + - `max` - largest sample. + - `min` - smallest sample. + operator: + type: string + enum: + - "==" + - "!=" + - ">" + - "<" + - ">=" + - "<=" + description: The comparison applied between the aggregated value and the threshold. + threshold: + type: number + format: double + minimum: 0.01 + description: The value the aggregated metric is compared against. Must be at least 0.01. diff --git a/components/schemas/monitoring/monitors/rules/MonitorRule.yml b/components/schemas/monitoring/monitors/rules/MonitorRule.yml new file mode 100644 index 00000000..13e5ea65 --- /dev/null +++ b/components/schemas/monitoring/monitors/rules/MonitorRule.yml @@ -0,0 +1,13 @@ +title: MonitorRule +type: object +description: > + A single rule evaluated by the monitor. The type discriminates whether the + rule watches events or metrics. +discriminator: + propertyName: type + mapping: + event: ./MonitorEventRule.yml + metric: ./MonitorMetricRule.yml +oneOf: + - $ref: ./MonitorEventRule.yml + - $ref: ./MonitorMetricRule.yml diff --git a/components/schemas/monitoring/monitors/rules/MonitorRuleSet.yml b/components/schemas/monitoring/monitors/rules/MonitorRuleSet.yml new file mode 100644 index 00000000..b42773c0 --- /dev/null +++ b/components/schemas/monitoring/monitors/rules/MonitorRuleSet.yml @@ -0,0 +1,24 @@ +title: MonitorRuleSet +description: > + A collection of rules and how they combine. Rules evaluate individually; the + evaluate mode determines whether all of them must match for the set to trigger, + or whether any single match is enough. +type: object +required: + - evaluate + - rules +properties: + evaluate: + type: string + enum: + - any + - all + description: > + How the rules combine. + - `any` - the rule set matches when any rule matches. + - `all` - the rule set matches only when every rule matches. + rules: + type: array + description: The individual rules evaluated by the rule set. + items: + $ref: ./MonitorRule.yml diff --git a/components/schemas/monitoring/monitors/rules/MonitorRuleTarget.yml b/components/schemas/monitoring/monitors/rules/MonitorRuleTarget.yml new file mode 100644 index 00000000..eb5ee63e --- /dev/null +++ b/components/schemas/monitoring/monitors/rules/MonitorRuleTarget.yml @@ -0,0 +1,6 @@ +title: MonitorRuleTarget +description: > + The subject of a monitor rule — the event target or metric name to evaluate + against. Alphanumeric characters, dots, hyphens, and underscores only. +type: string +pattern: "^[a-zA-Z0-9._-]+$" diff --git a/components/schemas/monitoring/monitors/tasks/MonitorReconfigureAction.yml b/components/schemas/monitoring/monitors/tasks/MonitorReconfigureAction.yml new file mode 100644 index 00000000..d296e22b --- /dev/null +++ b/components/schemas/monitoring/monitors/tasks/MonitorReconfigureAction.yml @@ -0,0 +1,23 @@ +title: MonitorReconfigureAction +description: > + Replaces the monitor's evaluation configuration. The new config is validated + before the job is queued; if validation fails, the request returns 422 without + queueing. +type: object +required: + - action + - contents +properties: + action: + type: string + enum: + - reconfigure + description: Identifies this as a reconfigure task. + contents: + type: object + required: + - config + properties: + config: + $ref: ../MonitorConfig.yml + description: The new configuration for the monitor. diff --git a/components/schemas/monitoring/monitors/tasks/MonitorTask.yml b/components/schemas/monitoring/monitors/tasks/MonitorTask.yml new file mode 100644 index 00000000..f66dc78b --- /dev/null +++ b/components/schemas/monitoring/monitors/tasks/MonitorTask.yml @@ -0,0 +1,8 @@ +title: MonitorTask +description: A task to be run against a monitor. +discriminator: + propertyName: action + mapping: + reconfigure: ./MonitorReconfigureAction.yml +oneOf: + - $ref: ./MonitorReconfigureAction.yml diff --git a/components/schemas/monitoring/Monitor.yml b/components/schemas/monitoring/platform/PlatformMonitor.yml similarity index 86% rename from components/schemas/monitoring/Monitor.yml rename to components/schemas/monitoring/platform/PlatformMonitor.yml index 783551fd..9a070ce1 100644 --- a/components/schemas/monitoring/Monitor.yml +++ b/components/schemas/monitoring/platform/PlatformMonitor.yml @@ -1,6 +1,6 @@ -title: Monitor +title: PlatformMonitor description: > - A monitor used to determine latency between the public internet and a load balancer on Cycle. + A platform monitor used to determine latency between the public internet and a load balancer on Cycle. These monitors are automatically created and managed by the platform. Information about specific monitors is provided for determining the regional latencies for an environment. type: object @@ -8,7 +8,7 @@ properties: node_id: type: string description: The ID of the node this monitor is running on. - country_short: + country_short: type: string description: The country code of where this monitor is located. country: @@ -35,4 +35,4 @@ required: - region - city - latitude - - longitude \ No newline at end of file + - longitude diff --git a/platform/api.yml b/platform/api.yml index 8420cc5c..9d6023a7 100644 --- a/platform/api.yml +++ b/platform/api.yml @@ -685,7 +685,20 @@ paths: "/v1/monitoring/logs/aggregate": $ref: paths/monitoring/logs/aggregate.yml "/v1/monitoring/platform/monitors": + $ref: paths/monitoring/platform/platformMonitors.yml + + ## Monitors + "/v1/monitoring/monitors": $ref: paths/monitoring/monitors/monitors.yml + "/v1/monitoring/monitors/{id}": + $ref: paths/monitoring/monitors/monitor.yml + "/v1/monitoring/monitors/{id}/tasks": + $ref: paths/monitoring/monitors/tasks.yml + ## Action Groups + "/v1/monitoring/monitors/action-groups": + $ref: paths/monitoring/monitors/action-groups/action-groups.yml + "/v1/monitoring/monitors/action-groups/{id}": + $ref: paths/monitoring/monitors/action-groups/action-group.yml # --Pipelines "/v1/pipelines": @@ -803,7 +816,7 @@ webhooks: schema: type: array items: - $ref: ../components/schemas/monitoring/Metric.yml + $ref: ../components/schemas/monitoring/metrics/Metric.yml environmentEventsPush: post: operationId: environmentEventsPush diff --git a/platform/paths/monitoring/metrics/metrics.yml b/platform/paths/monitoring/metrics/metrics.yml index 01769038..d579bec4 100644 --- a/platform/paths/monitoring/metrics/metrics.yml +++ b/platform/paths/monitoring/metrics/metrics.yml @@ -72,6 +72,6 @@ get: data: type: array items: - $ref: ../../../../components/schemas/monitoring/Metric.yml + $ref: ../../../../components/schemas/monitoring/metrics/Metric.yml default: $ref: ../../../../components/responses/errors/DefaultError.yml diff --git a/platform/paths/monitoring/monitors/action-groups/action-group.yml b/platform/paths/monitoring/monitors/action-groups/action-group.yml new file mode 100644 index 00000000..681fe247 --- /dev/null +++ b/platform/paths/monitoring/monitors/action-groups/action-group.yml @@ -0,0 +1,128 @@ +get: + operationId: "getActionGroup" + summary: Get Action Group + description: Requires the `monitoring-monitors-view` capability. + tags: + - Monitoring + parameters: + - name: id + in: path + required: true + description: The ID of the action group to fetch. + schema: + type: string + pattern: "^[a-f0-9]{24}$" + - name: include + in: query + required: false + description: + A comma separated list of include values. Included resources will show up under + the root document's `include` field, with the key being the id of the included resource. + schema: + type: array + items: + type: string + enum: + - creators + responses: + 200: + description: Returns an Action Group. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../../components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml + includes: + type: object + properties: + creators: + $ref: ../../../../../components/schemas/includes/IncludedCreators.yml + default: + $ref: ../../../../../components/responses/errors/DefaultError.yml +patch: + operationId: "updateActionGroup" + summary: Update Action Group + description: | + Requires the `monitoring-monitors-manage` capability. + + Action groups in `deleting` or `deleted` state cannot be updated. + tags: + - Monitoring + parameters: + - name: id + in: path + required: true + description: The ID of the action group to update. + schema: + type: string + pattern: "^[a-f0-9]{24}$" + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A user-defined name for the action group. Cannot be empty when provided. + identifier: + oneOf: + - $ref: ../../../../../components/schemas/Identifier.yml + - type: "null" + description: + type: string + description: A longer description of what this action group does and when it is used. + actions: + type: array + description: The actions run when this group is triggered. + items: + $ref: ../../../../../components/schemas/monitoring/monitors/MonitorAction.yml + responses: + 200: + description: Returns the updated Action Group. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../../components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml + default: + $ref: ../../../../../components/responses/errors/DefaultError.yml +delete: + operationId: "deleteActionGroup" + summary: Delete Action Group + description: | + Requires the `monitoring-monitors-manage` capability. + + Deletion runs asynchronously via a job. The response returns a Task with the queued job details. + tags: + - Monitoring + parameters: + - name: id + in: path + required: true + description: The ID of the action group to delete. + schema: + type: string + pattern: "^[a-f0-9]{24}$" + responses: + 202: + description: Returns a Task acknowledging the queued deletion job. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../../components/schemas/jobs/JobDescriptor.yml + default: + $ref: ../../../../../components/responses/errors/DefaultError.yml diff --git a/platform/paths/monitoring/monitors/action-groups/action-groups.yml b/platform/paths/monitoring/monitors/action-groups/action-groups.yml new file mode 100644 index 00000000..10d1cd44 --- /dev/null +++ b/platform/paths/monitoring/monitors/action-groups/action-groups.yml @@ -0,0 +1,111 @@ +get: + operationId: "getActionGroups" + summary: List Action Groups + description: Requires the `monitoring-monitors-view` capability. + tags: + - Monitoring + parameters: + - name: include + in: query + required: false + description: + A comma separated list of include values. Included resources will show up under + the root document's `include` field, with the key being the id of the included resource. + schema: + type: array + items: + type: string + enum: + - creators + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + identifier: + type: string + description: | + `filter[identifier]=value` List only those action groups matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given action group(s). + state: + type: string + description: | + `filter[state]=value1,value2` filter by the action group's current lifecycle state. + - $ref: ../../../../../components/parameters/SortParam.yml + - $ref: ../../../../../components/parameters/PageParam.yml + responses: + 200: + description: Returns a list of Action Groups. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: ../../../../../components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml + includes: + type: object + properties: + creators: + $ref: ../../../../../components/schemas/includes/IncludedCreators.yml + default: + $ref: ../../../../../components/responses/errors/DefaultError.yml +post: + operationId: "createActionGroup" + summary: Create Action Group + description: Requires the `monitoring-monitors-manage` capability. + tags: + - Monitoring + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - name + - description + - actions + properties: + name: + type: string + description: A user-defined name for the action group. Cannot be empty. + description: + type: string + description: A longer description of what this action group does and when it is used. + identifier: + oneOf: + - $ref: ../../../../../components/schemas/Identifier.yml + - type: "null" + description: A slug for the action group. Generated from the name when omitted or empty. + actions: + type: array + description: The actions run when this group is triggered. + items: + $ref: ../../../../../components/schemas/monitoring/monitors/MonitorAction.yml + responses: + 201: + description: Returns an Action Group. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../../components/schemas/monitoring/monitors/actionGroups/ActionGroup.yml + default: + $ref: ../../../../../components/responses/errors/DefaultError.yml diff --git a/platform/paths/monitoring/monitors/monitor.yml b/platform/paths/monitoring/monitors/monitor.yml new file mode 100644 index 00000000..9ef4102f --- /dev/null +++ b/platform/paths/monitoring/monitors/monitor.yml @@ -0,0 +1,138 @@ +get: + operationId: "getMonitor" + summary: Get Monitor + description: Requires the `monitoring-monitors-view` capability. + tags: + - Monitoring + parameters: + - name: id + in: path + required: true + description: The ID of the monitor to fetch. + schema: + type: string + pattern: "^[a-f0-9]{24}$" + - name: include + in: query + required: false + description: + A comma separated list of include values. Included resources will show up under + the root document's `include` field, with the key being the id of the included resource. + schema: + type: array + items: + type: string + enum: + - creators + responses: + 200: + description: Returns a Monitor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../components/schemas/monitoring/monitors/Monitor.yml + includes: + type: object + properties: + creators: + $ref: ../../../../components/schemas/includes/IncludedCreators.yml + default: + $ref: ../../../../components/responses/errors/DefaultError.yml +patch: + operationId: "updateMonitor" + summary: Update Monitor + description: | + Requires the `monitoring-monitors-manage` capability. + + Monitors in `deleting` or `deleted` state cannot be updated. + tags: + - Monitoring + parameters: + - name: id + in: path + required: true + description: The ID of the monitor to update. + schema: + type: string + pattern: "^[a-f0-9]{24}$" + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A user-defined name for the monitor. Cannot be empty when provided. + identifier: + oneOf: + - $ref: ../../../../components/schemas/Identifier.yml + - type: "null" + description: + type: string + description: A longer description of what this monitor observes and why. + scope: + type: object + description: What this monitor observes. + required: + - global + - clusters + properties: + global: + type: boolean + description: When true, the monitor observes all clusters within the hub. + clusters: + type: array + description: Cluster identifiers this monitor is scoped to. Ignored when global is true. + items: + $ref: ../../../../components/schemas/Identifier.yml + responses: + 200: + description: Returns the updated Monitor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../components/schemas/monitoring/monitors/Monitor.yml + default: + $ref: ../../../../components/responses/errors/DefaultError.yml +delete: + operationId: "deleteMonitor" + summary: Delete Monitor + description: | + Requires the `monitoring-monitors-manage` capability. + + Deletion runs asynchronously via a job. The response returns a Task with the queued job details. + tags: + - Monitoring + parameters: + - name: id + in: path + required: true + description: The ID of the monitor to delete. + schema: + type: string + pattern: "^[a-f0-9]{24}$" + responses: + 202: + description: Returns a Task acknowledging the queued deletion job. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../components/schemas/jobs/JobDescriptor.yml + default: + $ref: ../../../../components/responses/errors/DefaultError.yml diff --git a/platform/paths/monitoring/monitors/monitors.yml b/platform/paths/monitoring/monitors/monitors.yml index 83f779e9..f65f4cb1 100644 --- a/platform/paths/monitoring/monitors/monitors.yml +++ b/platform/paths/monitoring/monitors/monitors.yml @@ -1,15 +1,53 @@ get: - operationId: "getMonitoringMonitors" - summary: Get Monitoring Monitors - description: | - Returns location information about the monitors used for Cycle's external monitoring service. - These monitors are used for determining the latency between the public internet and environment - load balancers. + operationId: "getMonitors" + summary: List Monitors + description: Requires the `monitoring-monitors-view` capability. tags: - Monitoring + parameters: + - name: include + in: query + required: false + description: + A comma separated list of include values. Included resources will show up under + the root document's `include` field, with the key being the id of the included resource. + schema: + type: array + items: + type: string + enum: + - creators + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + identifier: + type: string + description: | + `filter[identifier]=value` List only those monitors matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given monitor(s). + state: + type: string + description: | + `filter[state]=value1,value2` filter by the monitor's current lifecycle state. + cluster: + type: string + description: | + `filter[cluster]=identifier` list monitors that either apply globally or are scoped to the specified cluster. + - $ref: ../../../../components/parameters/SortParam.yml + - $ref: ../../../../components/parameters/PageParam.yml responses: 200: - description: Returns and array of monitor location information. + description: Returns a list of Monitors. content: application/json: schema: @@ -20,6 +58,71 @@ get: data: type: array items: - $ref: ../../../../components/schemas/monitoring/Monitor.yml + $ref: ../../../../components/schemas/monitoring/monitors/Monitor.yml + includes: + type: object + properties: + creators: + $ref: ../../../../components/schemas/includes/IncludedCreators.yml + default: + $ref: ../../../../components/responses/errors/DefaultError.yml +post: + operationId: "createMonitor" + summary: Create Monitor + description: Requires the `monitoring-monitors-manage` capability. + tags: + - Monitoring + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - name + - description + - scope + - config + properties: + name: + type: string + description: A user-defined name for the monitor. Cannot be empty. + description: + type: string + description: A longer description of what this monitor observes and why. + identifier: + oneOf: + - $ref: ../../../../components/schemas/Identifier.yml + - type: "null" + description: A slug for the monitor. Generated from the name when omitted or empty. + scope: + type: object + description: What this monitor observes. Either global or scoped to specific clusters. + required: + - global + - clusters + properties: + global: + type: boolean + description: When true, the monitor observes all clusters within the hub. + clusters: + type: array + description: Cluster identifiers this monitor is scoped to. Ignored when global is true. + items: + $ref: ../../../../components/schemas/Identifier.yml + config: + $ref: ../../../../components/schemas/monitoring/monitors/MonitorConfig.yml + responses: + 201: + description: Returns a Monitor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: ../../../../components/schemas/monitoring/monitors/Monitor.yml default: $ref: ../../../../components/responses/errors/DefaultError.yml diff --git a/platform/paths/monitoring/monitors/tasks.yml b/platform/paths/monitoring/monitors/tasks.yml new file mode 100644 index 00000000..81695cf9 --- /dev/null +++ b/platform/paths/monitoring/monitors/tasks.yml @@ -0,0 +1,41 @@ +post: + operationId: "createMonitorJob" + summary: Create Monitor Job + description: | + Create a job for a monitor. Currently supports the `reconfigure` action, which + replaces the monitor's evaluation configuration. + + Requires the `monitoring-monitors-manage` capability. + + Monitors in `deleting` or `deleted` state cannot accept jobs. + tags: + - Monitoring + parameters: + - name: id + description: The ID of the requested monitor. + in: path + required: true + schema: + type: string + pattern: "^[a-f0-9]{24}$" + requestBody: + description: Parameters for creating a new monitor job. + content: + application/json: + schema: + $ref: ../../../../components/schemas/monitoring/monitors/tasks/MonitorTask.yml + responses: + 202: + description: Returns a Job Descriptor. + content: + application/json: + schema: + title: "TaskResponse" + type: object + required: + - data + properties: + data: + $ref: ../../../../components/schemas/jobs/JobDescriptor.yml + default: + $ref: ../../../../components/responses/errors/DefaultError.yml diff --git a/platform/paths/monitoring/platform/platformMonitors.yml b/platform/paths/monitoring/platform/platformMonitors.yml new file mode 100644 index 00000000..fe2638e6 --- /dev/null +++ b/platform/paths/monitoring/platform/platformMonitors.yml @@ -0,0 +1,25 @@ +get: + operationId: "getPlatformMonitors" + summary: Get Platform Monitors + description: | + Returns location information about the monitors used for Cycle's external platform monitoring service. + These monitors are used for determining the latency between the public internet and environment + load balancers. + tags: + - Monitoring + responses: + 200: + description: Returns and array of monitor location information. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: ../../../../components/schemas/monitoring/platform/PlatformMonitor.yml + default: + $ref: ../../../../components/responses/errors/DefaultError.yml