docs/sections/guides/access_guides/oom_access_info.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 .. _Kubernetes LoadBalancer: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer
   8 .. _Kubernetes NodePort: https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport
   9
  10 .. _oom_access_info_guide:
  11
  12 OOM Access Info
  13 ###############
  14
  15 .. figure:: ../../resources/images/oom_logo/oomLogoV2-medium.png
  16    :align: right
  17
  18 Access via NodePort/Loadbalancer
  19 ********************************
  20
  21 The ONAP deployment created by OOM operates in a private IP network that isn't
  22 publicly accessible (i.e. OpenStack VMs with private internal network) which
  23 blocks access to the ONAP User Interfaces.
  24 To enable direct access to a service from a user's own environment (a laptop etc.)
  25 the application's internal port is exposed through a `Kubernetes NodePort`_ or
  26 `Kubernetes LoadBalancer`_ object.
  27
  28 Typically, to be able to access the Kubernetes nodes publicly a public address
  29 is assigned. In OpenStack this is a floating IP address.
  30
  31 Most ONAP applications use the `NodePort` as predefined `service:type`,
  32 which opens allows access to the service through the the IP address of each
  33 Kubernetes node.
  34 When using  the `Loadbalancer` as `service:type` `Kubernetes LoadBalancer`_ object
  35 which gets a separate IP address.
  36
  37 .. note::
  38   The following example uses the `ONAP Portal`, which is not actively maintained
  39   in Kohn and will be replaced in the future
  40
  41 When e.g. the `portal-app` chart is deployed a Kubernetes service is created that
  42 instantiates a load balancer.  The LB chooses the private interface of one of
  43 the nodes as in the example below (10.0.0.4 is private to the K8s cluster only).
  44 Then to be able to access the portal on port 8989 from outside the K8s &
  45 OpenStack environment, the user needs to assign/get the floating IP address that
  46 corresponds to the private IP as follows::
  47
  48   > kubectl -n onap get services|grep "portal-app"
  49   portal-app  LoadBalancer   10.43.142.201   10.0.0.4   8989:30215/TCP,8006:30213/TCP,8010:30214/TCP   1d   app=portal-app,release=dev
  50
  51
  52 In this example, use the 11.0.0.4 private address as a key find the
  53 corresponding public address which in this example is 10.12.6.155. If you're
  54 using OpenStack you'll do the lookup with the horizon GUI or the OpenStack CLI
  55 for your tenant (openstack server list).  That IP is then used in your
  56 `/etc/hosts` to map the fixed DNS aliases required by the ONAP Portal as shown
  57 below::
  58
  59   10.12.6.155 portal.api.simpledemo.onap.org
  60   10.12.6.155 vid.api.simpledemo.onap.org
  61   10.12.6.155 sdc.api.fe.simpledemo.onap.org
  62   10.12.6.155 sdc.workflow.plugin.simpledemo.onap.org
  63   10.12.6.155 sdc.dcae.plugin.simpledemo.onap.org
  64   10.12.6.155 portal-sdk.simpledemo.onap.org
  65   10.12.6.155 policy.api.simpledemo.onap.org
  66   10.12.6.155 aai.api.sparky.simpledemo.onap.org
  67   10.12.6.155 cli.api.simpledemo.onap.org
  68   10.12.6.155 msb.api.discovery.simpledemo.onap.org
  69   10.12.6.155 msb.api.simpledemo.onap.org
  70   10.12.6.155 clamp.api.simpledemo.onap.org
  71   10.12.6.155 so.api.simpledemo.onap.org
  72   10.12.6.155 sdc.workflow.plugin.simpledemo.onap.org
  73
  74 Ensure you've disabled any proxy settings the browser you are using to access
  75 the portal and then simply access now the new ssl-encrypted URL:
  76 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
  77
  78 .. note::
  79   Using the HTTPS based Portal URL the Browser needs to be configured to accept
  80   unsecure credentials.
  81   Additionally when opening an Application inside the Portal, the Browser
  82   might block the content, which requires to disable the blocking and reloading
  83   of the page
  84
  85 .. note::
  86   Besides the ONAP Portal the Components can deliver additional user interfaces,
  87   please check the Component specific documentation.
  88
  89 .. note::
  90
  91    | Alternatives Considered:
  92
  93    -  Kubernetes port forwarding was considered but discarded as it would
  94       require the end user to run a script that opens up port forwarding tunnels
  95       to each of the pods that provides a portal application widget.
  96
  97    -  Reverting to a VNC server similar to what was deployed in the Amsterdam
  98       release was also considered but there were many issues with resolution,
  99       lack of volume mount, /etc/hosts dynamic update, file upload that were
 100       a tall order to solve in time for the Beijing release.
 101
 102    Observations:
 103
 104    -  If you are not using floating IPs in your Kubernetes deployment and
 105       directly attaching a public IP address (i.e. by using your public provider
 106       network) to your K8S Node VMs' network interface, then the output of
 107       'kubectl -n onap get services | grep "portal-app"'
 108       will show your public IP instead of the private network's IP. Therefore,
 109       you can grab this public IP directly (as compared to trying to find the
 110       floating IP first) and map this IP in /etc/hosts.
 111
 112 Some relevant information regarding accessing OOM from outside the cluster etc
 113
 114 ONAP Nodeports
 115 ==============
 116
 117 NodePorts are used to allow client applications, that run outside of
 118 Kubernetes, access to ONAP components deployed by OOM.
 119 A NodePort maps an externally reachable port to an internal port of an ONAP
 120 microservice.
 121 It should be noted that the use of NodePorts is temporary.
 122 An alternative solution based on Ingress Controller, which initial support is
 123 already in place. It is planned to become a default deployment option in the
 124 London release.
 125
 126 More information from official Kubernetes documentation about
 127 `Kubernetes NodePort`_.
 128
 129 The following table lists all the NodePorts used by ONAP.
 130
 131 .. csv-table:: NodePorts table
 132    :file: ../../resources/csv/nodeports.csv
 133    :widths: 20,20,20,20,20
 134    :header-rows: 1
 135
 136
 137 This table retrieves information from the ONAP deployment using the following
 138 Kubernetes command:
 139
 140 .. code-block:: bash
 141
 142   kubectl get svc -n onap -o go-template='{{range .items}}{{range.spec.ports}}{{if .nodePort}}{{.nodePort}}{{.}}{{"\n"}}{{end}}{{end}}{{end}}'
 143
 144
 145 (Optional) Access via Ingress
 146 *****************************
 147
 148 Using Ingress as access method requires the installation of an Ingress
 149 controller and the configuration of the ONAP deployment to use it.
 150
 151 For "ONAP on ServiceMesh" you can find the instructions in:
 152
 153 - :ref:`oom_base_optional_addons`
 154 - :ref:`oom_customize_overrides`
 155
 156 In the ServiceMesh deployment the Istio IngressGateway is the only access point
 157 for ONAP component interfaces.
 158 Usually the Ingress is accessed via a LoadBalancer IP (<ingress-IP>),
 159 which is used as central address.
 160 All APIs/UIs are provided via separate URLs which are routed to the component service.
 161 To use these URLs they need to be resolvable via DNS or via /etc/hosts.
 162
 163 The domain name is usually defined in the `global` section of the ONAP helm-charts,
 164 `virtualhost.baseurl` (here "simpledemo.onap.org") whereas the hostname of
 165 the service (e.g. "sdc-fe-ui") is defined in the component's chart.
 166
 167 .. code-block:: none
 168
 169   <ingress-IP> kiali.simpledemo.onap.org
 170   <ingress-IP> cds-ui.simpledemo.onap.org
 171   <ingress-IP> sdc-fe-ui.simpledemo.onap.org
 172   ...
 173
 174 To access e.g. the SDC UI now the new ssl-encrypted URL:
 175
 176 ``https://sdc-fe-ui.simpledemo.onap.org/sdc1``