Installing Provisioning Gateway

Planning Your Installation

In this section, you will learn to plan Provisioning Gateway installation.

Pre-installation Tasks:

Checking the Software Requirements

In this section, you will learn about softwares required to install provisioning gateway.

Before installing Provisioning Gateway, install the following softwares on your system.

Software	Version
Kubernetes	v1.17.5
HELM	v3.1.2

Additional softwares that needs to be deployed as per the requirement of the services are:

Software	Chart Version	Notes
elasticsearch	7.6.1	Needed for Logging Area
elastic-curator	5.5.4	Needed for Logging Area
elastic-exporter	1.1.0	Needed for Logging Area
logs	3.0.0	Needed for Logging Area
kibana	7.6.1	Needed for Logging Area
grafana	6.6.2	Needed for Metrics Area
prometheus	2.16.0	Needed for Metrics Area
prometheus-node-exporter	0.18.1	Needed for Metrics Area
metallb	0.8.4	Needed for External IP
metrics-server	0.3.6	Needed for Metric Server
tracer	1.14.0	Needed for Tracing Area

Note:

The above softwares are available in the Oracle Communications Cloud Native Environment (OCCNE). If you are deploying Provisioning Gateway in any other environment, then the above softwares must be installed before installing Provisioning Gateway.

To check the installed software items, execute the following command:

helm ls

Some systems may need to use helm command with admin.conf file as follows:

helm --kubeconfig admin.conf

Checking the Environment Setup

In this section, you will learn to setup an environment to install Provisioning Gateway.

Before installing Provisioning Gateway, your system should have the following:

Provisioning Gateway Software: The Provisioning Gateway software consists of:
- Provisioning Gateway Helm Chart: reflects the Provisioning Gateway software version. It comes in the form of a zipped tar file.
- Software images of the micro-services: are available in the form of docker images and/or tar file.
  
  Note:
  For more details about Provisioning Gateway software, see Checking the Software Requirements
Network Access: The Kubernetes cluster hosts must have network access to:
- Local docker image repository where the Provisioning Gateway images are available.
- Local helm repository where the Provisioning Gateway helm charts are available.
Note:
Execute all the kubectl and helm commands used in this document on a system depending on the infrastructure of the deployment. It may be some client machine like virtual machine, server, local desktop and so on).
Laptop/Desktop Client Software: A laptop/desktop where the user executes deployment commands should have:
- Network access to the helm repository and Docker image repository.
- Helm repository configured on the client.
- Network access to the Kubernetes cluster.
- Necessary environment settings to run the 'kubectl' commands. The environment should have privileges to create a namespace in the Kubernetes cluster.
- Helm client installed with the 'push' plugin. The environment should be configured so that the 'helm install' command deploys the software in the Kubernetes cluster.

Installation Sequence

In this section, you will learn about Provisioning Gateway installation sequence:

The installation sequence of Provisioning Gateway is as follows:

Installation Preparation
Namespace Creation: Before creating a namespace, it is important to verify whether any namespace is existing in the system or not. If a namespace does not exist, you must create it. The steps to verify and create a namespace are as follows:
1. Execute the following command to verify the existence of required namespace in system:
  kubectl get namespace
2. If the required namespace does not exist, then execute the following command to create a namespace:
  kubectl create namespace <required namespace>
  
  For example: kubectl create namespace provgw
Note:
This is an optional step. If the required namespace already exists, proceed with next step.

Service Account, Role and RoleBinding Creation: A sample command to create the resources is as follows:

Example: kubectl -n <provgw-namespace> create -f provgw-sample-resource-template.yaml

A sample template to create the resources is as follows:

Note:

You need to update the <helm-release> and <namespace> values with its respective provgw namespace and provgw helm release name.

#
# Sample template start
#
apiVersion: v1
kind: ServiceAccount
metadata:
  name: <helm-release>-serviceaccount
  namespace: <namespace>
---
 
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: <helm-release>-role
  namespace: <namespace>
rules:
- apiGroups:
  - "" # "" indicates the core API group
  resources:
  - services
  - configmaps
  - pods
  - secrets
  - endpoints
  verbs:
  - get
  - watch
  - list
---
 
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: RoleBinding
metadata:
  name: <helm-release>-rolebinding
  namespace: <namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: <helm-release>-role
subjects:
- kind: ServiceAccount                                  
  name:  <helm-release>-serviceaccount
  namespace: <namespace>
 
#
# Sample template end
#

