Installing the Manager on other Kubernetes platforms

The following sections provide instructions about installing Event Endpoint Management on Kubernetes platforms that support the Red Hat Universal Base Images (UBI) containers.

Before you begin

Ensure that you have set up your environment according to the prerequisites.
Ensure that you have planned for your installation, such as preparing for persistent storage, and considering security options.
Obtain the connection details for your Kubernetes cluster from your administrator.

Create a namespace

Create a namespace for Event Endpoint Management. For more information about namespaces, see the Kubernetes documentation.

Ensure that you use a namespace that is dedicated to a single deployment of Event Endpoint Management. A dedicated namespace is required because Event Endpoint Management uses network security policies to restrict network connections between its internal components. A single namespace per instance also allows for finer control of user accesses.

Important: Do not use any of the initial or system namespaces to install Event Endpoint Management. For example: default, kube-node-lease, kube-public, and kube-system.

Add the Helm repository

Before you can install the Event Endpoint Management operator and use it to create instances of the Event Manager, add the IBM Helm repository to your local repository list. The Helm repository provides access to the Event Endpoint Management Helm chart packages that install the operator on your cluster.

To add the IBM Helm repository to the local repository list, run the following command:

helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm

Install the Event Endpoint Management operator

Review the Event Endpoint Management operator requirements, including resource requirements and the required cluster-scoped permissions.

Important: You can install only one version of the Event Endpoint Management operator on a cluster. Installing multiple versions on a single cluster is not supported due to possible compatibility issues as they share the same Custom Resource Definitions (CRDs), making them unsuitable for coexistence.

Install the CRDs

Before you install the operator, the Custom Resource Definitions (CRDs) for Event Endpoint Management must be installed. To install the CRDs, run the following command:

helm install \
   <release-name> ibm-helm/ibm-eem-operator-crd \
   -n <namespace>

Where:

<release-name> is the name that you provide to identify your Event Endpoint Management CRD Helm install.
<namespace> is the name of the namespace where you want to install the helm release for CRD management.

For example, to install the operator CRD Helm chart in the eem-crds namespace run the command as follows:

helm install eem-crds ibm-helm/ibm-eem-operator-crd -n eem-crds

Choose the operator installation mode

Before you install the Event Endpoint Management operator, decide whether you want the operator to:

Manage instances in any namespace.

To use this option, set watchAnyNamespace: true when you install the operator. The operator is deployed into the specified namespace, and will be able to manage instances of the Event Manager in any namespace.
Manage only instances in a single namespace.

This is the default option: if watchAnyNamespace is not set, then it defaults false. The operator is deployed into the specified namespace, and will be able to manage only instances of the Event Manager in that namespace.

Note: If the Kubernetes service Domain Name System (DNS) domain for your cluster is not cluster.local, set kubernetesServiceDnsDomain as required.

Important: Mixing installation modes is not supported due to possible conflicts. If one operator is installed to manage all namespaces and another to manage a single namespace on the same cluster, it can result in conflicts and attempts to control the same CustomResourceDefinition resources.

Installing the operator

To install the operator, run the following command:

helm install \
   <release-name> ibm-helm/ibm-eem-operator \
   -n <namespace> \
   --set webhook.create=<true/false> \
   --set kubernetesServiceDnsDomain=<your.k8s.svc.dns.domain>  \
   --set watchAnyNamespace=<true/false>

Where:

<release-name> is the name that you provide to identify your operator.
<namespace> is the name of the namespace where you want to install the operator.
webhook.create=<true/false> determines whether the validating webhook is deployed (default is true if not specified).
kubernetesServiceDnsDomain=<your.k8s.svc.dns.domain> specifies the domain that is used when the operator generates certificates. The value that you enter is used as the suffix on hosts in the dnsNames section of the certificate. The default is cluster.local.
watchAnyNamespace=<true/false> determines whether the operator manages instances of the Event Manager in any namespace or only a single namespace (default is false if not specified).

Set to true for the operator to manage instances in any namespace, or do not specify if you want the operator to manage only instances in a single namespace.

For example, to install the operator on a cluster where it manages all instances of the Event Manager, run the command as follows:

helm install \
   eventendpointmanagement ibm-helm/ibm-eem-operator\
   -n "my-namespace" \
   --set watchAnyNamespace=true \
   --set webhook.create=false

