diff options
Diffstat (limited to 'docs/sections/guides/infra_guides')
| -rw-r--r-- | docs/sections/guides/infra_guides/oom_infra.rst | 34 | ||||
| -rw-r--r-- | docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst (renamed from docs/sections/guides/infra_guides/oom_base_config_setup.rst) | 196 | ||||
| -rw-r--r-- | docs/sections/guides/infra_guides/oom_infra_deployment_options.rst | 40 | ||||
| -rw-r--r-- | docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst (renamed from docs/sections/guides/infra_guides/oom_infra_setup.rst) | 59 | ||||
| -rw-r--r-- | docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst (renamed from docs/sections/guides/infra_guides/oom_setup_ingress_controller.rst) | 16 | ||||
| -rw-r--r-- | docs/sections/guides/infra_guides/oom_infra_optional_addons.rst (renamed from docs/sections/guides/infra_guides/oom_base_optional_addons.rst) | 126 |
6 files changed, 318 insertions, 153 deletions
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_base_config_setup.rst b/docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst index 81f6bb4f82..f27277ddc9 100644 --- a/docs/sections/guides/infra_guides/oom_base_config_setup.rst +++ b/docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst @@ -11,11 +11,15 @@ .. _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. @@ -29,7 +33,8 @@ the following mandatory installation and configuration steps must be completed. 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. @@ -70,7 +75,8 @@ Validate the installation:: Install & configure helm -************************ +------------------------ + Helm is used for package and configuration management of the relevant helm charts. For additional information, see the `helm installation guide`_ @@ -107,12 +113,13 @@ Verify the plugins are installed:: :: NAME VERSION DESCRIPTION - deploy 1.0.0 install (upgrade if release exists) parent charty and all subcharts as separate but related releases + 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 -********************************** +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. @@ -152,7 +159,7 @@ Verify the installation:: .. _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 @@ -189,3 +196,178 @@ Verify the installation:: 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 <recommended-istio-version> with the version + defined in the :ref:`versions_table` table:: + + > helm upgrade -i istio-base istio/base -n istio-system --version <recommended-istio-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 + <recommended-istio-version> with the version defined in the :ref:`versions_table` table:: + + > helm upgrade -i istiod istio/istiod -n istio-system --version <recommended-istio-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<oom_customize_overrides>` 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 + <recommended-istio-version> with the version defined in + the :ref:`versions_table` table:: + + > helm upgrade -i istio-ingress istio/gateway -n istio-ingress + --version <recommended-istio-version> -f ingress-istio.yaml --wait + + +Gateway-API +^^^^^^^^^^^ + +- Install the Gateway-API CRDs replacing the + <recommended-gwapi-version> with the version defined in + the :ref:`versions_table` table:: + + > kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/<recommended-gwapi-version>/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_setup.rst b/docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst index ed7b05a103..1b9db50fe0 100644 --- a/docs/sections/guides/infra_guides/oom_infra_setup.rst +++ b/docs/sections/guides/infra_guides/oom_infra_deployment_requirements.rst @@ -6,21 +6,12 @@ .. 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/ +.. _kubelet config 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. +ONAP Deployment Requirements +============================ .. rubric:: Minimum Hardware Configuration @@ -40,7 +31,7 @@ See the :ref:`OOM customized deployment<oom_customize_overrides>` section for mo .. 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. + | 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). @@ -54,28 +45,28 @@ The versions of software that are supported by OOM are as follows: .. 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 - ============== ================= ====== - + ============== =========== ======= ======== ======== ============= ======== + 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 + ============== =========== ======= ======== ======== ============= ======== -.. toctree:: - :hidden: +.. table:: OOM Software Requirements (production) - oom_base_config_setup.rst - oom_base_optional_addons.rst - oom_setup_ingress_controller.rst + ============== ====== ============ ============== + 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_setup_ingress_controller.rst b/docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst index 8c261fdfd7..1fb7baa53a 100644 --- a/docs/sections/guides/infra_guides/oom_setup_ingress_controller.rst +++ b/docs/sections/guides/infra_guides/oom_infra_ingres_controller_setup.rst @@ -10,7 +10,7 @@ .. _oom_setup_ingress_controller: OOM Ingress controller setup -############################ +============================ .. warning:: This guide should prob go in the Optional addons section @@ -42,7 +42,8 @@ The result at the end of this tutorial will be: controller Customize cluster.yml file -************************** +-------------------------- + Before setup cluster for ingress purposes DNS cluster IP and ingress provider should be configured and following: @@ -86,7 +87,8 @@ 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 @@ -120,7 +122,7 @@ Example output depends on the IP address and example output looks like bellow:: 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 @@ -135,7 +137,7 @@ MetalLB Load balancer can be easily installed using automatic install script:: Configuration of the Nginx ingress controller -********************************************* +--------------------------------------------- After installation of the DNS server and ingress controller, we can install and configure ingress controller. @@ -157,7 +159,8 @@ exposed as load balancer service with an external IP address:: ONAP with ingress exposed services -********************************** +---------------------------------- + If you want to deploy onap with services exposed through ingress controller you can use full onap deploy yaml:: @@ -173,4 +176,3 @@ Ingress also can be enabled on any onap setup override using following code: <...> ingress: enabled: true - diff --git a/docs/sections/guides/infra_guides/oom_base_optional_addons.rst b/docs/sections/guides/infra_guides/oom_infra_optional_addons.rst index 713aec6c8c..8b15f6c7c2 100644 --- a/docs/sections/guides/infra_guides/oom_base_optional_addons.rst +++ b/docs/sections/guides/infra_guides/oom_infra_optional_addons.rst @@ -13,12 +13,13 @@ .. _oom_base_optional_addons: OOM Optional Addons -################### +=================== -The following optional applications can be added to your kubernetes environment. +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. @@ -44,105 +45,9 @@ To install the prometheus stack, execute the following: > helm install prometheus prometheus-community/kube-prometheus-stack --namespace=prometheus --create-namespace --version=<recommended-pm-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 <recommended-istio-version> with the version - defined in the :ref:`versions_table` table:: - - > helm upgrade -i istio-base istio/base -n istio-system --version <recommended-istio-version> - -- Install the Istio Base Istio Discovery chart which deploys the istiod service, replacing the - <recommended-istio-version> 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 <recommended-istio-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 - <recommended-istio-version> with the version defined in - the :ref:`versions_table` table:: - - > helm upgrade -i istio-ingress istio/gateway -n istio-ingress - --version <recommended-istio-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`_ @@ -187,21 +92,32 @@ For setup the kiali operator is used, see `Kiali setup guide`_ 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. +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. +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`_ +Dependent component version compatibility details and installation instructions +can be found at `Kserve setup guide`_ Kserve installation requires the following components: |