Registering a remote Kubernetes cluster

Edit online

You must register a remote Kubernetes cluster to your team space on IBM® DevOps Test Hub (Test Hub) before you add the remote cluster to your project.

Before you begin

You must have completed the following tasks:

Verified that the Kubernetes cluster that you want to use is a supported one by referring to the OS, platform, and containers that are specified for Test Hub in System Requirements for DevOps Test Hub 2026.06 (11.0.9).
Kept a suitable kubeconfig file with access to the remote Kubernetes cluster in a folder on the computer that you want to use to access an instance of Test Hub.
Ensured that you are assigned a role as a Member or Project Creator in the team space. See Managing members and their roles in a team space.
Ensured that you are assigned a role as a Project Owner or Tester in the project. See Managing access to the server projects.

Procedure

Log in to Test Hub.
The Projects page of the initial team space is displayed.
Click Infrastructure > Agents and Intercepts in the navigation pane of the team space.

The Agents and Intercepts page is displayed.
Click Add new > Add new cluster.

The New cluster dialog is displayed.
Perform the following steps to add the kubeconfig file:
1. Click Browse, and locate the kubeconfig file of the Kubernetes cluster that you want to add.
2. Select the kubeconfig file, and then click Open.
  
  The name of the kubeconfig file that you selected is displayed along with the address of the Kubernetes cluster that is specified in the file.
3. Click Next.
The address of the Kubernetes cluster that is configured in the kubeconfig file is displayed in the Address field.
Note: You can change the address of the Kubernetes cluster if it is different from the address in the kubeconfig file.
Perform the following steps to add a namespace and name for the cluster:
1. Enter the namespace of the cluster in the Namespace field.
2. Enter a name for the cluster in the Name field.
  
  The name helps you to identify the cluster.
3. Click Next.

Perform the following steps to add the ingress details of the cluster:

Select the ingress type of the cluster from the Ingress type list.

You can select the ingress type from the following options that are displayed:


Option	Description	Result
None	When selected specifies that no ingress type is configured for the remote Kubernetes cluster.	You can run any of the supported tests on the remote cluster but not on the remote agents.
NGINX	When selected specifies that NGINX is configured as the ingress type for the remote Kubernetes cluster.	You can run any of the supported tests on the remote cluster or on any of the remote agents.

Enter the ingress host pattern of the cluster in the Ingress host pattern field.

The DNS used by a computer that runs a client application (such as a static agent) or the HTTP proxy that routes traffic to the virtual service needs to resolve such hostnames to the IP address of the ingress domain.

For example, if the IP of the remote cluster is 12.12.12.123, then you must enter the ingress host pattern as *.12.12.12.123.nip.io

The Unique ID of the virtual service is prefixed to the ingress hostname when virtual services are routed from the Test Hub cluster.
Enter the name of the secret in the remote namespace, which contains the certificate information.

You must have created the secret and named it following the naming conventions per the Kubernetes guidelines. The certificate that you create is a wildcard certificate which contains the Ingress host pattern of the Kubernetes cluster. This wildcard certificate ensures that the client applications can trust the virtual services.
Note: If a secret name is not provided then the default certificate that is provided by NGINX is used, which might cause issues to authenticate the virtual service by the client applications.
Click Next.

Optionally, perform the following steps to enter the code snippets for nodeSelectors and tolerations, if applicable for the remote cluster:
1. Enter the code snippet for nodeSelectors in a yaml format in the Node selectors field.
2. Enter the code snippet for tolerations in a yaml format in the Tolerations field.
3. Select the Copy pull secret to the cluster checkbox, if it is not already selected.
  
  Note: The remote Kubernetes cluster pulls the secret to access the Test Hub image registry which is the same registry that you used to install Test Hub. The remote Kubernetes cluster must be able to access the image registry at test runtime.
4. Click Register.
The remote cluster is added to the team space and is displayed with the icon in the Type column on the Agents and Intercepts page. You can identify the cluster with its name in the Agents column.
Note: The Projects column does not display any projects that are associated with the cluster yet.

Results

You have registered a remote Kubernetes cluster with your team space on Test Hub.

What to do next

You must add the remote cluster to your project in your team space before you use the remote cluster as a location to run test assets or resources in your project. See Adding a remote Kubernetes cluster to a project.