Installing an Open Horizon agent

Before you can deploy a Service Interconnect edge gateway in a Kubernetes namespace, you must install an Open Horizon agent in that namespace. The agent container image is stored in the IBM Hybrid Cloud Mesh (Mesh) instance of the IBM Cloud Container Registry (ICR). Mesh distributes the image from the ICR, removing the need to provide your own image repository.

Before you begin

Ensure that the host machine from which you start the agent installation meets the following requirements:
- The host is a Linux® machine or virtual machine with the AMD64 architecture.
- The host can access the Kubernetes cluster with the kubectl CLI or the OpenShift® Container Platform cluster with the oc CLI. You log in to the cluster as a user with administrative privileges.
To get the installation package for the Open Horizon agent, install and configure the Mesh CLI on the host machine.
Configure a Kubernetes storage class that can be used to satisfy the Open Horizon agent's persistent volume claim (PVC). The volume must be immediately available, and the agent must have read and write access to the volume.
Complete the following steps:
1. View the storage classes that are available for your cluster:
  - In a Kubernetes environment:
```
kubectl get storageclasses
```
  - In an OpenShift Container Platform environment:
```
oc get storageclasses
```
2. Configure your storage class. Use the following storage class examples as a guide:
  - For Red Hat® OpenShift Kubernetes Service (ROKS) and IBM Cloud Kubernetes Service, you might use ibmc-vpc-block-10iops-tier or ibmc-vpc-file-dp2.
    To use the ibmc-vpc-file-dp2 storage class, ensure that the File Storage for VPC driver is installed. See Enabling the IBM Cloud File Storage for VPC add-on.
  - For AWS Elastic Kubernetes Service (EKS), you might use ebs-sc.
    To use the ebs-sc storage class, ensure that the Amazon Elastic Block Store (EBS) driver is installed. See Amazon EBS CSI driver.
  - For Red Hat OpenShift Service on AWS (ROSA), you might use gp2.
  - For Azure Red Hat OpenShift (ARO), you might use managed-csi.
  - For Azure Kubernetes Service (AKS), you might use default.
  - For Google Cloud Google Kubernetes Engine (GKE), you might use standard-rwo.
  - For Red Hat OpenShift Container Platform, you might use rook-cephfs.
  - For all other Kubernetes environments, the available storage classes depend on how Kubernetes is configured. Use the following information to help you configure your storage class:
    - A PVC is created during the installation of the agent and is used by the agent to store data for the agent and cron job. The storage class must satisfy the following requirements:
      
      Supports read and write access to the volume.
      
      Supports ReadWriteOnce or ReadWriteMany access mode.
      
      Is available immediately.
    - If a storage class is used that doesn't exist on the cluster, the PVC doesn't bind to the persistent volume. The agent pod stays in the Pending status and the installation of the agent times out. You can run the following command to view the error message for the specified storage class:
      
      kubectl describe persistentvolumeclaims -n <agent_namespace> openhorizon-agent-pvc

About this task

The latest version of the Open Horizon agent is installed.

For more information about the Open Horizon project, see Open Horizon.

Procedure

Create the namespace where you want to install an Open Horizon agent, if the namespace doesn't already exist.
In a Kubernetes environment:
```
kubectl create namespace <agent_namespace>
```
In an OpenShift Container Platform environment:
```
oc new-project <agent_namespace> 
```
Set the CLI context to the namespace where you install the agent.
In a Kubernetes environment:
```
kubectl config set-context --current --namespace=<agent_namespace>
```
In an OpenShift Container Platform environment:
```
oc project <agent_namespace> 
```
Install an Open Horizon agent:
```
palmctl install openhorizon --name <agent_name> --namespace <agent_namespace> \
  --storage-class <storage_class> -d <install_package_location>
```
<install_package_location> is the folder on the host machine where the agent installation package is extracted to. When the agent is successfully installed, the folder is populated with a script to uninstall the agent. Don't use a temporary folder in case you need to uninstall the agent later.

<agent_name> is the name for your Open Horizon agent. Ensure that the name is meaningful enough to identify the cluster and the namespace where the agent is installed. The name must be unique within your Mesh tenant.

<storage_class> is the storage class that you configured for your Kubernetes environment.
Verify that the Open Horizon agent is installed and running:
In a Kubernetes environment:
```
kubectl get pods -n <agent_namespace>
```
In an OpenShift Container Platform environment:
```
oc get pods -n <agent_namespace>
```
If the agent pod is running, the output looks like this:
```
NAME                     READY   STATUS    RESTARTS   AGE
agent-7459dc47dc-mjf8w   1/1     Running   0          5d19h
```
When the installation script completes successfully, you can select the Open Horizon agent when you are deploying the Service Interconnect edge gateway.

What to do next

Deploy your Red Hat Service Interconnect gateways. See Deploying Service Interconnect edge gateways with the Mesh console and Deploying Service Interconnect edge gateways with the CLI.