diff --git a/docs/content/en/docs/implementing/slo/_index.md b/docs/content/en/docs/implementing/slo/_index.md index 12c821a5b3..b8867bec6d 100644 --- a/docs/content/en/docs/implementing/slo/_index.md +++ b/docs/content/en/docs/implementing/slo/_index.md @@ -44,7 +44,7 @@ and can be displayed on dashboard tools, such as Grafana. A Keptn Analysis is implemented with three resources: -* [AnalysisValueTemplate](../../crd-ref/metrics/v1alpha3/#analysisvaluetemplate) -- +* [AnalysisValueTemplate](../../yaml-crd-ref/analysisvaluetemplate.md) defines the SLI with the `KeptnMetricsProvider` (data source) and the query to perform for each SLI @@ -57,7 +57,7 @@ A Keptn Analysis is implemented with three resources: resource for each instance of each data provider you are using. The template refers to that provider and queries it. -* [AnalysisDefinition](../../crd-ref/metrics/v1alpha3/#analysisdefinition) -- +* [AnalysisDefinition](../../yaml-crd-ref/analysisdefinition.md) define the list of SLOs for an `Analysis` An `AnalysisDefinition` resource contains a list of objectives to satisfy. @@ -71,7 +71,7 @@ A Keptn Analysis is implemented with three resources: defining the data provider from which to gather the data and how to compute the Analysis -* [Analysis](../../crd-ref/metrics/v1alpha3/#analysis) -- +* [Analysis](../../yaml-crd-ref/analysis.md) define the specific configurations and the Analysis to report. An `Analysis` resource customizes the templates diff --git a/docs/content/en/docs/install/k8s.md b/docs/content/en/docs/install/k8s.md index cc21cf37eb..33a294d96d 100644 --- a/docs/content/en/docs/install/k8s.md +++ b/docs/content/en/docs/install/k8s.md @@ -132,6 +132,34 @@ Some considerations for Keptn: So you can create `KeptnMetrics` in a centralized namespace (such as `keptn-lifecycle-toolkit`) and access those metrics in evaluations on all namespaces in the cluster. +* Analysis related resources + ([Analysis](../yaml-crd-ref/analysis.md), + [AnalysisDefinition](../yaml-crd-ref/analysisdefinition.md), + and + [AnalysisValueTemplate](../yaml-crd-ref/analysisvaluetemplate.md)) + reference each other via a `name` and, optionally, a `namespace` field. + The `Analysis` resource references the `AnalysisDefinition` resource, + which then references the `AnalysisValueTemplate` resources. + + * If the `namespace` in the reference is not set explicitly, + the `AnalysisDefinition` and `AnalysisValueTemplate` resources + must reside in the same namespace as the `Analysis` resource. + * If the `namespace` in the reference is set for the resources, + the `Analysis`, `AnalysisDefinition`, and `AnalysisValueTemplate` resources + can each reside in different namespaces. + + This provides configuration options such as the following: + + * You can have one namespace + with all of your `AnalysisDefinition` and `AnalysisValueTemplate` resources + and reuse them in the different namespaces where you run analyses. + + * You can have everything strictly namespaced + and always put the `AnalysisDefinition`, `AnalysisValueTemplate` + and the `Analysis` resources into the same namespace, + without adding the explicit namespace selectors + when creating references between those objects. + * Each `KeptnApp` resource identifies the namespace to which it belongs. If you configure multiple namespaces, you can have `KeptnApp` resources with the same name diff --git a/docs/content/en/docs/yaml-crd-ref/analysis.md b/docs/content/en/docs/yaml-crd-ref/analysis.md index 8ac752ea96..0fc713f931 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysis.md +++ b/docs/content/en/docs/yaml-crd-ref/analysis.md @@ -45,7 +45,7 @@ status: [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) specification. * **spec** - * **timeframe** -- Specifies the range for the corresponding query + * **timeframe** (required) -- Specifies the range for the corresponding query in the AnalysisValueTemplate. This can be populated as one of the following: @@ -61,13 +61,18 @@ status: If neither is set, the Analysis can not be added to the cluster. * **args** -- Map of key/value pairs that can be used to substitute variables in the `AnalysisValueTemplate` query. - * **analysisDefinition** -- Identify the `AnalysisDefinition` resource + * **analysisDefinition** (required) -- Identify the `AnalysisDefinition` resource that stores the `AnalysisValuesTemplate` associated with this `Analysis` * **name** -- Name of the `AnalysisDefinition` resource - * **namespace** -- Namespace of the `AnalysisDefinition` resource. + * **namespace** (optional) -- + Namespace of the `AnalysisDefinition` resource. + The `AnalysisDefinition` resource can be located in any namespace. + If the namespace is not specified, + the analysis controller looks for the `AnalysisDefinition` resource + in the same namespace as the `Analysis` resource. * **status** -- results of this Analysis run, - added to the resource by Keptn. - * **pass** -- Whether the analysis passed or failed. + added to the resource by Keptn, + based on criteria defined in the `AnalysisDefinition` resource. * **warning** -- Whether the analysis returned a warning. * **raw** -- String-encoded JSON object that reaports the results diff --git a/docs/content/en/docs/yaml-crd-ref/analysisdefinition.md b/docs/content/en/docs/yaml-crd-ref/analysisdefinition.md index cdfb74ddff..a6523dbfd8 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysisdefinition.md +++ b/docs/content/en/docs/yaml-crd-ref/analysisdefinition.md @@ -13,23 +13,22 @@ list of Service Level Objectives (SLOs) for an `Analysis`. apiVersion: metrics.keptn.sh/v1alpha3 kind: AnalysisDefinition metadata: - name: ed-my-proj-dev-svc1 - namespace: keptn-lifecycle-toolkit-system + name: + namespace: spec: objectives: - analysisValueTemplateRef: - name: response-time-p95 - namespace: keptn-lifecycle-toolkit-system + name: + namespace: target: - failure: - lessThan: - fixedValue: 600 - warning: - inRange: - lowBound: 300 - highBound: 500 - weight: 1 - keyObjective: false + failure | warning: + : + : | + : + lowbound: + highBound: + weight: + keyObjective: totalScore: passPercentage: 90 warningPercentage: 75 @@ -39,30 +38,70 @@ spec: * **apiVersion** -- API version being used * **kind** -- Resource type. - Must be set to AnalysisDefinition. + Must be set to `AnalysisDefinition`. * **metadata** - * **name** ed-my-proj-dev-svc1 - * **namespace** keptn-lifecycle-toolkit-system + * **name** -- Unique name of this analysis definition. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification. + * **namespace** -- Namespace where this resource is located. + `Analysis` resources must specify this namespace + when referencing this definition, + unless it resides in the same namespace as the `Analysis` resource. * **spec** * **objectives** - * **analysisValueTemplateRef** - * **name** response-time-p95 - * **namespace** keptn-lifecycle-toolkit-system - * **target** - * **failure** - * **lessThan** - * **fixedValue** 600 + This is a list of objectives whose results are combined + to determine whether the analysis fails, passes, or passes with a warning. + * **analysisValueTemplateRef** (required) -- + This string marks the beginning of each objective + * **name** (required) -- The `metadata.name` value of the + [AnalysisDefinition](analysisdefinition.md) + resource used for this objective. + That resource defines the data provider and the query to use. + * **namespace** -- + Namespace of the `analysisValueTemplateRef` resource. + If the namespace is not specified, + the analysis controller looks for the `AnalysisValueTemplateRef` resource + in the same namespace as the `Analysis` resource. + * **target** -- defines failure or, optionally, warning criteria. + Values not specified for failure or warning result in a pass. + Keptn writes the results of the analysis to the `status` section + of the + [Analysis](analysis.md) + resource after the analysis runs. + * **failure** -- criteria for failure, specified as + `operator: `. + This can be specified either as an absolute value + or as a range of values. + + Valid operators for absolute values are: + * `lessThan` -- `<` operator + * `lessThanOrEqual` -- `<=` operator + * `greaterThan` -- `>` operator + * `greaterThanOrEqual` -- `>=` operator + * `equalTo` -- `==` operator + + Valid operators for specifying ranges are: + * `inRange` -- value is inclusively in the defined range + * `notInRange` -- value is exclusively out of the defined range + + Each of these operators require two arguments: + + * `lowBound` -- minimum value of the range included or excluded + * `highBound` -- maximum value of the range included or excluded - * **warning** - * **inRange** - * **lowBound** 300 - * **highBound** 500 - * **weight** 1 - * **keyObjective** false - * **totalScore** - * **passPercentage** 90 + * **warning** -- criteria for a warning, + specified in the same way as the `failure` field. + * **weight** -- used to emphasize the importance + of one `objective` over others + * **keyObjective** -- If set to `true`, + the entire analysis fails if this objective fails + * **totalScore** (required) -- + * **passPercentage** -- threshhold to reach for the full analysis + (all objectives) to pass - * **warningPercentage** + * **warningPercentage** -- threshhold to reach + for the full analysis (all objectives) to pass with `warning` status ## Usage @@ -92,17 +131,22 @@ spec: namespace: keptn-lifecycle-toolkit-system target: failure: - lessThan: - fixedValue: 600 + : + fixedValue: integer> | + inRange: | notInRange: + lowBound: + highBound: warning: - inRange: - lowBound: 300 - highBound: 500 - weight: 1 - keyObjective: false + : + fixedValue: integer> | + inRange: | notInRange: + lowBound: + highBound: + weight: + keyObjective: totalScore: - passPercentage: 90 - warningPercentage: 75 + passPercentage: + warningPercentage: ``` For an example of how to implement the Keptn Analysis feature, see the diff --git a/docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md b/docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md index 696398dc86..4c5d8fd557 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md +++ b/docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md @@ -18,7 +18,7 @@ apiVersion: metrics.keptn.sh/v1alpha3 kind: AnalysisValueTemplate metadata: name: response-time-p95 - namespace: keptn-lifecycle-toolkit-system + namespace: spec: provider: name: prometheus | dynatrace | dql | datadog @@ -46,9 +46,12 @@ spec: Names must comply with the [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) specification. - * **namespace** -- Namespace where this template lives + * **namespace** (optional) -- Namespace where this template lives. + `Analysis` resources must specify this namespace + when referencing this definition, + unless it resides in the same namespace as the `Analysis` resource. * **spec** - * **provider** + * **provider** (required) -- the KeptnMetricProvider * **name** -- The `spec.name` value of the [KeptnMetricsProvider](metricsprovider.md) resource to use. Note that each `AnalysisValueTemplate` resource @@ -56,7 +59,7 @@ spec: However, an `Analysis` resource can use multiple `AnalysisValueTemplate` resources, each of which uses a different data source. - * **query** -- query to be made. + * **query** (required) -- query to be made. This is done in the data provider's query language. It can include variables that use the go templating syntax to insert a placeholder in the query.