Deployment with OpenShift

This guide describes how to create a Kubernetes cluster by using OpenShift. For a production-ready cluster, follow the official OpenShift guides and best practices.

This guide contains instructions on how to:

1. Setup cluster with ROSA CLI.
2. Configure the Ingress controller for IED onboarding.

Setup of OpenShift on AWS

1. Download the oc CLI.
2. Download the ROSA CLI (Red Hat OpenShift Service on AWS).

Follow this guide to setup a ROSA Cluster.

Configure kubectl

Add context to local kube config file with oc cli:

oc login https://<hostname>:6443 --username <user> --password <password>

Verify the Installation

After a few minutes, the installation should be complete; verify the installation by listing the available nodes:

oc get nodes

Generate Certificates

You can either use custom TLS certificates that are used to terminate TLS traffic, or you can create self-signed certificates using openssl commands. To create self-signed certificates, you need to copy the files mentioned below to a folder on your machine, make the script executable and run it specifying the required IP address or FQDN of the host. For more information, see the TLS section.

IP BasedDNS Based

Generate certificate by providing IP address

In the following, we will create the required certificates using openssl with sample data.

Generate certificates using the `gen_with_ca-IP.sh` script

./gen_with_ca-IP.sh <ip of host>

gen_with_ca_IP.sh

#!/bin/bash

path=$(dirname "$0")

IEM_IP=$1

mkdir -p "${path}"/out

openssl genrsa -out "${path}"/out/myCA.key 4096

openssl req -x509 -new -nodes -key "${path}"/out/myCA.key -sha256 -days 825 -out "${path}"/out/myCA.crt -config "${path}"/ca.conf

openssl genrsa -out "${path}"/out/myCert.key 4096

openssl req -new -key "${path}"/out/myCert.key -out "${path}"/out/myCert.csr -subj "/C=DE/ST=Dummy/L=Dummy/O=Dummy/CN=$IEM_IP" -config <(cat "${path}"/cert.conf <(printf "\\n[alt_names]\\nIP.1=%s" "${IEM_IP}"))

openssl x509 -req -in "${path}"/out/myCert.csr -CA "${path}"/out/myCA.crt -CAkey "${path}"/out/myCA.key -CAcreateserial -out "${path}"/out/myCert.crt -days 825 -sha256 -extfile <(cat "${path}"/cert-ext.conf <(printf "\\n[alt_names]\\nIP.1=%s" "${IEM_IP}"))

cat "${path}"/out/myCert.crt "${path}"/out/myCA.crt > "${path}"/out/certChain.crt

rm "${path}"/out/myCert.csr "${path}"/out/myCA.srl

cp "${path}"/out/myCert.crt "${path}"/out/certChain.crt "$(pwd)"/

ca.conf

basicConstraints = CA:TRUE
keyUsage = cRLSign, keyCertSign
[req]
distinguished_name = req_distinguished_name
prompt = no

[req_distinguished_name]
C   = DE
ST  = Dummy
L   = Dummy
CN  = My Personal Root CA

cert.conf

IEM = ""

[req]
default_md = sha512
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
default_keyfile    = myCert.key
x509_extensions    = v3_ca
prompt             = no
authorityKeyIdentifier=keyid,issuer
distinguished_name = req_distinguished_name
req_extensions     = req_ext


[req_distinguished_name]
C=DE
ST=Dummy
L=Dummy
O=Dummy
CN=localhost

[req_ext]
subjectAltName = @alt_names

[v3_ca]
subjectAltName = @alt_names

cert-ext.conf

basicConstraints = CA:FALSE
nsCertType = server
nsComment = "My Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

Generate certificate by providing DNS name

In the following, we will create the required certificates using openssl with sample data.

Generate certificates using the `gen_with_ca-DNS.sh` script

./gen_with_ca-DNS.sh <name of host>

gen_with_ca_DNS.sh

#!/bin/bash

path=$(dirname "$0")

IEM_NAME=$1

mkdir -p "${path}"/out

openssl genrsa -out "${path}"/out/myCA.key 4096

openssl req -x509 -new -nodes -key "${path}"/out/myCA.key -sha256 -days 825 -out "${path}"/out/myCA.crt -config "${path}"/ca.conf

openssl genrsa -out "${path}"/out/myCert.key 4096

