1 .. This work is licensed under a Creative Commons Attribution 4.0
2 .. International License.
3 .. http://creativecommons.org/licenses/by/4.0
4 .. Copyright (C) 2022 Nordix Foundation
7 .. _HELM Best Practices Guide: https://docs.helm.sh/chart_best_practices/#requirements
8 .. _helm installation guide: https://helm.sh/docs/intro/install/
9 .. _kubectl installation guide: https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/
10 .. _Curated applications for Kubernetes: https://github.com/kubernetes/charts
11 .. _Cert-Manager Installation documentation: https://cert-manager.io/docs/installation/kubernetes/
12 .. _Cert-Manager kubectl plugin documentation: https://cert-manager.io/docs/usage/kubectl-plugin/
13 .. _Strimzi Apache Kafka Operator helm Installation documentation: https://strimzi.io/docs/operators/in-development/deploying.html#deploying-cluster-operator-helm-chart-str
14 .. _ONAP Next Generation Security & Logging Structure: https://wiki.onap.org/pages/viewpage.action?pageId=103417456
15 .. _Istio setup guide: https://istio.io/latest/docs/setup/install/helm/
16 .. _Gateway-API: https://gateway-api.sigs.k8s.io/
17 .. _Istio-Gateway: https://istio.io/latest/docs/reference/config/networking/gateway/
19 .. _oom_base_setup_guide:
24 As part of the initial base setup of the host Kubernetes cluster,
25 the following mandatory installation and configuration steps must be completed.
33 For additional platform add-ons, see the :ref:`oom_base_optional_addons` section.
35 Install & configure kubectl
36 ---------------------------
38 The Kubernetes command line interface used to manage a Kubernetes cluster needs to be installed
39 and configured to run as non root.
41 For additional information regarding kubectl installation and configuration see the `kubectl installation guide`_
43 To install kubectl, execute the following, replacing the <recommended-kubectl-version> with the version defined
44 in the :ref:`versions_table` table::
46 > curl -LO https://dl.k8s.io/release/v<recommended-kubectl-version>/bin/linux/amd64/kubectl
50 > sudo mv ./kubectl /usr/local/bin/kubectl
54 > cp kube_config_cluster.yml ~/.kube/config.onap
56 > export KUBECONFIG=~/.kube/config.onap
58 > kubectl config use-context onap
60 Validate the installation::
66 NAME STATUS ROLES AGE VERSION
67 onap-control-1 Ready controlplane,etcd 3h53m v1.23.8
68 onap-control-2 Ready controlplane,etcd 3h53m v1.23.8
69 onap-k8s-1 Ready worker 3h53m v1.23.8
70 onap-k8s-2 Ready worker 3h53m v1.23.8
71 onap-k8s-3 Ready worker 3h53m v1.23.8
72 onap-k8s-4 Ready worker 3h53m v1.23.8
73 onap-k8s-5 Ready worker 3h53m v1.23.8
74 onap-k8s-6 Ready worker 3h53m v1.23.8
77 Install & configure helm
78 ------------------------
80 Helm is used for package and configuration management of the relevant helm charts.
81 For additional information, see the `helm installation guide`_
83 To install helm, execute the following, replacing the <recommended-helm-version> with the version defined
84 in the :ref:`versions_table` table::
86 > wget https://get.helm.sh/helm-v<recommended-helm-version>-linux-amd64.tar.gz
88 > tar -zxvf helm-v<recommended-helm-version>-linux-amd64.tar.gz
90 > sudo mv linux-amd64/helm /usr/local/bin/helm
92 Verify the helm version with::
96 Helm's default CNCF provided `Curated applications for Kubernetes`_ repository called
97 *stable* can be removed to avoid confusion::
99 > helm repo remove stable
101 Install the additional OOM plugins required to un/deploy the OOM helm charts::
103 > git clone http://gerrit.onap.org/r/oom
105 > helm plugin install ~/oom/kubernetes/helm/plugins/deploy
107 > helm plugin install ~/oom/kubernetes/helm/plugins/undeploy
109 Verify the plugins are installed::
115 NAME VERSION DESCRIPTION
116 deploy 1.0.0 install (upgrade if release exists) parent chart and all subcharts as separate but related releases
117 undeploy 1.0.0 delete parent chart and subcharts that were deployed as separate releases
120 Install the Strimzi Kafka Operator
121 ----------------------------------
123 Strimzi Apache Kafka provides a way to run an Apache Kafka cluster on Kubernetes
124 in various deployment configurations by using kubernetes operators.
125 Operators are a method of packaging, deploying, and managing Kubernetes applications.
127 Strimzi Operators extend the Kubernetes functionality, automating common
128 and complex tasks related to a Kafka deployment. By implementing
129 knowledge of Kafka operations in code, the Kafka administration
130 tasks are simplified and require less manual intervention.
132 The Strimzi cluster operator is deployed using helm to install the parent chart
133 containing all of the required custom resource definitions. This should be done
134 by a kubernetes administrator to allow for deployment of custom resources in to
135 any kubernetes namespace within the cluster.
137 Full installation instructions can be found in the
138 `Strimzi Apache Kafka Operator helm Installation documentation`_.
140 To add the required helm repository, execute the following::
142 > helm repo add strimzi https://strimzi.io/charts/
144 To install the strimzi kafka operator, execute the following, replacing the <recommended-strimzi-version> with the version defined
145 in the :ref:`versions_table` table::
147 > helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version <recommended-strimzi-version> --set watchAnyNamespace=true --create-namespace
149 Verify the installation::
151 > kubectl get po -n strimzi-system
155 NAME READY STATUS RESTARTS AGE
156 strimzi-cluster-operator-7f7d6b46cf-mnpjr 1/1 Running 0 2m
159 .. _oom_base_setup_cert_manager:
164 Cert-Manager is a native Kubernetes certificate management controller.
165 It can help with issuing certificates from a variety of sources, such as
166 Let’s Encrypt, HashiCorp Vault, Venafi, a simple signing key pair, self
167 signed or external issuers. It ensures certificates are valid and up to
168 date, and attempt to renew certificates at a configured time before expiry.
170 Cert-Manager is deployed using regular YAML manifests which include all
171 the needed resources (the CustomResourceDefinitions, cert-manager,
172 namespace, and the webhook component).
174 Full installation instructions, including details on how to configure extra
175 functionality in Cert-Manager can be found in the
176 `Cert-Manager Installation documentation`_.
178 There is also a kubectl plugin (kubectl cert-manager) that can help you
179 to manage cert-manager resources inside your cluster. For installation
180 steps, please refer to `Cert-Manager kubectl plugin documentation`_.
183 To install cert-manager, execute the following, replacing the <recommended-cm-version> with the version defined
184 in the :ref:`versions_table` table::
186 > kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v<recommended-cm-version>/cert-manager.yaml
188 Verify the installation::
190 > kubectl get po -n cert-manager
194 NAME READY STATUS RESTARTS AGE
195 cert-manager-776c4cfcb6-vgnpw 1/1 Running 0 2m
196 cert-manager-cainjector-7d9668978d-hdxf7 1/1 Running 0 2m
197 cert-manager-webhook-66c8f6c75-dxmtz 1/1 Running 0 2m
203 In London ONAP deployment supports the
204 `ONAP Next Generation Security & Logging Structure`_
206 ONAP is currenty supporting Istio as default ServiceMesh platform.
207 Therefor the following instructions describe the setup of Istio and required tools.
208 Used `Istio setup guide`_
210 .. _oom_base_optional_addons_istio_installation:
212 Istio Platform Installation
213 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
215 Install Istio Basic Platform
216 """"""""""""""""""""""""""""
218 - Configure the Helm repository::
220 > helm repo add istio https://istio-release.storage.googleapis.com/charts
224 - Create a namespace for "mesh-level" configurations::
226 > kubectl create namespace istio-config
228 - Create a namespace istio-system for Istio components::
230 > kubectl create namespace istio-system
232 - Install the Istio Base chart which contains cluster-wide resources used by the
233 Istio control plane, replacing the <recommended-istio-version> with the version
234 defined in the :ref:`versions_table` table::
236 > helm upgrade -i istio-base istio/base -n istio-system --version <recommended-istio-version>
238 - Create an override for istiod (e.g. istiod.yaml) to add the oauth2-proxy as external
239 authentication provider and apply some specific config settings
241 .. collapse:: istiod.yaml
243 .. include:: ../../resources/yaml/istiod.yaml
246 - Install the Istio Base Istio Discovery chart which deploys the istiod service, replacing the
247 <recommended-istio-version> with the version defined in the :ref:`versions_table` table::
249 > helm upgrade -i istiod istio/istiod -n istio-system --version <recommended-istio-version>
250 --wait -f ./istiod.yaml
252 Add an EnvoyFilter for HTTP header case
253 """""""""""""""""""""""""""""""""""""""
255 When handling HTTP/1.1, Envoy will normalize the header keys to be all
256 lowercase. While this is compliant with the HTTP/1.1 spec, in practice this
257 can result in issues when migrating existing systems that might rely on
258 specific header casing. In our case a problem was detected in the SDC client
259 implementation, which relies on uppercase header values. To solve this problem
260 in general we add a EnvoyFilter to keep the uppercase header in the
261 istio-config namespace to apply for all namespaces, but set the context to
262 SIDECAR_INBOUND to avoid problems in the connection between Istio-Gateway and
265 - Create a EnvoyFilter file (e.g. envoyfilter-case.yaml)
267 .. collapse:: envoyfilter-case.yaml
269 .. include:: ../../resources/yaml/envoyfilter-case.yaml
272 - Apply the change to Istio::
274 > kubectl apply -f envoyfilter-case.yaml
277 Ingress Controller Installation
278 -------------------------------
280 In the production setup 2 different Ingress setups are supported.
282 - Istio Gateway `Istio-Gateway`_ (currently tested, but in the future deprecated)
283 - Gateway API `Gateway-API`_ (in Alpha status, but will be standard in the future)
285 Depending on the solution, the ONAP helm values.yaml has to be configured.
286 See the :ref:`OOM customized deployment<oom_customize_overrides>` section for more details.
291 - Create a namespace istio-ingress for the Istio Ingress gateway
292 and enable istio-injection::
294 > kubectl create namespace istio-ingress
296 > kubectl label namespace istio-ingress istio-injection=enabled
298 - To expose additional ports besides HTTP/S (e.g. for external Kafka access, SDNC-callhome)
299 create an override file (e.g. istio-ingress.yaml)
301 .. collapse:: istio-ingress.yaml
303 .. include:: ../../resources/yaml/istio-ingress.yaml
306 - Install the Istio Gateway chart using the override file, replacing the
307 <recommended-istio-version> with the version defined in
308 the :ref:`versions_table` table::
310 > helm upgrade -i istio-ingress istio/gateway -n istio-ingress
311 --version <recommended-istio-version> -f ingress-istio.yaml --wait
317 - Install the Gateway-API CRDs replacing the
318 <recommended-gwapi-version> with the version defined in
319 the :ref:`versions_table` table::
321 > kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/<recommended-gwapi-version>/experimental-install.yaml
323 - Create a common Gateway instance
326 Keycloak Installation
327 ---------------------
329 - Add helm repositories
331 > helm repo add bitnami https://charts.bitnami.com/bitnami
333 > helm repo add codecentric https://codecentric.github.io/helm-charts
337 - create keycloak namespace
339 > kubectl create namespace keycloak
340 > kubectl label namespace keycloak istio-injection=enabled
342 Install Keycloak-Database
343 ^^^^^^^^^^^^^^^^^^^^^^^^^
345 - To configure the Postgres DB
346 create an override file (e.g. keycloak-db-values.yaml)
348 .. collapse:: keycloak-db-values.yaml
350 .. include:: ../../resources/yaml/keycloak-db-values.yaml
353 - Install the Postgres DB
355 > helm -n keycloak upgrade -i keycloak-db bitnami/postgresql --values ./keycloak-db-values.yaml
360 - To configure the Keycloak instance
361 create an override file (e.g. keycloak-server-values.yaml)
363 .. collapse:: keycloak-server-values.yaml
365 .. include:: ../../resources/yaml/keycloak-server-values.yaml
370 > helm -n keycloak upgrade -i keycloak codecentric/keycloak --values ./keycloak-server-values.yaml
372 The required Ingress entry and REALM will be provided by the ONAP "Platform"