From e08eee030fd379fa7253e99626c314d021b1eacd Mon Sep 17 00:00:00 2001 From: Andreas Geissler Date: Fri, 21 Apr 2023 14:21:37 +0200 Subject: [DOC] Update London OOM documentation Add information: - new Deployment options (Production, Development) - move Istio deployment to base installation - add Gateway-API and Keycloak Installation instructions - split and rename of a few files for updated structure - changed rst section formatting as suggested in sphinx rtd theme - add London Release Notes Issue-ID: OOM-3159 Signed-off-by: Andreas Geissler Change-Id: I98b8541d51daba982fd6c8be0c85fae676d53c13 --- docs/conf.py | 2 + docs/index.rst | 2 +- .../guides/infra_guides/oom_base_config_setup.rst | 191 ----------- .../infra_guides/oom_base_optional_addons.rst | 228 ------------- docs/sections/guides/infra_guides/oom_infra.rst | 34 ++ .../infra_guides/oom_infra_base_config_setup.rst | 373 +++++++++++++++++++++ .../infra_guides/oom_infra_deployment_options.rst | 40 +++ .../oom_infra_deployment_requirements.rst | 72 ++++ .../oom_infra_ingres_controller_setup.rst | 178 ++++++++++ .../infra_guides/oom_infra_optional_addons.rst | 144 ++++++++ .../guides/infra_guides/oom_infra_setup.rst | 81 ----- .../infra_guides/oom_setup_ingress_controller.rst | 176 ---------- docs/sections/oom_project_description.rst | 2 +- docs/sections/release_notes/release-notes-kohn.rst | 128 +++++++ docs/sections/release_notes/release-notes.rst | 50 ++- docs/sections/resources/yaml/istiod.yaml | 21 ++ .../resources/yaml/keycloak-db-values.yaml | 7 + .../resources/yaml/keycloak-server-values.yaml | 53 +++ docs/spelling_wordlist.txt | 0 kubernetes/onap/Chart.yaml | 2 +- 20 files changed, 1088 insertions(+), 696 deletions(-) delete mode 100644 docs/sections/guides/infra_guides/oom_base_config_setup.rst delete mode 100644 docs/sections/guides/infra_guides/oom_base_optional_addons.rst create mode 100644 docs/sections/guides/infra_guides/oom_infra.rst create mode 100644 docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst create mode 100644 docs/sections/guides/infra_guides/oom_infra_deployment_options.rst create mode 100644 docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst create mode 100644 docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst create mode 100644 docs/sections/guides/infra_guides/oom_infra_optional_addons.rst delete mode 100644 docs/sections/guides/infra_guides/oom_infra_setup.rst delete mode 100644 docs/sections/guides/infra_guides/oom_setup_ingress_controller.rst create mode 100644 docs/sections/release_notes/release-notes-kohn.rst create mode 100644 docs/sections/resources/yaml/istiod.yaml create mode 100644 docs/sections/resources/yaml/keycloak-db-values.yaml create mode 100644 docs/sections/resources/yaml/keycloak-server-values.yaml create mode 100644 docs/spelling_wordlist.txt diff --git a/docs/conf.py b/docs/conf.py index 29c57e6da0..c77ad2579c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,5 +55,7 @@ def setup(app): linkcheck_ignore = [ "https://istio-release.storage.googleapis.com/charts", + "https://charts.bitnami.com/bitnami", + "https://codecentric.github.io/helm-charts", r'http://localhost:\d+/' ] diff --git a/docs/index.rst b/docs/index.rst index 7a1d52b2ff..e889e0664c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ OOM Documentation Repository sections/oom_project_description.rst sections/guides/development_guides/oom_development.rst - sections/guides/infra_guides/oom_infra_setup.rst + sections/guides/infra_guides/oom_infra.rst sections/guides/deployment_guides/oom_deployment.rst sections/guides/user_guides/oom_user_guide.rst sections/guides/access_guides/oom_access_info.rst diff --git a/docs/sections/guides/infra_guides/oom_base_config_setup.rst b/docs/sections/guides/infra_guides/oom_base_config_setup.rst deleted file mode 100644 index 81f6bb4f82..0000000000 --- a/docs/sections/guides/infra_guides/oom_base_config_setup.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2022 Nordix Foundation - -.. Links -.. _HELM Best Practices Guide: https://docs.helm.sh/chart_best_practices/#requirements -.. _helm installation guide: https://helm.sh/docs/intro/install/ -.. _kubectl installation guide: https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/ -.. _Curated applications for Kubernetes: https://github.com/kubernetes/charts -.. _Cert-Manager Installation documentation: https://cert-manager.io/docs/installation/kubernetes/ -.. _Cert-Manager kubectl plugin documentation: https://cert-manager.io/docs/usage/kubectl-plugin/ -.. _Strimzi Apache Kafka Operator helm Installation documentation: https://strimzi.io/docs/operators/in-development/deploying.html#deploying-cluster-operator-helm-chart-str - -.. _oom_base_setup_guide: - -OOM Base Platform -################# - -As part of the initial base setup of the host Kubernetes cluster, -the following mandatory installation and configuration steps must be completed. - -.. contents:: - :backlinks: top - :depth: 1 - :local: -.. - -For additional platform add-ons, see the :ref:`oom_base_optional_addons` section. - -Install & configure kubectl -*************************** -The Kubernetes command line interface used to manage a Kubernetes cluster needs to be installed -and configured to run as non root. - -For additional information regarding kubectl installation and configuration see the `kubectl installation guide`_ - -To install kubectl, execute the following, replacing the with the version defined -in the :ref:`versions_table` table:: - - > curl -LO https://dl.k8s.io/release/v/bin/linux/amd64/kubectl - - > chmod +x ./kubectl - - > sudo mv ./kubectl /usr/local/bin/kubectl - - > mkdir ~/.kube - - > cp kube_config_cluster.yml ~/.kube/config.onap - - > export KUBECONFIG=~/.kube/config.onap - - > kubectl config use-context onap - -Validate the installation:: - - > kubectl get nodes - -:: - - NAME STATUS ROLES AGE VERSION - onap-control-1 Ready controlplane,etcd 3h53m v1.23.8 - onap-control-2 Ready controlplane,etcd 3h53m v1.23.8 - onap-k8s-1 Ready worker 3h53m v1.23.8 - onap-k8s-2 Ready worker 3h53m v1.23.8 - onap-k8s-3 Ready worker 3h53m v1.23.8 - onap-k8s-4 Ready worker 3h53m v1.23.8 - onap-k8s-5 Ready worker 3h53m v1.23.8 - onap-k8s-6 Ready worker 3h53m v1.23.8 - - -Install & configure helm -************************ -Helm is used for package and configuration management of the relevant helm charts. -For additional information, see the `helm installation guide`_ - -To install helm, execute the following, replacing the with the version defined -in the :ref:`versions_table` table:: - - > wget https://get.helm.sh/helm-v-linux-amd64.tar.gz - - > tar -zxvf helm-v-linux-amd64.tar.gz - - > sudo mv linux-amd64/helm /usr/local/bin/helm - -Verify the helm version with:: - - > helm version - -Helm's default CNCF provided `Curated applications for Kubernetes`_ repository called -*stable* can be removed to avoid confusion:: - - > helm repo remove stable - -Install the additional OOM plugins required to un/deploy the OOM helm charts:: - - > git clone http://gerrit.onap.org/r/oom - - > helm plugin install ~/oom/kubernetes/helm/plugins/deploy - - > helm plugin install ~/oom/kubernetes/helm/plugins/undeploy - -Verify the plugins are installed:: - - > helm plugin ls - -:: - - NAME VERSION DESCRIPTION - deploy 1.0.0 install (upgrade if release exists) parent charty and all subcharts as separate but related releases - undeploy 1.0.0 delete parent chart and subcharts that were deployed as separate releases - - -Install the strimzi kafka operator -********************************** -Strimzi Apache Kafka provides a way to run an Apache Kafka cluster on Kubernetes -in various deployment configurations by using kubernetes operators. -Operators are a method of packaging, deploying, and managing Kubernetes applications. - -Strimzi Operators extend the Kubernetes functionality, automating common -and complex tasks related to a Kafka deployment. By implementing -knowledge of Kafka operations in code, the Kafka administration -tasks are simplified and require less manual intervention. - -The Strimzi cluster operator is deployed using helm to install the parent chart -containing all of the required custom resource definitions. This should be done -by a kubernetes administrator to allow for deployment of custom resources in to -any kubernetes namespace within the cluster. - -Full installation instructions can be found in the -`Strimzi Apache Kafka Operator helm Installation documentation`_. - -To add the required helm repository, execute the following:: - - > helm repo add strimzi https://strimzi.io/charts/ - -To install the strimzi kafka operator, execute the following, replacing the with the version defined -in the :ref:`versions_table` table:: - - > helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version --set watchAnyNamespace=true --create-namespace - -Verify the installation:: - - > kubectl get po -n strimzi-system - -:: - - NAME READY STATUS RESTARTS AGE - strimzi-cluster-operator-7f7d6b46cf-mnpjr 1/1 Running 0 2m - - -.. _oom_base_setup_cert_manager: - -Install Cert-Manager -******************** - -Cert-Manager is a native Kubernetes certificate management controller. -It can help with issuing certificates from a variety of sources, such as -Let’s Encrypt, HashiCorp Vault, Venafi, a simple signing key pair, self -signed or external issuers. It ensures certificates are valid and up to -date, and attempt to renew certificates at a configured time before expiry. - -Cert-Manager is deployed using regular YAML manifests which include all -the needed resources (the CustomResourceDefinitions, cert-manager, -namespace, and the webhook component). - -Full installation instructions, including details on how to configure extra -functionality in Cert-Manager can be found in the -`Cert-Manager Installation documentation`_. - -There is also a kubectl plugin (kubectl cert-manager) that can help you -to manage cert-manager resources inside your cluster. For installation -steps, please refer to `Cert-Manager kubectl plugin documentation`_. - - -To install cert-manager, execute the following, replacing the with the version defined -in the :ref:`versions_table` table:: - - > kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v/cert-manager.yaml - -Verify the installation:: - - > kubectl get po -n cert-manager - -:: - - NAME READY STATUS RESTARTS AGE - cert-manager-776c4cfcb6-vgnpw 1/1 Running 0 2m - cert-manager-cainjector-7d9668978d-hdxf7 1/1 Running 0 2m - cert-manager-webhook-66c8f6c75-dxmtz 1/1 Running 0 2m - diff --git a/docs/sections/guides/infra_guides/oom_base_optional_addons.rst b/docs/sections/guides/infra_guides/oom_base_optional_addons.rst deleted file mode 100644 index 713aec6c8c..0000000000 --- a/docs/sections/guides/infra_guides/oom_base_optional_addons.rst +++ /dev/null @@ -1,228 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2022 Nordix Foundation - -.. Links -.. _Prometheus stack README: https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#readme -.. _ONAP Next Generation Security & Logging Structure: https://wiki.onap.org/pages/viewpage.action?pageId=103417456 -.. _Istio setup guide: https://istio.io/latest/docs/setup/install/helm/ -.. _Kiali setup guide: https://kiali.io/docs/installation/installation-guide/example-install/ -.. _Kserve setup guide: https://kserve.github.io/website/0.10/admin/kubernetes_deployment/ - -.. _oom_base_optional_addons: - -OOM Optional Addons -################### - -The following optional applications can be added to your kubernetes environment. - -Install Prometheus Stack -************************ - -Prometheus is an open-source systems monitoring and alerting toolkit with -an active ecosystem. - -Kube Prometheus Stack is a collection of Kubernetes manifests, Grafana -dashboards, and Prometheus rules combined with documentation and scripts to -provide easy to operate end-to-end Kubernetes cluster monitoring with -Prometheus using the Prometheus Operator. As it includes both Prometheus -Operator and Grafana dashboards, there is no need to set up them separately. -See the `Prometheus stack README`_ for more information. - -To install the prometheus stack, execute the following: - -- Add the prometheus-community Helm repository:: - - > helm repo add prometheus-community https://prometheus-community.github.io/helm-charts - -- Update your local Helm chart repository cache:: - - > helm repo update - -- To install prometheus, execute the following, replacing the with the version defined in the :ref:`versions_table` table:: - - > helm install prometheus prometheus-community/kube-prometheus-stack --namespace=prometheus --create-namespace --version= - -ONAP on Service Mesh -******************** - -.. warning:: - "ONAP on Service Mesh" is not fully supported in "Kohn". Full support is - planned for London release to support the - `ONAP Next Generation Security & Logging Structure`_ - -.. figure:: ../../resources/images/servicemesh/ServiceMesh.png - :align: center - -ONAP is currenty planned to support Istio as default ServiceMesh platform. -Therefor the following instructions describe the setup of Istio and required tools. -Used `Istio setup guide`_ - -.. _oom_base_optional_addons_istio_installation: - -Istio Platform Installation -=========================== - -Install Istio Basic Platform ----------------------------- - -- Configure the Helm repository:: - - > helm repo add istio https://istio-release.storage.googleapis.com/charts - - > helm repo update - -- Create a namespace for "mesh-level" configurations:: - - > kubectl create namespace istio-config - -- Create a namespace istio-system for Istio components:: - - > kubectl create namespace istio-system - -- Install the Istio Base chart which contains cluster-wide resources used by the - Istio control plane, replacing the with the version - defined in the :ref:`versions_table` table:: - - > helm upgrade -i istio-base istio/base -n istio-system --version - -- Install the Istio Base Istio Discovery chart which deploys the istiod service, replacing the - with the version defined in the :ref:`versions_table` table - (enable the variable to enforce the (sidecar) proxy startup before the container start):: - - > helm upgrade -i istiod istio/istiod -n istio-system --version - --wait --set global.proxy.holdApplicationUntilProxyStarts=true --set meshConfig.rootNamespace=istio-config - -Add an EnvoyFilter for HTTP header case ---------------------------------------- - -When handling HTTP/1.1, Envoy will normalize the header keys to be all lowercase. -While this is compliant with the HTTP/1.1 spec, in practice this can result in issues -when migrating existing systems that might rely on specific header casing. -In our case a problem was detected in the SDC client implementation, which relies on -uppercase header values. To solve this problem in general we add a EnvoyFilter to keep -the uppercase header in the istio-config namespace to apply for all namespaces, but -set the context to SIDECAR_INBOUND to avoid problems in the connection between Istio-Gateway and Services - -- Create a EnvoyFilter file (e.g. envoyfilter-case.yaml) - - .. collapse:: envoyfilter-case.yaml - - .. include:: ../../resources/yaml/envoyfilter-case.yaml - :code: yaml - -- Apply the change to Istio:: - - > kubectl apply -f envoyfilter-case.yaml - -Install Istio Gateway ---------------------- - -- Create a namespace istio-ingress for the Istio Ingress gateway - and enable istio-injection:: - - > kubectl create namespace istio-ingress - - > kubectl label namespace istio-ingress istio-injection=enabled - -- To expose additional ports besides HTTP/S (e.g. for external Kafka access, SDNC-callhome) - create an override file (e.g. istio-ingress.yaml) - - .. collapse:: istio-ingress.yaml - - .. include:: ../../resources/yaml/istio-ingress.yaml - :code: yaml - -- Install the Istio Gateway chart using the override file, replacing the - with the version defined in - the :ref:`versions_table` table:: - - > helm upgrade -i istio-ingress istio/gateway -n istio-ingress - --version -f ingress-istio.yaml --wait - -Kiali Installation -================== - -Kiali is used to visualize the Network traffic in a ServiceMesh enabled cluster -For setup the kiali operator is used, see `Kiali setup guide`_ - -- Install kiali-operator namespace:: - - > kubectl create namespace kiali-operator - - > kubectl label namespace kiali-operator istio-injection=enabled - -- Install the kiali-operator:: - - > helm repo add kiali https://kiali.org/helm-charts - - > helm repo update kiali - - > helm install --namespace kiali-operator kiali/kiali-operator - -- Create Kiali CR file (e.g. kiali.yaml) - - .. collapse:: kiali.yaml - - .. include:: ../../resources/yaml/kiali.yaml - :code: yaml - -- Install kiali:: - - > kubectl apply -f kiali.yaml - -- Create Ingress gateway entry for the kiali web interface - using the configured Ingress (here "simpledemo.onap.org") - as described in :ref:`oom_customize_overrides` - - .. collapse:: kiali-ingress.yaml - - .. include:: ../../resources/yaml/kiali-ingress.yaml - :code: yaml - -- Add the Ingress entry for Kiali:: - - > kubectl -n istio-system apply -f kiali-ingress.yaml - - -Jaeger Installation -=================== - -To be done... - - -Kserve Installation -******************** - -KServe is a standard Model Inference Platform on Kubernetes. It supports RawDeployment mode to enable InferenceService deployment with Kubernetes resources. Comparing to serverless deployment it unlocks Knative limitations such as mounting multiple volumes, on the other hand Scale down and from Zero is not supported in RawDeployment mode. - -This installation is necessary for the ML models to be deployed as inference service. Once deployed, the inference services can be queried for the prediction. - -**Kserve participant component in Policy ACM requires this installation. Kserve participant deploy/undeploy inference services in Kserve.** - -Dependent component version compatibility details and installation instructions can be found at `Kserve setup guide`_ - -Kserve installation requires the following components: - -- Istio. Its installation instructions can be found at :ref:`oom_base_optional_addons_istio_installation` - -- Cert-Manager. Its installation instructions can be found at :ref:`oom_base_setup_cert_manager` - -Installation instructions as follows, - -- Create kserve namespace:: - - > kubectl create namespace kserve - -- Install Kserve:: - - > kubectl apply -f https://github.com/kserve/kserve/releases/download/v/kserve.yaml - -- Install Kserve default serving runtimes:: - - > kubectl apply -f https://github.com/kserve/kserve/releases/download/v/kserve-runtimes.yaml - -- Patch ConfigMap inferenceservice-config as follows:: - - > kubectl patch configmap/inferenceservice-config -n kserve --type=strategic -p '{"data": {"deploy": "{\"defaultDeploymentMode\": \"RawDeployment\"}"}}' diff --git a/docs/sections/guides/infra_guides/oom_infra.rst b/docs/sections/guides/infra_guides/oom_infra.rst new file mode 100644 index 0000000000..ddc00b6115 --- /dev/null +++ b/docs/sections/guides/infra_guides/oom_infra.rst @@ -0,0 +1,34 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. Links +.. _Kubernetes: https://kubernetes.io/ + + +.. _oom_infra_guide: + +OOM Infrastructure Guide +======================== + +.. figure:: ../../resources/images/oom_logo/oomLogoV2-medium.png + :align: right + +OOM deploys and manages ONAP on a pre-established Kubernetes_ cluster - the +creation of this cluster is outside of the scope of the OOM project as there +are many options including public clouds with pre-established environments. +If creation of a Kubernetes cluster is required, the life-cycle of this +cluster is independent of the life-cycle of the ONAP components themselves. + +For more information about functionality and processes please refer to the +following documents: + +.. toctree:: + :maxdepth: 1 + + oom_infra_deployment_options.rst + oom_infra_deployment_requirements.rst + oom_infra_base_config_setup.rst + oom_infra_optional_addons.rst + oom_infra_ingres_controller_setup.rst diff --git a/docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst b/docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst new file mode 100644 index 0000000000..f27277ddc9 --- /dev/null +++ b/docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst @@ -0,0 +1,373 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. Links +.. _HELM Best Practices Guide: https://docs.helm.sh/chart_best_practices/#requirements +.. _helm installation guide: https://helm.sh/docs/intro/install/ +.. _kubectl installation guide: https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/ +.. _Curated applications for Kubernetes: https://github.com/kubernetes/charts +.. _Cert-Manager Installation documentation: https://cert-manager.io/docs/installation/kubernetes/ +.. _Cert-Manager kubectl plugin documentation: https://cert-manager.io/docs/usage/kubectl-plugin/ +.. _Strimzi Apache Kafka Operator helm Installation documentation: https://strimzi.io/docs/operators/in-development/deploying.html#deploying-cluster-operator-helm-chart-str +.. _ONAP Next Generation Security & Logging Structure: https://wiki.onap.org/pages/viewpage.action?pageId=103417456 +.. _Istio setup guide: https://istio.io/latest/docs/setup/install/helm/ +.. _Gateway-API: https://gateway-api.sigs.k8s.io/ +.. _Istio-Gateway: https://istio.io/latest/docs/reference/config/networking/gateway/ + +.. _oom_base_setup_guide: + +OOM Base Platform +================= + +As part of the initial base setup of the host Kubernetes cluster, +the following mandatory installation and configuration steps must be completed. + +.. contents:: + :backlinks: top + :depth: 1 + :local: +.. + +For additional platform add-ons, see the :ref:`oom_base_optional_addons` section. + +Install & configure kubectl +--------------------------- + +The Kubernetes command line interface used to manage a Kubernetes cluster needs to be installed +and configured to run as non root. + +For additional information regarding kubectl installation and configuration see the `kubectl installation guide`_ + +To install kubectl, execute the following, replacing the with the version defined +in the :ref:`versions_table` table:: + + > curl -LO https://dl.k8s.io/release/v/bin/linux/amd64/kubectl + + > chmod +x ./kubectl + + > sudo mv ./kubectl /usr/local/bin/kubectl + + > mkdir ~/.kube + + > cp kube_config_cluster.yml ~/.kube/config.onap + + > export KUBECONFIG=~/.kube/config.onap + + > kubectl config use-context onap + +Validate the installation:: + + > kubectl get nodes + +:: + + NAME STATUS ROLES AGE VERSION + onap-control-1 Ready controlplane,etcd 3h53m v1.23.8 + onap-control-2 Ready controlplane,etcd 3h53m v1.23.8 + onap-k8s-1 Ready worker 3h53m v1.23.8 + onap-k8s-2 Ready worker 3h53m v1.23.8 + onap-k8s-3 Ready worker 3h53m v1.23.8 + onap-k8s-4 Ready worker 3h53m v1.23.8 + onap-k8s-5 Ready worker 3h53m v1.23.8 + onap-k8s-6 Ready worker 3h53m v1.23.8 + + +Install & configure helm +------------------------ + +Helm is used for package and configuration management of the relevant helm charts. +For additional information, see the `helm installation guide`_ + +To install helm, execute the following, replacing the with the version defined +in the :ref:`versions_table` table:: + + > wget https://get.helm.sh/helm-v-linux-amd64.tar.gz + + > tar -zxvf helm-v-linux-amd64.tar.gz + + > sudo mv linux-amd64/helm /usr/local/bin/helm + +Verify the helm version with:: + + > helm version + +Helm's default CNCF provided `Curated applications for Kubernetes`_ repository called +*stable* can be removed to avoid confusion:: + + > helm repo remove stable + +Install the additional OOM plugins required to un/deploy the OOM helm charts:: + + > git clone http://gerrit.onap.org/r/oom + + > helm plugin install ~/oom/kubernetes/helm/plugins/deploy + + > helm plugin install ~/oom/kubernetes/helm/plugins/undeploy + +Verify the plugins are installed:: + + > helm plugin ls + +:: + + NAME VERSION DESCRIPTION + deploy 1.0.0 install (upgrade if release exists) parent chart and all subcharts as separate but related releases + undeploy 1.0.0 delete parent chart and subcharts that were deployed as separate releases + + +Install the Strimzi Kafka Operator +---------------------------------- + +Strimzi Apache Kafka provides a way to run an Apache Kafka cluster on Kubernetes +in various deployment configurations by using kubernetes operators. +Operators are a method of packaging, deploying, and managing Kubernetes applications. + +Strimzi Operators extend the Kubernetes functionality, automating common +and complex tasks related to a Kafka deployment. By implementing +knowledge of Kafka operations in code, the Kafka administration +tasks are simplified and require less manual intervention. + +The Strimzi cluster operator is deployed using helm to install the parent chart +containing all of the required custom resource definitions. This should be done +by a kubernetes administrator to allow for deployment of custom resources in to +any kubernetes namespace within the cluster. + +Full installation instructions can be found in the +`Strimzi Apache Kafka Operator helm Installation documentation`_. + +To add the required helm repository, execute the following:: + + > helm repo add strimzi https://strimzi.io/charts/ + +To install the strimzi kafka operator, execute the following, replacing the with the version defined +in the :ref:`versions_table` table:: + + > helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version --set watchAnyNamespace=true --create-namespace + +Verify the installation:: + + > kubectl get po -n strimzi-system + +:: + + NAME READY STATUS RESTARTS AGE + strimzi-cluster-operator-7f7d6b46cf-mnpjr 1/1 Running 0 2m + + +.. _oom_base_setup_cert_manager: + +Install Cert-Manager +-------------------- + +Cert-Manager is a native Kubernetes certificate management controller. +It can help with issuing certificates from a variety of sources, such as +Let’s Encrypt, HashiCorp Vault, Venafi, a simple signing key pair, self +signed or external issuers. It ensures certificates are valid and up to +date, and attempt to renew certificates at a configured time before expiry. + +Cert-Manager is deployed using regular YAML manifests which include all +the needed resources (the CustomResourceDefinitions, cert-manager, +namespace, and the webhook component). + +Full installation instructions, including details on how to configure extra +functionality in Cert-Manager can be found in the +`Cert-Manager Installation documentation`_. + +There is also a kubectl plugin (kubectl cert-manager) that can help you +to manage cert-manager resources inside your cluster. For installation +steps, please refer to `Cert-Manager kubectl plugin documentation`_. + + +To install cert-manager, execute the following, replacing the with the version defined +in the :ref:`versions_table` table:: + + > kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v/cert-manager.yaml + +Verify the installation:: + + > kubectl get po -n cert-manager + +:: + + NAME READY STATUS RESTARTS AGE + cert-manager-776c4cfcb6-vgnpw 1/1 Running 0 2m + cert-manager-cainjector-7d9668978d-hdxf7 1/1 Running 0 2m + cert-manager-webhook-66c8f6c75-dxmtz 1/1 Running 0 2m + +Istio Service Mesh +------------------ + +.. note:: + In London ONAP deployment supports the + `ONAP Next Generation Security & Logging Structure`_ + +ONAP is currenty supporting Istio as default ServiceMesh platform. +Therefor the following instructions describe the setup of Istio and required tools. +Used `Istio setup guide`_ + +.. _oom_base_optional_addons_istio_installation: + +Istio Platform Installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Install Istio Basic Platform +"""""""""""""""""""""""""""" + +- Configure the Helm repository:: + + > helm repo add istio https://istio-release.storage.googleapis.com/charts + + > helm repo update + +- Create a namespace for "mesh-level" configurations:: + + > kubectl create namespace istio-config + +- Create a namespace istio-system for Istio components:: + + > kubectl create namespace istio-system + +- Install the Istio Base chart which contains cluster-wide resources used by the + Istio control plane, replacing the with the version + defined in the :ref:`versions_table` table:: + + > helm upgrade -i istio-base istio/base -n istio-system --version + +- Create an override for istiod (e.g. istiod.yaml) to add the oauth2-proxy as external + authentication provider and apply some specific config settings + + .. collapse:: istiod.yaml + + .. include:: ../../resources/yaml/istiod.yaml + :code: yaml + +- Install the Istio Base Istio Discovery chart which deploys the istiod service, replacing the + with the version defined in the :ref:`versions_table` table:: + + > helm upgrade -i istiod istio/istiod -n istio-system --version + --wait -f ./istiod.yaml + +Add an EnvoyFilter for HTTP header case +""""""""""""""""""""""""""""""""""""""" + +When handling HTTP/1.1, Envoy will normalize the header keys to be all +lowercase. While this is compliant with the HTTP/1.1 spec, in practice this +can result in issues when migrating existing systems that might rely on +specific header casing. In our case a problem was detected in the SDC client +implementation, which relies on uppercase header values. To solve this problem +in general we add a EnvoyFilter to keep the uppercase header in the +istio-config namespace to apply for all namespaces, but set the context to +SIDECAR_INBOUND to avoid problems in the connection between Istio-Gateway and +Services + +- Create a EnvoyFilter file (e.g. envoyfilter-case.yaml) + + .. collapse:: envoyfilter-case.yaml + + .. include:: ../../resources/yaml/envoyfilter-case.yaml + :code: yaml + +- Apply the change to Istio:: + + > kubectl apply -f envoyfilter-case.yaml + + +Ingress Controller Installation +------------------------------- + +In the production setup 2 different Ingress setups are supported. + +- Istio Gateway `Istio-Gateway`_ (currently tested, but in the future deprecated) +- Gateway API `Gateway-API`_ (in Alpha status, but will be standard in the future) + +Depending on the solution, the ONAP helm values.yaml has to be configured. +See the :ref:`OOM customized deployment` section for more details. + +Istio Gateway +^^^^^^^^^^^^^ + +- Create a namespace istio-ingress for the Istio Ingress gateway + and enable istio-injection:: + + > kubectl create namespace istio-ingress + + > kubectl label namespace istio-ingress istio-injection=enabled + +- To expose additional ports besides HTTP/S (e.g. for external Kafka access, SDNC-callhome) + create an override file (e.g. istio-ingress.yaml) + + .. collapse:: istio-ingress.yaml + + .. include:: ../../resources/yaml/istio-ingress.yaml + :code: yaml + +- Install the Istio Gateway chart using the override file, replacing the + with the version defined in + the :ref:`versions_table` table:: + + > helm upgrade -i istio-ingress istio/gateway -n istio-ingress + --version -f ingress-istio.yaml --wait + + +Gateway-API +^^^^^^^^^^^ + +- Install the Gateway-API CRDs replacing the + with the version defined in + the :ref:`versions_table` table:: + + > kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download//experimental-install.yaml + +- Create a common Gateway instance + TBD + +Keycloak Installation +--------------------- + +- Add helm repositories + + > helm repo add bitnami https://charts.bitnami.com/bitnami + + > helm repo add codecentric https://codecentric.github.io/helm-charts + + > helm repo update + +- create keycloak namespace + + > kubectl create namespace keycloak + > kubectl label namespace keycloak istio-injection=enabled + +Install Keycloak-Database +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- To configure the Postgres DB + create an override file (e.g. keycloak-db-values.yaml) + + .. collapse:: keycloak-db-values.yaml + + .. include:: ../../resources/yaml/keycloak-db-values.yaml + :code: yaml + +- Install the Postgres DB + + > helm -n keycloak upgrade -i keycloak-db bitnami/postgresql --values ./keycloak-db-values.yaml + +Configure Keycloak +^^^^^^^^^^^^^^^^^^ + +- To configure the Keycloak instance + create an override file (e.g. keycloak-server-values.yaml) + + .. collapse:: keycloak-server-values.yaml + + .. include:: ../../resources/yaml/keycloak-server-values.yaml + :code: yaml + +- Install keycloak + + > helm -n keycloak upgrade -i keycloak codecentric/keycloak --values ./keycloak-server-values.yaml + +The required Ingress entry and REALM will be provided by the ONAP "Platform" +component. diff --git a/docs/sections/guides/infra_guides/oom_infra_deployment_options.rst b/docs/sections/guides/infra_guides/oom_infra_deployment_options.rst new file mode 100644 index 0000000000..dc206e0548 --- /dev/null +++ b/docs/sections/guides/infra_guides/oom_infra_deployment_options.rst @@ -0,0 +1,40 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. Links +.. _Kubernetes: https://kubernetes.io/ +.. _Kubernetes best practices: https://kubernetes.io/docs/setup/best-practices/cluster-large/ +.. _kubelet config guide: https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/ + + + +ONAP Deployment Options +======================= + +OOM supports 2 different deployment options of ONAP. + +- Development Setup +- Production Setup + +In the following sections describe the different setups. + +Development setup +----------------- + +The development setup deploys ONAP components exposing its external services +via NodePorts and without TLS termination and internal traffic encryption. + +Production setup +---------------- + +The production setup deploys ONAP components exposing its external services +via Ingress with TLS termination. +Internal traffic encryption will be ensured by using Istio ServiceMesh. + +.. figure:: ../../resources/images/servicemesh/ServiceMesh.png + :align: center + +For external access we start to establish Authentication via Oauth2-proxy +and Keycloak which will be completed in the coming release. diff --git a/docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst b/docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst new file mode 100644 index 0000000000..1b9db50fe0 --- /dev/null +++ b/docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst @@ -0,0 +1,72 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. Links +.. _Kubernetes: https://kubernetes.io/ +.. _Kubernetes best practices: https://kubernetes.io/docs/setup/best-practices/cluster-large/ +.. _kubelet config guide: https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/ + + + +ONAP Deployment Requirements +============================ + +.. rubric:: Minimum Hardware Configuration + +Some recommended hardware requirements are provided below. Note that this is for a +full ONAP deployment (all components). + +.. table:: OOM Hardware Requirements + + ===== ===== ====== ==================== + RAM HD vCores Ports + ===== ===== ====== ==================== + 224GB 160GB 112 0.0.0.0/0 (all open) + ===== ===== ====== ==================== + +Customizing ONAP to deploy only components that are needed will drastically reduce these requirements. +See the :ref:`OOM customized deployment` section for more details. + +.. note:: + | Kubernetes supports a maximum of 110 pods per node - this can be overcome by modifying your kubelet config. + | See the `kubelet config guide`_ for more information. + + | The use of many small nodes is preferred over a few larger nodes (for example 14 x 16GB - 8 vCores each). + + | OOM can be deployed on a private set of physical hosts or VMs (or even a combination of the two). + +.. rubric:: Software Requirements + +The versions of software that are supported by OOM are as follows: + +.. _versions_table: + +.. table:: OOM Software Requirements (base) + + ============== =========== ======= ======== ======== ============= ======== + Release Kubernetes Helm kubectl Docker Cert-Manager Strimzi + ============== =========== ======= ======== ======== ============= ======== + Jakarta 1.22.4 3.6.3 1.22.4 20.10.x 1.8.0 0.28.0 + Kohn 1.23.8 3.8.2 1.23.8 20.10.x 1.8.0 0.32.0 + London 1.23.8 3.8.2 1.23.x 20.10.x 1.11.1 0.35.0 + ============== =========== ======= ======== ======== ============= ======== + +.. table:: OOM Software Requirements (production) + + ============== ====== ============ ============== + Release Istio Gateway-API Keycloak + ============== ====== ============ ============== + London 1.17.2 v0.6.2 19.0.3-legacy + ============== ====== ============ ============== + +.. table:: OOM Software Requirements (optional) + + ============== ================= ========== + Release Prometheus Stack K8ssandra + ============== ================= ========== + Jakarta 35.x + Kohn 35.x + London 45.x 1.6.1 + ============== ================= ========== diff --git a/docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst b/docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst new file mode 100644 index 0000000000..1fb7baa53a --- /dev/null +++ b/docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst @@ -0,0 +1,178 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2020, Samsung Electronics +.. Modification copyright (C) 2022 Nordix Foundation + +.. Links +.. _metallb Metal Load Balancer installation: https://metallb.universe.tf/installation/ + +.. _oom_setup_ingress_controller: + +OOM Ingress controller setup +============================ + +.. warning:: + This guide should prob go in the Optional addons section + +This optional guide provides instruction how to setup experimental ingress controller +feature. For this, we are hosting our cluster on OpenStack VMs and using the +Rancher Kubernetes Engine (RKE) to deploy and manage our Kubernetes Cluster and +ingress controller + +.. contents:: + :backlinks: top + :depth: 1 + :local: +.. + +The result at the end of this tutorial will be: + +#. Customization of the cluster.yaml file for ingress controller support + +#. Installation and configuration test DNS server for ingress host resolution + on testing machines + +#. Installation and configuration MLB (Metal Load Balancer) required for + exposing ingress service + +#. Installation and configuration NGINX ingress controller + +#. Additional info how to deploy ONAP with services exposed via Ingress + controller + +Customize cluster.yml file +-------------------------- + +Before setup cluster for ingress purposes DNS cluster IP and ingress provider +should be configured and following: + +.. code-block:: yaml + + --- + <...> + restore: + restore: false + snapshot_name: "" + ingress: + provider: none + dns: + provider: coredns + upstreamnameservers: + - :31555 + +Where the should be set to the same IP as the CONTROLPANE +node. + +For external load balancer purposes, minimum one of the worker node should be +configured with external IP address accessible outside the cluster. It can be +done using the following example node configuration: + +.. code-block:: yaml + + --- + <...> + - address: + internal_address: + port: "22" + role: + - worker + hostname_override: "onap-worker-0" + user: ubuntu + ssh_key_path: "~/.ssh/id_rsa" + <...> + +Where the is external worker node IP address, and +is internal node IP address if it is required. + + +DNS server configuration and installation +----------------------------------------- + +DNS server deployed on the Kubernetes cluster makes it easy to use services +exposed through ingress controller because it resolves all subdomain related to +the ONAP cluster to the load balancer IP. Testing ONAP cluster requires a lot +of entries on the target machines in the /etc/hosts. Adding many entries into +the configuration files on testing machines is quite problematic and error +prone. The better wait is to create central DNS server with entries for all +virtual host pointed to simpledemo.onap.org and add custom DNS server as a +target DNS server for testing machines and/or as external DNS for Kubernetes +cluster. + +DNS server has automatic installation and configuration script, so installation +is quite easy:: + + > cd kubernetes/contrib/dns-server-for-vhost-ingress-testing + + > ./deploy\_dns.sh + +After DNS deploy you need to setup DNS entry on the target testing machine. +Because DNS listen on non standard port configuration require iptables rules +on the target machine. Please follow the configuration proposed by the deploy +scripts. +Example output depends on the IP address and example output looks like bellow:: + + DNS server already deployed: + 1. You can add the DNS server to the target machine using following commands: + sudo iptables -t nat -A OUTPUT -p tcp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555 + sudo iptables -t nat -A OUTPUT -p udp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555 + sudo sysctl -w net.ipv4.conf.all.route_localnet=1 + sudo sysctl -w net.ipv4.ip_forward=1 + 2. Update /etc/resolv.conf file with nameserver 192.168.211.211 entry on your target machine + + +MetalLB Load Balancer installation and configuration +---------------------------------------------------- + +By default pure Kubernetes cluster requires external load balancer if we want +to expose external port using LoadBalancer settings. For this purpose MetalLB +can be used. Before installing the MetalLB you need to ensure that at least one +worker has assigned IP accessible outside the cluster. + +MetalLB Load balancer can be easily installed using automatic install script:: + + > cd kubernetes/contrib/metallb-loadbalancer-inst + + > ./install-metallb-on-cluster.sh + + +Configuration of the Nginx ingress controller +--------------------------------------------- + +After installation of the DNS server and ingress controller, we can install and +configure ingress controller. +It can be done using the following commands:: + + > cd kubernetes/contrib/ingress-nginx-post-inst + + > kubectl apply -f nginx_ingress_cluster_config.yaml + + > kubectl apply -f nginx_ingress_enable_optional_load_balacer_service.yaml + +After deploying the NGINX ingress controller, you can ensure that the ingress port is +exposed as load balancer service with an external IP address:: + + > kubectl get svc -n ingress-nginx + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + default-http-backend ClusterIP 10.10.10.10 80/TCP 25h + ingress-nginx LoadBalancer 10.10.10.11 10.12.13.14 80:31308/TCP,443:30314/TCP 24h + + +ONAP with ingress exposed services +---------------------------------- + +If you want to deploy onap with services exposed through ingress controller you +can use full onap deploy yaml:: + + > onap/resources/overrides/onap-all-ingress-nginx-vhost.yaml + +Ingress also can be enabled on any onap setup override using following code: + +.. code-block:: yaml + + --- + <...> + global: + <...> + ingress: + enabled: true diff --git a/docs/sections/guides/infra_guides/oom_infra_optional_addons.rst b/docs/sections/guides/infra_guides/oom_infra_optional_addons.rst new file mode 100644 index 0000000000..8b15f6c7c2 --- /dev/null +++ b/docs/sections/guides/infra_guides/oom_infra_optional_addons.rst @@ -0,0 +1,144 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix Foundation + +.. Links +.. _Prometheus stack README: https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#readme +.. _ONAP Next Generation Security & Logging Structure: https://wiki.onap.org/pages/viewpage.action?pageId=103417456 +.. _Istio setup guide: https://istio.io/latest/docs/setup/install/helm/ +.. _Kiali setup guide: https://kiali.io/docs/installation/installation-guide/example-install/ +.. _Kserve setup guide: https://kserve.github.io/website/0.10/admin/kubernetes_deployment/ + +.. _oom_base_optional_addons: + +OOM Optional Addons +=================== + +The following optional applications can be added to your kubernetes +environment. + +Install Prometheus Stack +------------------------ + +Prometheus is an open-source systems monitoring and alerting toolkit with +an active ecosystem. + +Kube Prometheus Stack is a collection of Kubernetes manifests, Grafana +dashboards, and Prometheus rules combined with documentation and scripts to +provide easy to operate end-to-end Kubernetes cluster monitoring with +Prometheus using the Prometheus Operator. As it includes both Prometheus +Operator and Grafana dashboards, there is no need to set up them separately. +See the `Prometheus stack README`_ for more information. + +To install the prometheus stack, execute the following: + +- Add the prometheus-community Helm repository:: + + > helm repo add prometheus-community https://prometheus-community.github.io/helm-charts + +- Update your local Helm chart repository cache:: + + > helm repo update + +- To install prometheus, execute the following, replacing the with the version defined in the :ref:`versions_table` table:: + + > helm install prometheus prometheus-community/kube-prometheus-stack --namespace=prometheus --create-namespace --version= + + +Kiali Installation +------------------ + +Kiali is used to visualize the Network traffic in a ServiceMesh enabled cluster +For setup the kiali operator is used, see `Kiali setup guide`_ + +- Install kiali-operator namespace:: + + > kubectl create namespace kiali-operator + + > kubectl label namespace kiali-operator istio-injection=enabled + +- Install the kiali-operator:: + + > helm repo add kiali https://kiali.org/helm-charts + + > helm repo update kiali + + > helm install --namespace kiali-operator kiali/kiali-operator + +- Create Kiali CR file (e.g. kiali.yaml) + + .. collapse:: kiali.yaml + + .. include:: ../../resources/yaml/kiali.yaml + :code: yaml + +- Install kiali:: + + > kubectl apply -f kiali.yaml + +- Create Ingress gateway entry for the kiali web interface + using the configured Ingress (here "simpledemo.onap.org") + as described in :ref:`oom_customize_overrides` + + .. collapse:: kiali-ingress.yaml + + .. include:: ../../resources/yaml/kiali-ingress.yaml + :code: yaml + +- Add the Ingress entry for Kiali:: + + > kubectl -n istio-system apply -f kiali-ingress.yaml + + +Jaeger Installation +------------------- + +To be done... + +K8ssandra-Operator Installation +------------------------------- + +To be done... + +Kserve Installation +------------------- + +KServe is a standard Model Inference Platform on Kubernetes. It supports +RawDeployment mode to enable InferenceService deployment with Kubernetes +resources. Comparing to serverless deployment it unlocks Knative limitations +such as mounting multiple volumes, on the other hand Scale down and from Zero +is not supported in RawDeployment mode. + +This installation is necessary for the ML models to be deployed as inference +service. Once deployed, the inference services can be queried for the +prediction. + +**Kserve participant component in Policy ACM requires this installation. Kserve participant deploy/undeploy inference services in Kserve.** + +Dependent component version compatibility details and installation instructions +can be found at `Kserve setup guide`_ + +Kserve installation requires the following components: + +- Istio. Its installation instructions can be found at :ref:`oom_base_optional_addons_istio_installation` + +- Cert-Manager. Its installation instructions can be found at :ref:`oom_base_setup_cert_manager` + +Installation instructions as follows, + +- Create kserve namespace:: + + > kubectl create namespace kserve + +- Install Kserve:: + + > kubectl apply -f https://github.com/kserve/kserve/releases/download/v/kserve.yaml + +- Install Kserve default serving runtimes:: + + > kubectl apply -f https://github.com/kserve/kserve/releases/download/v/kserve-runtimes.yaml + +- Patch ConfigMap inferenceservice-config as follows:: + + > kubectl patch configmap/inferenceservice-config -n kserve --type=strategic -p '{"data": {"deploy": "{\"defaultDeploymentMode\": \"RawDeployment\"}"}}' diff --git a/docs/sections/guides/infra_guides/oom_infra_setup.rst b/docs/sections/guides/infra_guides/oom_infra_setup.rst deleted file mode 100644 index ed7b05a103..0000000000 --- a/docs/sections/guides/infra_guides/oom_infra_setup.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2022 Nordix Foundation - -.. Links -.. _Kubernetes: https://kubernetes.io/ -.. _Kubernetes best practices: https://kubernetes.io/docs/setup/best-practices/cluster-large/ -.. _kubelet confg guide: https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/ - -.. _oom_infra_setup_guide: - -OOM Infrastructure Guide -######################## - -.. figure:: ../../resources/images/oom_logo/oomLogoV2-medium.png - :align: right - -OOM deploys and manages ONAP on a pre-established Kubernetes_ cluster - the -creation of this cluster is outside of the scope of the OOM project as there -are many options including public clouds with pre-established environments. -If creation of a Kubernetes cluster is required, the life-cycle of this -cluster is independent of the life-cycle of the ONAP components themselves. - -.. rubric:: Minimum Hardware Configuration - -Some recommended hardware requirements are provided below. Note that this is for a -full ONAP deployment (all components). - -.. table:: OOM Hardware Requirements - - ===== ===== ====== ==================== - RAM HD vCores Ports - ===== ===== ====== ==================== - 224GB 160GB 112 0.0.0.0/0 (all open) - ===== ===== ====== ==================== - -Customizing ONAP to deploy only components that are needed will drastically reduce these requirements. -See the :ref:`OOM customized deployment` section for more details. - -.. note:: - | Kubernetes supports a maximum of 110 pods per node - this can be overcome by modifying your kubelet config. - | See the `kubelet confg guide`_ for more information. - - | The use of many small nodes is preferred over a few larger nodes (for example 14 x 16GB - 8 vCores each). - - | OOM can be deployed on a private set of physical hosts or VMs (or even a combination of the two). - -.. rubric:: Software Requirements - -The versions of software that are supported by OOM are as follows: - -.. _versions_table: - -.. table:: OOM Software Requirements (base) - - ============== =========== ======= ======== ======== ============ ======= - Release Kubernetes Helm kubectl Docker Cert-Manager Strimzi - ============== =========== ======= ======== ======== ============ ======= - Jakarta 1.22.4 3.6.3 1.22.4 20.10.x 1.8.0 0.28.0 - Kohn 1.23.8 3.8.2 1.23.8 20.10.x 1.8.0 0.32.0 - ============== =========== ======= ======== ======== ============ ======= - -.. table:: OOM Software Requirements (optional) - - ============== ================= ====== - Release Prometheus Stack Istio - ============== ================= ====== - Jakarta 35.x --- - Kohn 35.x 1.15.1 - ============== ================= ====== - - -.. toctree:: - :hidden: - - oom_base_config_setup.rst - oom_base_optional_addons.rst - oom_setup_ingress_controller.rst - - diff --git a/docs/sections/guides/infra_guides/oom_setup_ingress_controller.rst b/docs/sections/guides/infra_guides/oom_setup_ingress_controller.rst deleted file mode 100644 index 8c261fdfd7..0000000000 --- a/docs/sections/guides/infra_guides/oom_setup_ingress_controller.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2020, Samsung Electronics -.. Modification copyright (C) 2022 Nordix Foundation - -.. Links -.. _metallb Metal Load Balancer installation: https://metallb.universe.tf/installation/ - -.. _oom_setup_ingress_controller: - -OOM Ingress controller setup -############################ - -.. warning:: - This guide should prob go in the Optional addons section - -This optional guide provides instruction how to setup experimental ingress controller -feature. For this, we are hosting our cluster on OpenStack VMs and using the -Rancher Kubernetes Engine (RKE) to deploy and manage our Kubernetes Cluster and -ingress controller - -.. contents:: - :backlinks: top - :depth: 1 - :local: -.. - -The result at the end of this tutorial will be: - -#. Customization of the cluster.yaml file for ingress controller support - -#. Installation and configuration test DNS server for ingress host resolution - on testing machines - -#. Installation and configuration MLB (Metal Load Balancer) required for - exposing ingress service - -#. Installation and configuration NGINX ingress controller - -#. Additional info how to deploy ONAP with services exposed via Ingress - controller - -Customize cluster.yml file -************************** -Before setup cluster for ingress purposes DNS cluster IP and ingress provider -should be configured and following: - -.. code-block:: yaml - - --- - <...> - restore: - restore: false - snapshot_name: "" - ingress: - provider: none - dns: - provider: coredns - upstreamnameservers: - - :31555 - -Where the should be set to the same IP as the CONTROLPANE -node. - -For external load balancer purposes, minimum one of the worker node should be -configured with external IP address accessible outside the cluster. It can be -done using the following example node configuration: - -.. code-block:: yaml - - --- - <...> - - address: - internal_address: - port: "22" - role: - - worker - hostname_override: "onap-worker-0" - user: ubuntu - ssh_key_path: "~/.ssh/id_rsa" - <...> - -Where the is external worker node IP address, and -is internal node IP address if it is required. - - -DNS server configuration and installation -***************************************** -DNS server deployed on the Kubernetes cluster makes it easy to use services -exposed through ingress controller because it resolves all subdomain related to -the ONAP cluster to the load balancer IP. Testing ONAP cluster requires a lot -of entries on the target machines in the /etc/hosts. Adding many entries into -the configuration files on testing machines is quite problematic and error -prone. The better wait is to create central DNS server with entries for all -virtual host pointed to simpledemo.onap.org and add custom DNS server as a -target DNS server for testing machines and/or as external DNS for Kubernetes -cluster. - -DNS server has automatic installation and configuration script, so installation -is quite easy:: - - > cd kubernetes/contrib/dns-server-for-vhost-ingress-testing - - > ./deploy\_dns.sh - -After DNS deploy you need to setup DNS entry on the target testing machine. -Because DNS listen on non standard port configuration require iptables rules -on the target machine. Please follow the configuration proposed by the deploy -scripts. -Example output depends on the IP address and example output looks like bellow:: - - DNS server already deployed: - 1. You can add the DNS server to the target machine using following commands: - sudo iptables -t nat -A OUTPUT -p tcp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555 - sudo iptables -t nat -A OUTPUT -p udp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555 - sudo sysctl -w net.ipv4.conf.all.route_localnet=1 - sudo sysctl -w net.ipv4.ip_forward=1 - 2. Update /etc/resolv.conf file with nameserver 192.168.211.211 entry on your target machine - - -MetalLB Load Balancer installation and configuration -**************************************************** - -By default pure Kubernetes cluster requires external load balancer if we want -to expose external port using LoadBalancer settings. For this purpose MetalLB -can be used. Before installing the MetalLB you need to ensure that at least one -worker has assigned IP accessible outside the cluster. - -MetalLB Load balancer can be easily installed using automatic install script:: - - > cd kubernetes/contrib/metallb-loadbalancer-inst - - > ./install-metallb-on-cluster.sh - - -Configuration of the Nginx ingress controller -********************************************* - -After installation of the DNS server and ingress controller, we can install and -configure ingress controller. -It can be done using the following commands:: - - > cd kubernetes/contrib/ingress-nginx-post-inst - - > kubectl apply -f nginx_ingress_cluster_config.yaml - - > kubectl apply -f nginx_ingress_enable_optional_load_balacer_service.yaml - -After deploying the NGINX ingress controller, you can ensure that the ingress port is -exposed as load balancer service with an external IP address:: - - > kubectl get svc -n ingress-nginx - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - default-http-backend ClusterIP 10.10.10.10 80/TCP 25h - ingress-nginx LoadBalancer 10.10.10.11 10.12.13.14 80:31308/TCP,443:30314/TCP 24h - - -ONAP with ingress exposed services -********************************** -If you want to deploy onap with services exposed through ingress controller you -can use full onap deploy yaml:: - - > onap/resources/overrides/onap-all-ingress-nginx-vhost.yaml - -Ingress also can be enabled on any onap setup override using following code: - -.. code-block:: yaml - - --- - <...> - global: - <...> - ingress: - enabled: true - diff --git a/docs/sections/oom_project_description.rst b/docs/sections/oom_project_description.rst index 404a410931..71af2d426b 100644 --- a/docs/sections/oom_project_description.rst +++ b/docs/sections/oom_project_description.rst @@ -46,7 +46,7 @@ The OOM documentation is broken into four different areas each targeted at a different user: - :ref:`oom_dev_guide` - a guide for developers of OOM -- :ref:`oom_infra_setup_guide` - a guide for those setting up the environments that OOM will use +- :ref:`oom_infra_guide` - a guide for those setting up the environments that OOM will use - :ref:`oom_deploy_guide` - a guide for those deploying OOM on an existing cloud - :ref:`oom_user_guide` - a guide for operators of an OOM instance - :ref:`oom_access_info_guide` - a guide for operators who require access to OOM applications diff --git a/docs/sections/release_notes/release-notes-kohn.rst b/docs/sections/release_notes/release-notes-kohn.rst new file mode 100644 index 0000000000..66d04628c1 --- /dev/null +++ b/docs/sections/release_notes/release-notes-kohn.rst @@ -0,0 +1,128 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 + International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) ONAP Project and its contributors +.. _release_notes_kohn: + +:orphan: + +************************************* +ONAP Operations Manager Release Notes +************************************* + +Previous Release Notes +====================== + +- :ref:`Jakarta ` +- :ref:`Istanbul ` +- :ref:`Honolulu ` +- :ref:`Guilin ` +- :ref:`Frankfurt ` +- :ref:`El Alto ` +- :ref:`Dublin ` +- :ref:`Casablanca ` +- :ref:`Beijing ` +- :ref:`Amsterdam ` + +Abstract +======== + +This document provides the release notes for the Kohn release. + +Summary +======= + + + +Release Data +============ + ++--------------------------------------+--------------------------------------+ +| **Project** | OOM | +| | | ++--------------------------------------+--------------------------------------+ +| **Docker images** | N/A | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | Kohn | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | 2022/12/05 | +| | | ++--------------------------------------+--------------------------------------+ + +New features +------------ + +* Kubernetes support for version up to 1.23.8 +* Helm support for version up to Helm: 3.8.2 +* Kubespray version used for automated deployment 2.19 (used for automated deployment) +* Initial Setup for "ONAP on ServiceMesh" deployment + + * using Istio 1.14.1 as SM platform + * including Istio Ingress Gateway for external access + * modify 90% of ONAP component charts to support SeviceMesh + +**Bug fixes** + +A list of issues resolved in this release can be found here: +https://jira.onap.org/projects/OOM/versions/11499 + + +**Known Issues** + + +Deliverables +------------ + +Software Deliverables +~~~~~~~~~~~~~~~~~~~~~ + +OOM provides `Helm charts `_ + +Documentation Deliverables +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- :ref:`Project Description ` - a guide for developers of OOM +- :ref:`oom_dev_guide` - a guide for developers of OOM +- :ref:`oom_infra_guide` - a guide for those setting up the environments that OOM will use +- :ref:`oom_deploy_guide` - a guide for those deploying OOM on an existing cloud +- :ref:`oom_user_guide` - a guide for operators of an OOM instance +- :ref:`oom_access_info_guide` - a guide for operators who require access to OOM applications + +Known Limitations, Issues and Workarounds +========================================= + +Known Vulnerabilities +--------------------- + +* Cassandra version needs to be updated to support new Python version + see `OOM-2900 `_ + +Workarounds +----------- + + +Security Notes +-------------- + +**Fixed Security Issues** + +* Fixed vulnerabilities for oom-platform-cert-service + see `Fixes `_ + +References +========== + +For more information on the ONAP Istanbul release, please see: + +#. `ONAP Home Page`_ +#. `ONAP Documentation`_ +#. `ONAP Release Downloads`_ +#. `ONAP Wiki Page`_ + + +.. _`ONAP Home Page`: https://www.onap.org +.. _`ONAP Wiki Page`: https://wiki.onap.org +.. _`ONAP Documentation`: https://docs.onap.org +.. _`ONAP Release Downloads`: https://git.onap.org diff --git a/docs/sections/release_notes/release-notes.rst b/docs/sections/release_notes/release-notes.rst index 501a37f637..ed8957bddf 100644 --- a/docs/sections/release_notes/release-notes.rst +++ b/docs/sections/release_notes/release-notes.rst @@ -11,6 +11,7 @@ ONAP Operations Manager Release Notes Previous Release Notes ====================== +- :ref:`Kohn ` - :ref:`Jakarta ` - :ref:`Istanbul ` - :ref:`Honolulu ` @@ -25,7 +26,7 @@ Previous Release Notes Abstract ======== -This document provides the release notes for the Kohn release. +This document provides the release notes for the London release. Summary ======= @@ -42,33 +43,51 @@ Release Data | **Docker images** | N/A | | | | +--------------------------------------+--------------------------------------+ -| **Release designation** | Kohn | +| **Release designation** | London | | | | +--------------------------------------+--------------------------------------+ -| **Release date** | 2022/12/05 | +| **Release date** | 2023/06/xx | | | | +--------------------------------------+--------------------------------------+ New features ------------ -* Kubernetes support for version up to 1.23.8 -* Helm support for version up to Helm: 3.8.2 -* Kubespray version used for automated deployment 2.19 (used for automated deployment) -* Initial Setup for "ONAP on ServiceMesh" deployment +* Introduction of "Production" ONAP setup, including: - * using Istio 1.14.1 as SM platform - * including Istio Ingress Gateway for external access - * modify 90% of ONAP component charts to support SeviceMesh + * Istio Service Mesh based deployment + * Ingress (Istio-Gateway) deployment and usage as standard external access method + * Internal Security provided by ServiceMesh and Component2Component AuthorizationPolicies + * External Security by introducing AuthN/Z using Keycloak and OAuth2Proxy for Ingress Access + +* Removal of unsupported components (AAF, Portal, Contrib,...) +* Update of Helmcharts to use common templates and practices +* Optional support for Cassandra 4.x using k8ssandra-operator + +* `REQ-1349 `_ Removal of AAF. + Internal communication encryption and authorization is offered by ServiceMesh + +* `REQ-1350 `_ All component must be + able to run without MSB. Component helm charts modified to use MSB optionally + and test the components during Daily and Gating with and without MSB + +* `REQ-1351 `_ External secure + communication only via Ingress. + Ingress resources created by templates and Ingress installation is described + in the OOM documents **Bug fixes** A list of issues resolved in this release can be found here: -https://jira.onap.org/projects/OOM/versions/11499 - +https://jira.onap.org/projects/OOM/versions/11500 **Known Issues** +* Components not working under ServiceMesh + + * CDS UI + * SO Monitor UI + * CLI Deliverables ------------ @@ -83,7 +102,7 @@ Documentation Deliverables - :ref:`Project Description ` - a guide for developers of OOM - :ref:`oom_dev_guide` - a guide for developers of OOM -- :ref:`oom_infra_setup_guide` - a guide for those setting up the environments that OOM will use +- :ref:`oom_infra_guide` - a guide for those setting up the environments that OOM will use - :ref:`oom_deploy_guide` - a guide for those deploying OOM on an existing cloud - :ref:`oom_user_guide` - a guide for operators of an OOM instance - :ref:`oom_access_info_guide` - a guide for operators who require access to OOM applications @@ -96,19 +115,16 @@ Known Vulnerabilities * Cassandra version needs to be updated to support new Python version see `OOM-2900 `_ + In London supported as option (using k8ssandra-operator), see :ref:`oom_base_optional_addons` Workarounds ----------- - Security Notes -------------- **Fixed Security Issues** -* Fixed vulnerabilities for oom-platform-cert-service - see `Fixes `_ - References ========== diff --git a/docs/sections/resources/yaml/istiod.yaml b/docs/sections/resources/yaml/istiod.yaml new file mode 100644 index 0000000000..47380125b8 --- /dev/null +++ b/docs/sections/resources/yaml/istiod.yaml @@ -0,0 +1,21 @@ +global: + proxy: + # Controls if sidecar is injected at the front of the container list and blocks the start of the other containers until the proxy is ready + holdApplicationUntilProxyStarts: true + #logging: + # level: "default:debug" +meshConfig: + rootNamespace: istio-config + extensionProviders: + - name: oauth2-proxy + envoyExtAuthzHttp: + service: oauth2-proxy.default.svc.cluster.local + port: 80 + timeout: 1.5s + includeHeadersInCheck: ["authorization", "cookie"] + headersToUpstreamOnAllow: ["x-forwarded-access-token", "authorization", "path", "x-auth-request-user", "x-auth-request-email", "x-auth-request-access-token"] + headersToDownstreamOnDeny: ["content-type", "set-cookie"] +pilot: + env: + PILOT_ENABLE_MYSQL_FILTER: true + PILOT_HTTP10: true \ No newline at end of file diff --git a/docs/sections/resources/yaml/keycloak-db-values.yaml b/docs/sections/resources/yaml/keycloak-db-values.yaml new file mode 100644 index 0000000000..ae1459bea7 --- /dev/null +++ b/docs/sections/resources/yaml/keycloak-db-values.yaml @@ -0,0 +1,7 @@ +# See https://github.com/bitnami/charts/tree/master/bitnami/postgresql +global: + postgresql: + auth: + username: dbusername + password: dbpassword + database: keycloak \ No newline at end of file diff --git a/docs/sections/resources/yaml/keycloak-server-values.yaml b/docs/sections/resources/yaml/keycloak-server-values.yaml new file mode 100644 index 0000000000..7eaecbedfc --- /dev/null +++ b/docs/sections/resources/yaml/keycloak-server-values.yaml @@ -0,0 +1,53 @@ +image: + # The Keycloak image repository + repository: quay.io/keycloak/keycloak + # Overrides the Keycloak image tag whose default is the chart appVersion + tag: "19.0.3-legacy" + +postgresql: + # If `true`, the Postgresql dependency is enabled + enabled: false + +extraEnv: | + - name: KEYCLOAK_USER + valueFrom: + secretKeyRef: + name: {{ include "keycloak.fullname" . }}-admin-creds + key: user + - name: KEYCLOAK_PASSWORD + valueFrom: + secretKeyRef: + name: {{ include "keycloak.fullname" . }}-admin-creds + key: password + - name: DB_VENDOR + value: postgres + - name: DB_ADDR + value: keycloak-db-postgresql + - name: DB_PORT + value: "5432" + - name: DB_DATABASE + value: keycloak + - name: DB_USER + value: dbusername + - name: DB_PASSWORD_FILE + value: /secrets/db-creds/password + - name: PROXY_ADDRESS_FORWARDING + value: "true" + +extraVolumeMounts: | + - name: db-creds + mountPath: /secrets/db-creds + readOnly: true + +extraVolumes: | + - name: db-creds + secret: + secretName: keycloak-db-postgresql + +secrets: + admin-creds: + annotations: + my-test-annotation: Test secret for {{ include "keycloak.fullname" . }} + stringData: + user: admin + password: secret \ No newline at end of file diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/kubernetes/onap/Chart.yaml b/kubernetes/onap/Chart.yaml index 23e2096fe2..6b66357a03 100644 --- a/kubernetes/onap/Chart.yaml +++ b/kubernetes/onap/Chart.yaml @@ -16,7 +16,7 @@ apiVersion: v2 name: onap version: 12.0.0 -appVersion: Kohn +appVersion: London description: Open Network Automation Platform (ONAP) home: https://www.onap.org/ sources: -- cgit 1.2.3-korg