length=${#IEM_NAME}
if [ $length \> 63 ]
then 
    echo "WARNING: string too long for CN, will be adjusted"
    arrCN=(${IEM_NAME//./ })
    IEM_NAME_CN=*.${arrCN[-3]}.${arrCN[-2]}.${arrCN[-1]}
    echo "new CN $IEM_NAME_CN"
else 
    IEM_NAME_CN=$IEM_NAME
fi

openssl req -new -key "${path}"/out/myCert.key -out "${path}"/out/myCert.csr -subj "/C=DE/ST=Dummy/L=Dummy/O=Dummy/CN=$IEM_NAME_CN" -config <(cat "${path}"/cert.conf <(printf "\\n[alt_names]\\nDNS=%s" "${IEM_NAME}"))

openssl x509 -req -in "${path}"/out/myCert.csr -CA "${path}"/out/myCA.crt -CAkey "${path}"/out/myCA.key -CAcreateserial -out "${path}"/out/myCert.crt -days 825 -sha256 -extfile <(cat "${path}"/cert-ext.conf <(printf "\\n[alt_names]\\nDNS=%s" "${IEM_NAME}"))

cat "${path}"/out/myCert.crt "${path}"/out/myCA.crt > "${path}"/out/certChain.crt

rm "${path}"/out/myCert.csr "${path}"/out/myCA.srl
cp "${path}"/out/myCert.crt "${path}"/out/certChain.crt "$(pwd)"/

ca.conf

basicConstraints = CA:TRUE
keyUsage = cRLSign, keyCertSign
[req]
distinguished_name = req_distinguished_name
prompt = no

[req_distinguished_name]
C   = DE
ST  = Dummy
L   = Dummy
CN  = My Personal Root CA

cert.conf

IEM = ""

[req]
default_md = sha512
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
default_keyfile    = myCert.key
x509_extensions    = v3_ca
prompt             = no
authorityKeyIdentifier=keyid,issuer
distinguished_name = req_distinguished_name
req_extensions     = req_ext


[req_distinguished_name]
C=DE
ST=Dummy
L=Dummy
O=Dummy
CN=localhost

[req_ext]
subjectAltName = @alt_names

[v3_ca]
subjectAltName = @alt_names

cert-ext.conf

basicConstraints = CA:FALSE
nsCertType = server
nsComment = "My Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

OpenShift default certificates

With the default installation of OpenShift, an Ingress Controller is deployed directly. The Ingress Controller is pre-configured with certificates. It may therefore not be necessary to create self-signed certificates. If TLS should be terminated directly in the application check how to Terminating TLS through building API Gateway.

Create namespace

Create a namespace for installation of the IEM Pro.

kubectl create namespace <namespace>

Install IEM Pro with provisioning CLI

Use the following guide to install the IEM Pro.

Use the following parameter specific for the OpenShift installation:

Parameter	Explanation	Value
--set global.additionalSpec.enabled	This add fsGroup: 10001 and fsGroupChangePolicy: Always to the deployments	false
--set global.security.runAsUser	Depending on the SCC OpenShift does not allow to run more then one process with the same user A Guide to OpenShift and UIDs	""
--set global.security.init.runAsUser	Depending on the SCC OpenShift does not allow to run more then one process with the same user A Guide to OpenShift and UIDs	""
--set kong.securityContext	Do not set Security Context, as this is set automatically by OpenShift.	"null"

This command shows a minimal configuration to install the IEM Pro on OpenShift (for further configuration see: Deploying IEM):

ieprovision install <config> \
  --set global.hostname="<hostname>" \
  --set global.storageClass="<storageClass>" \
  --set global.storageClassPg="<storageClass>" \
  --set global.additionalSpec.enabled=false \
  --set global.security.runAsUser=""  \
  --set global.security.init.runAsUser="" \
  --set kong.securityContext="null"

Configure Ingress for DNS based setup

For configuring the ingress rule correctly you need to get the service name of the Industrial Edge Gateway.

Get the service name of Industrial Edge Gateway:

kubectl get svc --no-headers -o custom-columns=":metadata.name" -n <namespace> | grep gateway-proxy

# Output:

ieb14c-gateway-proxy

1. Two ways to configure the TLS termination are possible. To terminate TLS at the existing Ingress from OpenShift the Edge example can be used. In case the TLS termination should be done at the IE Gateway the Passthrough example can be used. To replace the default Ingress certificate from OpenShift see Replacing the default ingress certificate.

   TLS termination at IngressTLS termination at IE Gateway

   Example TLS termination at Ingress

   ingress_edge.yaml

   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     name: iem-route
     namespace: iem
   spec:
     host: <hostname>
     path: /
     to:
       kind: Service
       name: <gateway>
       weight: 100
     port:
       targetPort: kong-proxy
     tls:
       termination: edge
     wildcardPolicy: None
   

   Insert a value for the host according the value set for hostname in the template file and service name of Industrial Edge Gateway in the ingress ressource definition file. To use certificates other than the default ingress certificates, see the OpenShift documentation.

   Example TLS termination at IE Gateway

   ingress-passthrough.yaml

   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     name: iem-route
     namespace: iem
   spec:
     host: <hostname>
     to:
       kind: Service
       name: <gateway>
       weight: 100
     port:
       targetPort: kong-proxy-tls
     tls:
       termination: passthrough
     wildcardPolicy: None
   

   Insert a value for the host according the value set for hostname in the template file and service name of Industrial Edge Gateway in the ingress ressource definition file. Add the certificate created above to the Industrial Edge Gateway (see Terminating TLS through building API Gateway).

   Create Kubernetes secret within the same namespace as the IEM deployment

   kubectl create secret -n <namespace> tls kongcert --key <path to key> --cert <path to cert>
   

   Use the following provision-cli flags to use the secret

   --set kong.env.SSL_CERT=/etc/secrets/kongcert/tls.crt \
   --set kong.env.SSL_CERT_KEY=/etc/secrets/kongcert/tls.key \
   --set kong.secretVolumes.kong-proxy-tls=kongcert
   

2. Deploy the ingress rule:

kubectl apply -f ingress.yaml

Configuration of HA Proxy

If HA Proxy is used as Ingress Controller, the default timeout settings must be adjusted. Otherwise the transfer of large files (such as Apps or Firmware) may be interrupted.

ha proxy setup

kind: Route
apiVersion: route.openshift.io/v1
metadata:
  annotations:
    haproxy.router.openshift.io/timeout: 10m