For example, to install the operator that manages Event Manager instances in only the my-eventendpointmanagement namespace, and with the defaults for all other options, run the command as follows:

helm install eventendpointmanagement ibm-helm/ibm-eem-operator -n "my-eventendpointmanagement"

Checking the operator status

To check the status of the installed operator, run the following command:

kubectl get deploy ibm-eem-operator -n <namespace>

Where:

<namespace> is the name of the namespace where the operator is installed.

A successful installation returns a result similar to the following with 1/1 in the READY column:

NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
ibm-eem-operator                1/1     1            1           7d4h

Install an Event Manager instance

Instances of the Event Manager can be created after the Event Endpoint Management operator is installed. If the operator was installed to manage a specific namespace, then it can be used only to manage instances of the Event Manager in that namespace. If the operator was installed to manage all namespaces, then it can be used to manage instances of the Event Manager in any namespace, including namespaces created after the operator was deployed.

When you install an instance of the Event Manager, ensure that you are using a namespace that an operator is managing.

Creating an image pull secret

Before you install an Event Manager instance, create an image pull secret that is called ibm-entitlement-key in the namespace where you want to create an instance of the Event Manager. The secret enables container images to be pulled from the registry.

Obtain an entitlement key from the IBM Container software library.
Click Entitlement keys in the navigation on the left, and click Add new key, or if you have an existing active key available, click Copy to copy the entitlement key to the clipboard.
Create the secret in the Event Manager namespace as follows.

Name the secret ibm-entitlement-key, use cp as the username, your entitlement key as the password, and cp.icr.io as the docker server:
```
kubectl create secret docker-registry ibm-entitlement-key --docker-username=cp --docker-password="<your-entitlement-key>" --docker-server="cp.icr.io" -n "<target-namespace>"
```

Installing an instance by using the CLI

To install an instance of the Event Manager from the command line, you must first prepare an EventEndpointManagement custom resource configuration in a YAML file.

A number of sample configuration files are included in the Helm chart package to base your deployment on. The sample configurations range from a smaller deployment for nonproduction development or general experimentation to a large deployment ready to handle a production workload.

The sample configurations are also available in GitHub, where you can select the GitHub tag for your Event Endpoint Management version, and then go to /cr-examples/eventendpointmanagement/kubernetes to access the samples for the Kubernetes platforms that support the Red Hat Universal Base Images (UBI) containers.

Note: If you are experimenting with Event Endpoint Management for the first time, the Quick start sample is the smallest and simplest example that can be used to create an experimental deployment. For a production setup, use the Production sample configuration.

More information about these samples is available in the planning section. You can base your deployment on the sample that most closely reflects your requirements and make customizations as required.

Important: Ensure that the spec.license.accept field in the custom resource YAML is set to true, and that the correct values are selected for the spec.license.license and spec.license.use fields before you deploy the Event Manager instance. These values are used for metering purposes and might result in inaccurate charging and auditing if set incorrectly. For more information about the available options, see the licensing reference.

When you modify the sample configuration, ensure that the following fields are updated based on your requirements:

The spec.license.accept field in the custom resource YAML is set to true.
The correct values are selected for the spec.license.use, spec.license.license, and spec.license.metric fields before you deploy an Event Manager instance. For information about the right values for your deployment, see the licensing reference.
The manager.storageSpec.type field is updated as ephemeral or persistent-claim based on your requirements. See configuring to select the correct storage type and other optional specifications such as storage size, root storage path, and secrets.
The manager.tls.caSecretName or manager.tls.secretName field is updated based on your requirements. If neither is specified, self-signed certificates are used. See configuring TLS.

The spec.manager.endpoints[] section must contain entries for the service endpoints.

For example:

apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
# ...
spec:
  manager:
    endpoints:
      - name: ui
        host: my-eem-ui.mycluster.com
      - name: gateway
        host: my-eem-gateway.mycluster.com
      - name: admin
        host: my-eem-admin.mycluster.com
      - name: server
        host: eem.my-eem-server.mycluster.com

The value that is supplied in endpoints[server].host must start with eem.

To deploy an Event Manager instance, run the following command:

Apply the configured EventEndpointManagement custom resource to your target namespace:

kubectl apply -f <custom-resource-file-path> -n <target-namespace>

For example:

kubectl apply -f production.yaml -n my-namespace

Wait for the installation to complete.