docs: add required labels to required CRD fields (Analysis, AnalysisD…

…efinition, AnalysisValueTemplate) (keptn#2356)

Release-As: 0.9.0

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

docs/content/en/docs/install/k8s.md

@@ -144,6 +144,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

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.
     <!-- markdownlint-disable -->
     * **warning** -- Whether the analysis returned a warning.
     * **raw** --  String-encoded JSON object that reaports the results

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: <name-of-this-resource>
+  namespace: <namespace-where-this-resource-resides>
 spec:
   objectives:
     - analysisValueTemplateRef:
-        name: response-time-p95
-        namespace: keptn-lifecycle-toolkit-system
+        name: <name-of-referenced-analysisValueTemplateRef-resource>
+        namespace: <namespace-of-the-template-ref>
       target:
-        failure:
-          lessThan:
-            fixedValue: 600
-        warning:
-          inRange:
-            lowBound: 300
-            highBound: 500
-      weight: 1
-      keyObjective: false
+        failure | warning:
+          <operator>:
+            <operatorValue>: <quantity> |
+            <RangeValue>:
+                lowbound: <quantity>
+                highBound: <quantity>
+      weight: <integer>
+      keyObjective: <boolean>
   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: <quantity>`.
+          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
         <!-- markdownlint-disable -->
-        * **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
     <!-- markdownlint-disable -->
-    * **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
+          <operator>:
+            fixedValue: integer> |
+            inRange: | notInRange:
+              lowBound: <integer-quantity>
+              highBound: <integer-quantity>
         warning:
-          inRange:
-            lowBound: 300
-            highBound: 500
-      weight: 1
-      keyObjective: false
+          <operator>:
+            fixedValue: integer> |
+            inRange: | notInRange:
+              lowBound: <integer-quantity>
+              highBound: <integer-quantity>
+      weight: <integer>
+      keyObjective: <boolean>
   totalScore:
-    passPercentage: 90
-    warningPercentage: 75
+    passPercentage: <integer-percentage>
+    warningPercentage: <integer-percentage>
 ```
 
 For an example of how to implement the Keptn Analysis feature, see the

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: <namespace-where-this-resource-resides>
 spec:
   provider:
     name: prometheus | dynatrace | dql | datadog
@@ -46,17 +46,20 @@ 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
       can use only one data source.
       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.