PVC Creation for persistence storage of audit reports: To create a PVC:
1. Create a yaml file with following content:
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: dynamic-auditor-pvc
spec:
  storageClassName: <Please Provide your StorageClass  Name>
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
```
  Note:
  Do not change the name under metadata used in the above template for auditor service.
  
  You should configure the respective/correct storage class under which you want to create PV.
2. Execute the following command to create a PVC:
  kubectl -f <pvc.yaml> -n <namespace>
3. Execute the following command to verify PVC creation:
  kubectl get pvc -n <namespace>

Kubernetes Secret Creation (provgw-ingress-secret) for storing private keys and certificates for https:

Note:

It is a user or operator discretion to create the private keys and certificates for IngressGateway and it is not in the scope of provgw. This section shares only samples to create them.

To create a secret to store private keys and certificate for IngressGateway:

Execute the following command to generate RSA private key:

openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout rsa_private_key
            -out rsa_certificate.crt -config ssl.conf -passin pass:"keystorepasswd" -passout
            pass:"keystorepasswd"

Execute the following command to convert the private key to .pem format:

openssl rsa -in rsa_private_key -outform PEM -out rsa_private_key_pkcs1.pem -passin
            pass:"keystorepasswd" -passout pass:"keystorepasswd"

Execute the following command to generate certificate using the private key:

openssl req -new -key rsa_private_key -out apigatewayrsa.csr -config ssl.conf -passin
            pass:"keystorepasswd" -passout pass:"keystorepasswd"

Note:

You can use ssl.conf to configure default entries along with storage area network (SAN) details for your certificate.

A sample ssl.conf file is given below:

ssl.conf
#ssl.conf
[ req ]
default_bits = 4096
distinguished_name = req_distinguished_name
req_extensions = req_ext
[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_default = IN
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Karnataka
localityName = Locality Name (eg, city)
localityName_default = Bangalore
organizationName = Organization Name (eg, company)
organizationName_default = Oracle
commonName = Common Name (e.g. server FQDN or YOUR name)
commonName_max = 64
commonName_default = localhost
[ req_ext ]
subjectAltName = @alt_names
[alt_names]
IP = 127.0.0.1
DNS.1 = localhost

Execute the following set of commands to create a root Certificate Authority (CA):

openssl req -new -keyout cakey.pem -out careq.pem -config ssl.conf -passin
            pass:"keystorepasswd" -passout pass:"keystorepasswd"

openssl x509 -signkey cakey.pem -req -days 3650 -in careq.pem -out caroot.cer
            -extensions v3_ca -passin pass:"keystorepasswd" echo 1234 >
        serial.txt

Execute the following command to sign the server certificate with root CA private key:

openssl x509 -CA caroot.cer -CAkey cakey.pem -CAserial serial.txt -req -in
            apigatewayrsa.csr -out apigatewayrsa.cer -days 365 -extfile ssl.conf -extensions req_ext
            -passin pass:"keystorepasswd"

Execute the following command to generate ECDSA private key:

openssl ecparam -genkey -name prime256v1 -noout -out ecdsa_private_key.pem

openssl pkcs8 -topk8 -in ecdsa_private_key.pem -inform pem -out
            ecdsa_private_key_pkcs8.pem -outform pem -nocrypt

Execute the following set of commands to generate certificate using the private key:

openssl req -new -key ecdsa_private_key_pkcs8.pem -x509 -nodes -days 365 -out
            ecdsa_certificate.crt -config ssl.conf

openssl req -new -key ecdsa_private_key_pkcs8.pem -out apigatewayecdsa.csr -config
            ssl.conf -passin pass:"keystorepasswd" -passout
        pass:"keystorepasswd"

Execute the following command to sign the server certificate with root CA private key:

openssl x509 -CA caroot.cer -CAkey cakey.pem -CAserial serial.txt -req -in
            apigatewayecdsa.csr -out apigatewayecdsa.cer -days 365 -extfile ssl.conf -extensions
            req_ext -passin pass:"keystorepasswd"

Create a key.txt file by entering any password.
```
Example: echo "keystorepasswd" > key.txt
```
Create a trust.txt file by entering any password.
```
Example: echo "truststorepasswd" > trust.txt
```

Execute the following set of commands to create a Secret:

kubectl create ns NameSpace

kubectl create secret generic ocudr-gateway-secret --from-file=apigatewayrsa.cer
            --from-file=caroot.cer --from-file=apigatewayecdsa.cer
            --from-file=rsa_private_key_pkcs1.pem --from-file=ecdsa_private_key_pkcs8.pem
            --from-file=key.txt --from-file=trust.txt -n
    <Namespace>

provgw-custom-values-1.8.0.yaml File Configuration: This includes repository path, primary and secondary node and Provisioning Gateway details configuration. Other configurations may change depending on the deployment.

Note:
For more details, you can refer to Customizing Provisioning Gateway.
ProvGateway Deployment and Verification: You can deploy Provisioning Gateway either with HELM repository or with HELM tar in Kubernetes cluster. Before deploying Provisioning Gateway, you need to prepare for its installation.
Execute the following command to deploy Provisioning Gateway:

helm install <helm chart> [--version <ProvGw version>] --name <release> --namespace <k8s namespace> -f <provgw-custom-values-1.8.0.yaml>
In the above command:
- <helm chart>: is the name of the chart, which is of the form <helm repo>/provgw.
- <ProvGw version>: is the software version (helm chart version) of the Provisioning Gateway. This is optional. If omitted, the default is 'latest' version available in helm repository.
- <release>: is a user defined name to identify the helm deployment. All pod names, service name, deployment name are prepended by the release name.
- <k8s namespace>: is a user defined name used to identify the kubernetes namespace of the Provisioning Gateway. All the Provisioning Gateway micro services are deployed in this kubernetes namespace.
- <provgw-custom-values-1.8.0.yaml>: is the customized provgw-custom-values-1.8.0.yaml file. For more details, refer to Customizing Provisioning Gateway.
Note:
If helm3 is used, then execute the following command for installation:
helm install -name <release> --namespace <k8s namespace> -f <provgw-custom-values-1.8.0.yaml> <helm chart> [--version <PROVGW version>]

After Provisioning Gateway deployment, you need to verify whether all the services and pods are up and running.

Installation Preparation

In this section, you will learn to prepare for Provisioning Gateway installation.

Installation Preparation includes downloading the required files and loading the files to the system. The steps are:

Download the Provisioning Gateway package (provgw-pkg-1.8.0.tgz) from Oracle Software Delivery Cloud (OSDC).
Untar the Provisioning Gateway package. Execute the following command to untar Provisioning Gateway Package File.
tar -xvf provgw-pkg-1.8.0.0.0.tgz
This command results into provgw-pkg-1.8.0 directory. The directory consists of following:
- ProvGw Docker Images File: provgw-images-1.8.0.tar
- Helm File: provgw-1.8.0.tgz
- Readme txt File: The Readme.txt contains cksum and md5sum of tarballs.
Verify the checksums of tarballs. Execute the following command:
cat Readme.txt
Load the image tarballs to docker images. Execute the following command:
docker load --input provgw-images-1.8.0.tar
Check if all the images are loaded. Execute the following command:
docker images | grep provgw

Tag the docker images to docker registry. Execute the following command:

docker tag <image-name>:<image-tag> <docker-repo>/<image-name>:<image-tag>

Sample Commands:

docker tag provgw/provgw-service:1.8.0 <customer repo>/provgw-service:1.8.0
docker tag provgw/auditor-service:1.8.0 <customer repo>/auditor-service:1.8.0
docker tag provgw/ocingress_gateway:1.8.1 <customer repo>/ocingress_gateway:1.8.1
docker tag provgw/configurationinit:1.4.0 <customer repo>/configurationinit:1.4.0
docker tag provgw/configurationupdate:1.4.0 <customer repo>/configurationupdate:1.4.0
docker tag provgw/ocegress_gateway:1.8.1 <customer repo>/ocegress_gateway:1.8.1

Push the docker images to docker registry. Execute the following command:

docker push <docker-repo>/<image-name>:<image-tag>

Sample Commands:

docker push <customer repo>/provgw-service:1.8.0
docker push <customer repo>/auditor-service:1.8.0
docker push <customer repo>/ocingress_gateway:1.8.0
docker push <customer repo>/configurationinit:1.4.0
docker push <customer repo>/configurationupdate:1.4.0
docker push <customer repo>/ocegress_gateway:1.8.1

Untar Helm Files. Execute the following command:
tar -xvzf provgw-1.8.0.tgz
Download the Provisioning Gateway Custom Template ZIP file from OHC. The steps are as follows:
1. Go to the URL, docs.oracle.com
2. Navigate to Industries->Communications->Cloud Native Core.
3. Click the Provisioning Gateway Custom Template link to download the zip file.
4. Unzip the template to get provgw-custom-configtemplates-1.8.0 file that contains the following:
  - ProvGW_Dashboard.json: This file is used by grafana.
  - provgw-custom-values-1.8.0.yaml: This file is used during installation.

Following are the Provisioning Gateway Images.

Pod	Image
<helm_release_name>-provgw-service	provgw/provgw_service
<helm_release_name>-prov-ingressgateway	provgw/ocingress_gateway provgw/configurationinit provgw/configurationupdate
<helm_release_name>-prov-egressgateway	provgw/ocegress_gateway provgw/configurationinit provgw/configurationupdate
<helm_release_name>-auditor-service	provgw/auditor-service