Installing an operator-managed Event Gateway

Before you begin

Review the pre-installation planning sections in Installing the Event Gateway.

Creating TLS certificates for the Event Gateway

Two options are available for configuring TLS on your operator-managed Event Gateway:

Specify the CA certificate and key for your gateway. When you specify the CA certificate, the Event Endpoint Management operator automatically generates and maintains the server certificate that secures your gateway endpoint.
Specify the server certificate, the server certificate key, and the CA certificate for your gateway.

Creating a self-signed CA certificate with cert-manager

The best way to create and manage TLS certificates is to use cert-manager. Cert-manager creates TLS certificates based on a YAML definition, stores them in Kubernetes secrets, and automatically renews them before they expire. Cert-manager supports integration with external public signers, and can also create self-signed certificates.

On Kubernetes, install the cert-manager community operator. Cert-manager is included on Red Hat OpenShift.

The Event Gateway YAML files that the Event Endpoint Management UI creates includes the definitions of a self-signed certificate and issuer.

If you want to create externally-signed certificates with cert-manager, see the cert-manager documentation.

Generating a CA certificate with OpenSSL

For test and demonstration purposes, you can create a CA certificate and key with the following OpenSSL commands:

openssl genrsa -out tls.key 2048
openssl req -new -x509 -key tls.key -days 730 -out tls.crt

Important: It is recommended to use cert-manager to create and manage your certificates. Do not use this example certificate in production environments.

Supplying your own server certificate and key

If you already have a server certificate that you want to use, then create a Kubernetes secret that contains this certificate, along with its key and CA certificate.

The Subject Alternative Names (SANs) in your certificate must include the path to all the hostnames that are used for your Event Gateway. You can use a wildcard SAN entry, for example: *.<CLUSTER_API> - where <CLUSTER_API> is derived from the URL of your OpenShift Container Platform cluster. If the URL is https://console-openshift-console.apps.clusterapi.com/ then <cluster api> is apps.clusterapi.com.

Create a file called custom-gateway-cert.yaml and paste in the following contents:

apiVersion: v1
data:
  ca.crt: <base64 encoded CA certificate>
  tls.crt: <base64 encoded server certificate>
  tls.key: <base64 encoded key>
metadata:
  name: custom-gateway-cert
kind: Secret
type: kubernetes.io/tls

Apply the file to create the Kubenetes secret in the same namespace where your Event Gateway is to be deployed:
```
kubectl -n <namespace> apply -f custom-gateway-cert.yaml
```

Operator-managed Event Gateway installation steps

In the navigation pane, click Administration > Event Gateways.
Click Add gateway.
Select the Operator-managed deployment tile, then click Next.
Provide the configuration details for your gateway, then click Next.
- Gateway group: Create or specify an existing gateway group for your new gateway.
- Gateway ID: Provide an ID for your new gateway that is unique within the gateway group.
- Replicas: The number of Kubernetes replicas of the gateway pod to create.
Copy the generated custom resource YAML to two separate files:
- gateway_cr_original.yaml
- gateway_cr.yaml
Important: Keep gateway_cr_original.yaml in a safe location and do not edit it. To remove write permissions to avoid accidental updates to this file, you can run chmod a-w gateway_cr_original.yaml.
Update the gateway_cr.yaml file and set spec.license.accept to true.
Configure TLS certificates. The following TLS configuration options are available:
- Use the default self-signed issuer and certificate that is specified in the gateway_cr.yaml file.
  
  Note: The default certificate and issuer have names that are generated from the gateway group and ID that you specified in step 4.
- Modify the default self-signed issuer and certificate specifications in the gateway_cr.yaml file to suit your requirements. For example, you might want to update the specification in the following scenarios:
  - If you plan to install multiple Event Gateway instances and want to use the same certificate and issuer for all of them, then remove <gateway id> from the issuer and certificate names, and from spec.template.pod.spec.containers[egw].env[GATEWAY_TRUST_PEM] (which is set to the certificate name).
  - If you already have a cert-manager issuer or ClusterIssuer that you want to use, then delete the issuer specification and update the certificate specification to refer to your existing issuer.
- If you created a Kubernetes secret from your own CA and server certificate, then update gateway_cr.yaml as follows:
  
  a. Delete the Issuer and Certificate sections:
```
 apiVersion: cert-manager.io/v1
 kind: Issuer
 ...
 ---
 apiVersion: cert-manager.io/v1
 kind: Certificate
 ...
```
  b. Update the spec.template.pod.spec.containers[egw].env[GATEWAY_TRUST_PEM] section to refer to the CA certificate in your Kubernetes secret:
```
      - name: GATEWAY_TRUST_PEM
        valueFrom:
          secretKeyRef:
            key: ca.crt
            name: "<Kubernetes secret that contains your certificate>"     
```
  c. Configure the spec.tls section to refer to your server certificate:
```
 spec:
   tls:
    secretName: <Kubernetes secret that contains your certificate>
    key: tls.key
    serverCertificate: tls.crt
    caCertificate: ca.crt
```
Replace any other placeholder variables in the YAML.
Create a backup of the updated gateway_cr.yaml file, in addition to the gateway_cr_original.yaml file.
To install the Event Gateway through the OpenShift Container Platform web console, complete the following steps:

a. Log in to the OpenShift Container Platform web console using your login credentials.

b. Click the + (Quick create) icon in the upper-right.

c. Select Import YAML.

d. Set Project to the namespace where you want to install the Event Gateway.

e. Paste in the contents of your updated gateway_cr.yaml file.

h. Click Create to start the Event Gateway installation process.
To install the Event Gateway by using the CLI, run the following commands:

a. If you are deploying an operator-managed gateway on other Kubernetes platforms, then add the spec.endpoints[] section to your gateway_cr.yaml file:
```
  spec:
    endpoints:
      - name: gateway
        host: <gateway endpoint>
```
For more information about the endpoints property, see Configuring ingresses.

b. Apply the gateway_cr.yaml file in your Kubernetes environment by using the kubectl command. For example:
```
  kubectl -n <gateway namespace> apply -f gateway_cr.yaml
```
Return to the Event Gateways page to monitor the status of the new Event Gateway. When the gateway is registered, the status reports Running.
Complete the gateway verification checks.