docs: add namespace restriction info (#3335)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Signed-off-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>

README.md

@@ -110,51 +110,20 @@ helm repo update
 helm upgrade --install keptn keptn/keptn -n keptn-system --create-namespace --wait
 ```
 
-### Installation with only certain namespaces allowed
-
-Keptn lifecycle orchestration is by default enabled for all namespaces except the following ones:
-
-- `kube-system`
-- `kube-public`
-- `kube-node-lease`
-- `cert-manager`
-- `keptn-system`
-- `observability`
-- `monitoring`
-- `<Keptn installation namespace>`
-
-To restrict Keptn lifecycle orchestration to specific namespaces, you must specify
-those namespaces during installation via helm values.
-First you need to create a `values.yaml`
-file
-
-```yaml
-lifecycleOperator:
-  allowedNamespaces:
-  - allowed-ns-1
-  - allowed-ns-2
-```
-
-and add the values file to the helm installation command:
-
-```shell
-helm repo add keptn https://charts.lifecycle.keptn.sh
-helm repo update
-helm upgrade --install keptn keptn/keptn -n keptn-system --values values.yaml --create-namespace --wait
-```
-
-> **Note**
-Please be aware that you still need to correctly annotate the namespaces where
-Keptn lifecycle orchestration is allowed.
-> To annotate them, use:
-
-```shell
-kubectl annotate ns <your-allowed-namespace> keptn.sh/lifecycle-toolkit='enabled'
-```
-
-> **Note**
-Please be aware that, if this option is set, adding any additional namespace
-requires the helm installation to be updated by adding the name of the new namespace to the list.
+### Monitored namespaces
+
+Keptn must be installed in its own namespace
+that does not run other major components or deployments.
+
+By default, the Keptn lifecycle orchestration
+monitors all namespaces in the cluster
+except for a few namespaces that are reserved
+for specific Kubernetes and other components.
+You can modify the Helm chart to specify the namespaces
+where the Keptn lifecycle orchestration is allowed.
+For more information, see the "Namespaces and Keptn" page in the
+[Configuration](https://keptn.sh/stable/docs/installation/configuration/)
+section of the documentation.
 
 ## More information
 

docs/docs/installation/configuration/index.md

@@ -5,4 +5,5 @@ comments: true
 # Configuration
 
 This section contains guides for specific configuration use cases for Keptn.
-Those will help you adjust settings that need to be set at installation time.
+These will help you adjust settings that need to be set at installation time
+and allocate resources required to run Keptn.

docs/docs/installation/configuration/namespace-keptn.md

@@ -0,0 +1,74 @@
+---
+comments: true
+---
+
+# Restrict monitored namespaces
+
+This page discusses how to restrict the namespaces
+where the Keptn
+[lifecycle-operator](../../components/lifecycle-operator/index.md)
+orchestrates the deployments.
+
+For information about how to allocate Keptn resources
+across namespaces, see
+[Namespaces and resources](namespace-resources.md).
+
+## Default behavior
+
+Keptn must be installed on its own namespace
+that does not run any other components,
+especially any application deployment.
+
+By default, Keptn lifecycle orchestration is enabled
+for all namespaces except the followings:
+
+- `kube-system`
+- `kube-public`
+- `kube-node-lease`
+- `cert-manager`
+- `keptn-system` (Keptn installation namespace)
+- `observability`
+- `monitoring`
+
+## Custom namespace restriction
+
+If you want to restrict Keptn to only some namespaces, you should:
+
+- Allow those namespaces during installation
+- Annotate those namespaces
+
+To implement this:
+
+1. Create a `values.yaml` file
+   that lists the namespaces Keptn lifecycle orchestration should monitor:
+
+      ```yaml
+      lifecycleOperator:
+        allowedNamespaces:
+        - allowed-ns-1
+        - allowed-ns-2
+      ```
+
+1. Add the values file to the helm installation command:
+
+      ```shell
+      helm repo add keptn https://charts.lifecycle.keptn.sh
+      helm repo update
+      helm upgrade --install keptn keptn/keptn -n keptn-system \
+           --values values.yaml --create-namespace --wait
+      ```
+
+1. Annotate the namespaces where Keptn lifecycle orchestration is allowed
+   by issuing the following command
+   for each namespace:
+
+      ```shell
+      kubectl annotate ns <your-allowed-namespace> \
+            keptn.sh/lifecycle-toolkit='enabled'
+      ```
+
+> **Note**
+Restricted allowed namespaces are configured at installation time.
+To add or remove Keptn allowed namespaces,
+you must modify the list of namespaces in your `values.yaml` file
+and rerun the `helm upgrade` command.

docs/docs/installation/configuration/namespace-resources.md

@@ -0,0 +1,87 @@
+---
+comments: true
+---
+
+# Allocate namespaces for Keptn resources
+
+Keptn primarily operates on Kubernetes
+[Workload](https://kubernetes.io/docs/concepts/workloads/)
+resources and
+[KeptnApp](../../reference/crd-reference/app.md)
+resources that are activated and defined by annotations to each workload.
+You have significant flexibility to decide how many namespaces to use
+and where to locate each resource.
+See the Kubernetes
+[Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
+documentation for some basic information.
+You can also search and find many "Best Practices for Namespaces"
+documents published on the web.
+
+Possible namespace designs for Keptn run the gamut:
+
+* Run all your Keptn work in a single namespace
+* Create a separate namespace for each logical grouping of your Keptn work
+* Create a separate namespace for each [workload](https://kubernetes.io/docs/concepts/workloads/)
+
+This page summarizes some namespace considerations
+for some Keptn resources.
+For information about limiting the namespaces where Keptn is allowed, see
+[Namespaces and Keptn](namespace-keptn.md).
+
+## KeptnMetric resources
+
+[KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md)
+resources need to be located
+in the same namespace as the associated
+[KeptnMetric](../../reference/crd-reference/metric.md)
+resources.
+But
+[KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
+resources that are used for pre- and post-deployment
+can reference metrics from any namespace.
+So you can create `KeptnMetrics` resources in a centralized namespace
+(such as `keptn-system`)
+and access those metrics in evaluations on all namespaces in the cluster.
+
+## Analysis related resources
+
+Analysis related resources
+([Analysis](../../reference/crd-reference/analysis.md),
+[AnalysisDefinition](../../reference/crd-reference/analysisdefinition.md),
+and
+[AnalysisValueTemplate](../../reference/crd-reference/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.
+
+## KeptnApp resources
+
+Each `KeptnApp` resource identifies the namespace to which it belongs.
+If you configure multiple namespaces,
+you can have `KeptnApp` resources with the same name
+in multiple namespaces without having them conflict.
+
+You do not need separate namespaces for separate versions of your application.
+The `KeptnApp` resource includes fields to define
+the `version` as well as a `revision`
+(used if you have to rerun a deployment
+but want to retain the version number).

docs/docs/installation/index.md

@@ -8,6 +8,12 @@ Keptn must be installed onto each Kubernetes cluster you want to monitor.
 Additionally, Keptn needs to be enabled on your namespaces.
 This gives you flexibility in how and where you want to use Keptn.
 
+> **Note** By default, Keptn monitors all namespaces in the cluster
+> except for those reserved for major components.
+> See
+> [Namespaces and Keptn](configuration/namespace-keptn.md)
+> to learn how to limit the namespaces that Keptn monitors.
+
 Keptn is installed using [Helm](https://helm.sh/).
 
 After you install Keptn, you are ready to

mkdocs.yml

@@ -120,7 +120,8 @@ nav:
           - Upgrade: docs/installation/upgrade.md
           - Configuration:
               - docs/installation/configuration/index.md
-              - How to structure your namespaces: docs/installation/configuration/namespace.md
+              - Restricting monitored namespaces: docs/installation/configuration/namespace-keptn.md
+              - Allocating namespaces for Keptn resources: docs/installation/configuration/namespace-resources.md
               - vCluster installation: docs/installation/configuration/vcluster.md
               - Keptn + cert-manager.io: docs/installation/configuration/cert-manager.md
               - Deploy Keptn via ArgoCD: docs/installation/configuration/argocd.md