docs/sections/guides/infra_guides/oom_infra_base_config_setup.rst

   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
   5
   6 .. Links
   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/
  18
  19 .. _oom_base_setup_guide:
  20
  21 OOM Base Platform
  22 =================
  23
  24 As part of the initial base setup of the host Kubernetes cluster,
  25 the following mandatory installation and configuration steps must be completed.
  26
  27 .. contents::
  28    :backlinks: top
  29    :depth: 1
  30    :local:
  31 ..
  32
  33 For additional platform add-ons, see the :ref:`oom_base_optional_addons` section.
  34
  35 Install & configure kubectl
  36 ---------------------------
  37
  38 The Kubernetes command line interface used to manage a Kubernetes cluster needs to be installed
  39 and configured to run as non root.
  40
  41 For additional information regarding kubectl installation and configuration see the `kubectl installation guide`_
  42
  43 To install kubectl, execute the following, replacing the <recommended-kubectl-version> with the version defined
  44 in the :ref:`versions_table` table::
  45
  46     > curl -LO https://dl.k8s.io/release/v<recommended-kubectl-version>/bin/linux/amd64/kubectl
  47
  48     > chmod +x ./kubectl
  49
  50     > sudo mv ./kubectl /usr/local/bin/kubectl
  51
  52     > mkdir ~/.kube
  53
  54     > cp kube_config_cluster.yml ~/.kube/config.onap
  55
  56     > export KUBECONFIG=~/.kube/config.onap
  57
  58     > kubectl config use-context onap
  59
  60 Validate the installation::
  61
  62     > kubectl get nodes
  63
  64 ::
  65
  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
  75
  76
  77 Install & configure helm
  78 ------------------------
  79
  80 Helm is used for package and configuration management of the relevant helm charts.
  81 For additional information, see the `helm installation guide`_
  82
  83 To install helm, execute the following, replacing the <recommended-helm-version> with the version defined
  84 in the :ref:`versions_table` table::
  85
  86     > wget https://get.helm.sh/helm-v<recommended-helm-version>-linux-amd64.tar.gz
  87
  88     > tar -zxvf helm-v<recommended-helm-version>-linux-amd64.tar.gz
  89
  90     > sudo mv linux-amd64/helm /usr/local/bin/helm
  91
  92 Verify the helm version with::
  93
  94     > helm version
  95
  96 Helm's default CNCF provided `Curated applications for Kubernetes`_ repository called
  97 *stable* can be removed to avoid confusion::
  98
  99     > helm repo remove stable
 100
 101 Install the additional OOM plugins required to un/deploy the OOM helm charts::
 102
 103     > git clone http://gerrit.onap.org/r/oom
 104
 105     > helm plugin install ~/oom/kubernetes/helm/plugins/deploy
 106
 107     > helm plugin install ~/oom/kubernetes/helm/plugins/undeploy
 108
 109 Verify the plugins are installed::
 110
 111     > helm plugin ls
 112
 113 ::
 114
 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
 118
 119
 120 Install the Strimzi Kafka Operator
 121 ----------------------------------
 122
 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.
 126
 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.
 131
 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.
 136
 137 Full installation instructions can be found in the
 138 `Strimzi Apache Kafka Operator helm Installation documentation`_.
 139
 140 To add the required helm repository, execute the following::
 141
 142     > helm repo add strimzi https://strimzi.io/charts/
 143
 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::
 146
 147     > helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version <recommended-strimzi-version> --set watchAnyNamespace=true --create-namespace
 148
 149 Verify the installation::
 150
 151     > kubectl get po -n strimzi-system
 152
 153 ::
 154
 155     NAME                                        READY   STATUS    RESTARTS       AGE
 156     strimzi-cluster-operator-7f7d6b46cf-mnpjr   1/1     Running   0              2m
 157
 158
 159 .. _oom_base_setup_cert_manager:
 160
 161 Install Cert-Manager
 162 --------------------
 163
 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.
 169
 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).
 173
 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`_.
 177
 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`_.
 181
 182
 183 To install cert-manager, execute the following, replacing the <recommended-cm-version> with the version defined
 184 in the :ref:`versions_table` table::
 185
 186     > kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v<recommended-cm-version>/cert-manager.yaml
 187
 188 Verify the installation::
 189
 190     > kubectl get po -n cert-manager
 191
 192 ::
 193
 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
 198
 199 Istio Service Mesh
 200 ------------------
 201
 202 .. note::
 203     In London ONAP deployment supports the
 204     `ONAP Next Generation Security & Logging Structure`_
 205
 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`_
 209
 210 .. _oom_base_optional_addons_istio_installation:
 211
 212 Istio Platform Installation
 213 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 214
 215 Install Istio Basic Platform
 216 """"""""""""""""""""""""""""
 217
 218 - Configure the Helm repository::
 219
 220     > helm repo add istio https://istio-release.storage.googleapis.com/charts
 221
 222     > helm repo update
 223
 224 - Create a namespace for "mesh-level" configurations::
 225
 226     > kubectl create namespace istio-config
 227
 228 - Create a namespace istio-system for Istio components::
 229
 230     > kubectl create namespace istio-system
 231
 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::
 235
 236     > helm upgrade -i istio-base istio/base -n istio-system --version <recommended-istio-version>
 237
 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
 240
 241     .. collapse:: istiod.yaml
 242
 243       .. include:: ../../resources/yaml/istiod.yaml
 244          :code: yaml
 245
 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::
 248
 249     > helm upgrade -i istiod istio/istiod -n istio-system --version <recommended-istio-version>
 250     --wait -f ./istiod.yaml
 251
 252 Add an EnvoyFilter for HTTP header case
 253 """""""""""""""""""""""""""""""""""""""
 254
 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
 263 Services
 264
 265 - Create a EnvoyFilter file (e.g. envoyfilter-case.yaml)
 266
 267     .. collapse:: envoyfilter-case.yaml
 268
 269       .. include:: ../../resources/yaml/envoyfilter-case.yaml
 270          :code: yaml
 271
 272 - Apply the change to Istio::
 273
 274     > kubectl apply -f envoyfilter-case.yaml
 275
 276
 277 Ingress Controller Installation
 278 -------------------------------
 279
 280 In the production setup 2 different Ingress setups are supported.
 281
 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)
 284
 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.
 287
 288 Istio Gateway
 289 ^^^^^^^^^^^^^
 290
 291 - Create a namespace istio-ingress for the Istio Ingress gateway
 292   and enable istio-injection::
 293
 294     > kubectl create namespace istio-ingress
 295
 296     > kubectl label namespace istio-ingress istio-injection=enabled
 297
 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)
 300
 301     .. collapse:: istio-ingress.yaml
 302
 303       .. include:: ../../resources/yaml/istio-ingress.yaml
 304          :code: yaml
 305
 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::
 309
 310     > helm upgrade -i istio-ingress istio/gateway -n istio-ingress
 311     --version <recommended-istio-version> -f ingress-istio.yaml --wait
 312
 313
 314 Gateway-API
 315 ^^^^^^^^^^^
 316
 317 - Install the Gateway-API CRDs replacing the
 318   <recommended-gwapi-version> with the version defined in
 319   the :ref:`versions_table` table::
 320
 321     > kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/<recommended-gwapi-version>/experimental-install.yaml
 322
 323 - Create a common Gateway instance
 324   TBD
 325
 326 Keycloak Installation
 327 ---------------------
 328
 329 - Add helm repositories
 330
 331   > helm repo add bitnami https://charts.bitnami.com/bitnami
 332
 333   > helm repo add codecentric https://codecentric.github.io/helm-charts
 334
 335   > helm repo update
 336
 337 - create keycloak namespace
 338
 339   > kubectl create namespace keycloak
 340   > kubectl label namespace keycloak istio-injection=enabled
 341
 342 Install Keycloak-Database
 343 ^^^^^^^^^^^^^^^^^^^^^^^^^
 344
 345 - To configure the Postgres DB
 346   create an override file (e.g. keycloak-db-values.yaml)
 347
 348     .. collapse:: keycloak-db-values.yaml
 349
 350       .. include:: ../../resources/yaml/keycloak-db-values.yaml
 351          :code: yaml
 352
 353 - Install the Postgres DB
 354
 355   > helm -n keycloak upgrade -i keycloak-db bitnami/postgresql --values ./keycloak-db-values.yaml
 356
 357 Configure Keycloak
 358 ^^^^^^^^^^^^^^^^^^
 359
 360 - To configure the Keycloak instance
 361   create an override file (e.g. keycloak-server-values.yaml)
 362
 363     .. collapse:: keycloak-server-values.yaml
 364
 365       .. include:: ../../resources/yaml/keycloak-server-values.yaml
 366          :code: yaml
 367
 368 - Install keycloak
 369
 370   > helm -n keycloak upgrade -i keycloak codecentric/keycloak --values ./keycloak-server-values.yaml
 371
 372 The required Ingress entry and REALM will be provided by the ONAP "Platform"
 373 component.