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