service-exposure/README.md

   1 #
   2 # ============LICENSE_START=======================================================
   3 #  Copyright (C) 2022 Nordix Foundation.
   4 # ================================================================================
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #      http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16 #
  17 # SPDX-License-Identifier: Apache-2.0
  18 # ============LICENSE_END=========================================================
  19 #
  20 This collection of files represent rapp service exposure prototyping in O-RAN.
  21 Prerequisites: Istio should be installed on your cluster with the demo profile.
  22   istioctl install --set profile=demo
  23 Please refer to the istio documentation for more information.
  24 You will also need cfssl installed on your system: sudo apt install golang-cfssl
  25 Please refer to the K8s documentation: Manage TLS Certificates in a Cluster
  26 The deployments have been implemented and tested using minikube.
  27 If you are not using minikube, references to "minikube ip" should be changed to the appropiate value for you host.
  28 To replicate these tests you will need to setup the various host path referenced in the yaml files on your own machine.
  29
  30 chartmuseum.yaml:             path: /var/chartmuseum/charts
  31 keycloak.yaml:                path: /auth/realms/master
  32 keycloak.yaml:                path: /var/keycloak/certs
  33 postgres.yaml:                path: "/var/keycloak/data2"
  34 postgres.yaml:                path: /tmp
  35 rapps-keycloak-mgr.yaml:      path: /var/rapps/certs
  36
  37 or change them to match your own setup.
  38
  39 The certs directory contains 3 shell scripts for creating the server, client and webhook certs: server_certs.sh, client_certs.sh and webhook-certs.sh
  40 Certs generated by the server_certs.sh script: rootCA.crt, tls.crt and tls.key go in the "/var/keycloak/certs" directory
  41 Certs generated by the client_certs.sh script: client.crt, client.key, client_pub.key and rootCA.crt go in the "/var/rapps/certs" directory
  42 The webhook-certs.sh script generates certs for use in the MutatingWebhookConfiguration.yaml and the rapps-webhook.yaml files.
  43 To configure MutatingWebhookConfiguration.yaml run the following commands:
  44 1. ca_pem_b64="$(openssl base64 -A <"./certs/ca.pem")"
  45 2. sed -i 's/${CA_PEM_B64}/'"$ca_pem_b64"'/g' MutatingWebhookConfiguration.yaml
  46
  47 To configure rapps-webhook.yaml append the rapps-webhook-tls.yaml file to the end of it
  48 1. cat rapps-webhook.yaml ./certs/rapps-webhook-tls.yaml >> rapps-webhook.yaml.tmp
  49 2. mv rapps-webhook.yaml.tmp rapps-webhook.yaml
  50
  51 Create the istio-nonrtric namespace and enable it for istio injection
  52
  53    kubectl create ns istio-nonrtric
  54
  55    kubectl label namespace istio-nonrtric istio-injection=enabled
  56
  57
  58 All go programs need to be built prior to running the Dockerfiles
  59
  60    go build rapps-helm-installer.go
  61    go build rapps-keycloak-mgr.go
  62    go build rapps-istio-mgr.go
  63    go build rapps-rapp-provider.go
  64    go build rapps-rapp-invoker.go
  65    go build rapps-webhook.go
  66    go build rapps-jwt.go
  67    go build rapps-rapp-helloworld-provider.go
  68    go build rapps-rapp-helloworld-invoker1.go
  69    go build rapps-rapp-helloworld-invoker2.go
  70
  71 Once the go programs have been compile you then need to build a docker image for each of them.
  72
  73    docker build -f Dockerfile_rim . -t <tag prefix>/rapps-istio-mgr
  74    docker build -f Dockerfile_rkm . -t <tag prefix>/rapps-keycloak-mgr
  75    docker build -f Dockerfile_rhi . -t <tag prefix>/rapps-helm-installer
  76    docker build -f Dockerfile_wh . -t <tag prefix>/rapps-webhook
  77    docker build -f Dockerfile_jwt . -t <tag prefix>/rapps-jwt
  78    docker build -f Dockerfile_rhwp  . -t <tag prefix>/rapps-rapp-helloworld-provider
  79    docker build -f Dockerfile_rhwi1  . -t <tag prefix>/rapps-rapp-helloworld-invoker1
  80    docker build -f Dockerfile_rhwi2  . -t <tag prefix>/rapps-rapp-helloworld-invoker2
  81
  82 Image references in the yaml files/helm charts should be changed to match your own tagged images.
  83
  84 You will need to package your rapp charts and copy them to the /var/chartmuseum/charts directory before starting.
  85
  86    cd charts/
  87    helm package rapp-provider
  88    scp -i $(minikube ssh-key) rapp-provider-0.1.0.tgz docker@$(minikube ip):/var/chartmuseum/charts
  89
  90    helm package rapp-invoker
  91    scp -i $(minikube ssh-key) rapp-invoker-0.1.0.tgz docker@$(minikube ip):/var/chartmuseum/charts
  92
  93
  94 Start keycloak and postgres in the default namespace with istio injection:
  95
  96    istioctl kube-inject -f postgres.yaml | kubectl apply -f -
  97    istioctl kube-inject -f keycloak.yaml | kubectl apply -f -
  98 or use the keycloak.sh deploy script
  99
 100 To start the management pods run:
 101
 102    start_pods.sh
 103
 104 Once all pods have been started a list of running pods is displayed at the end of the script:
 105 NAME                                                         READY   STATUS    RESTARTS   AGE
 106 chartmuseum-deployment-7b8cd4c9d4-nd7dk                      1/1     Running   0          9s
 107 jwt-proxy-admission-controller-deployment-66797fb6df-mlk8t   1/1     Running   0          8s
 108 keycloak-846ff979bc-ndvdf                                    2/2     Running   0          2m16s
 109 postgres-78b4b9d95-nqjkj                                     2/2     Running   0          2m29s
 110 rapps-helm-installer-deployment-67476694-n5r24               1/1     Running   0          8s
 111 rapps-istio-mgr-deployment-67c67647b6-p5s2k                  1/1     Running   0          8s
 112 rapps-keycloak-mgr-deployment-7464f87575-54h9x               1/1     Running   0          8s
 113
 114 Get the node port for the helm installer that corresponds to port 80
 115
 116    kubectl get svc rapps-helm-installer
 117    NAME                   TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
 118    rapps-helm-installer   NodePort   10.96.58.211   <none>        80:31570/TCP   8m9s
 119
 120 Once these pods are up and running run:
 121    curl http://<minikube ip>:<helm installer node port>/install?chart=<rapp chart name>
 122    to install your rapp
 123
 124    e.g. curl http://192.168.49.2:31570/install?chart=rapp-hello-world-provider
 125         Successfully installed release: rapp-provider
 126
 127    Alternativley use the deploy_rapp.sh script
 128    e.g. ./deploy_rapp.sh rapp-helloworld-provider
 129    Note: The line export host= should be changed to the appropaite ip for the host you are running on.
 130
 131 This will setup keycloak realm + client, istio policies and deploy your chart.
 132
 133 You should install both the provider and the invoker to see the pods communicating.
 134
 135 Check the invoker logs to see the test message:
 136
 137    kubectl logs rapp-invoker-758468d7d4-njmdn  -n istio-nonrtric
 138    Received response for rapp-provider get request - Hello World!
 139
 140 If you want to test using the rp_test.sh file, the client_secret field needs be changed to match the secret for you keycloak client.
 141 You can find this in the keycloak-mgr log.
 142
 143 To uninstall run:
 144    curl http://<minikube ip>:<helm installer node port>/uninstall?chart=<rapp chart name>
 145    e.g. curl http://192.168.49.2:31570/uninstall?chart=rapp-invoker
 146         Successfully uninstalled release: rapp-invoker
 147
 148    Alternativley use the undeploy_rapp.sh script
 149    e.g. ./undeploy_rapp.sh rapp-helloworld-provider
 150
 151 To stop the management pods and provider/invoker pods at the same time run:
 152    stop_pods.sh
 153
 154 Remove postgres and keycloak with the following commands:
 155    kubectl delete -f keycloak.yaml
 156    kubectl delete -f postgres.yaml
 157
 158    or use ./keycloak.sh undeploy