Configuring external client access by using the Mesh CLI

Use the palmctl CLI to connect client applications that run on non-Kubernetes infrastructure to services over the Mesh network segment.

Before you begin

Note:

These instructions use the example of a single-node MicroK8s cluster that is installed on a VM. However, the instructions also apply to multi-node and managed Kubernetes clusters.

For more information about supported Kubernetes distributions, see Supported platforms and software.
Ensure that the following prerequisites are completed:
  1. MicroK8s is installed on a separate VM in the same VPC or local network as the external client. See Getting started with MicroK8s.
  2. MetalLB is installed in the MicroK8s cluster, in the metallb-system namespace.

    MetalLB provides load-balancer services for bare metal and on-premises environments such as VMs running MicroK8s. To enable the MetalLB add-on for MicroK8s, see Enabling MetalLB for MicroK8s. For other Kubernetes distributions, see Installing MetalLB.

    To enable Mesh to manage the necessary MetalLB resources, complete the following steps:
    1. Create a Kubernetes role in the metallb-system namespace that grants permission to manage MetalLB resources such as address pools.
    2. Bind this role to a service account in the namespace on the MicroK8s cluster where you install the Mesh gateway.
    For an example of the configuration commands that you might use, see Example: Granting Mesh access to MetalLB.
  3. A set of IP addresses is reserved on the local network for the primary network interface of the MicroK8s VM.

    For cloud environments, the primary network interface of the VM might need to be configured to accept these IP addresses, which are used to expose services.

About this task

An external client is a client application that operates outside of a Kubernetes cluster but can connect to services within a Mesh network segment. External clients can operate in non-Kubernetes environments such as VMs, mainframes, and bare metal servers.

For on-premises environments, the equivalent to a virtual private cloud (VPC) might be, for example, a VLAN or subnet.

Procedure

  1. Register the MicroK8s cluster in Mesh.
    See Registering infrastructure resources by using the Mesh CLI.
  2. Install the Open Horizon agent on the MicroK8s cluster.
    See Installing an Open Horizon agent.

    After the Open Horizon agent is installed, the Service Interconnect edge gateway is automatically registered in Mesh.

  3. Create a VPC by using the palmctl create command.
    For example, run a command like this:
    cat << EOM | palmctl create vpc --cloud-name "<cloud_name>" -f -
name: <vpc_name>
type: IBMVPC
location_id: <vpc_location_id>
EOM
  4. Create a single-node Kubernetes cluster in the VPC.
    1. Get the ID of the VPC.
      For example, run a command like this:
      IBM_VPC_ID=$(palmctl get vpc --cloud-name "<cloud_name>" --name "<vpc_name>" | yq .resource_id)
    2. Create the cluster.
      For example, run a command like this:
      cat << EOM | palmctl create cluster --cloud-name "<cloud_name>" -f -
name: <eca_cluster_name>
type: SINGLE-NODE-K8S
is_multi_zone: false
location_id: <location_id>
deployed_in_vpc: $IBM_VPC_ID
auto_discover: false
EOM
  5. Configure the gateway that was registered in step 2. Configure the gateway for external client access and specify an IP address pool.
    For example, run a command like this:
    cat << EOF | palmctl patch gateway --name "<eca_gateway_name>" -f -
external_client_access: lb-single-node-ip-pool
ip_address_pool: <ip_address_pool_value>
EOF
    You can enter the pool of IP addresses formatted as a hyphenated range or in CIDR notation. To specify multiple ranges, separate them with commas. For example:
    ip_address_pool: 192.0.2.1-192.0.2.3, 203.0.113.7/8
  6. Deploy the gateway in the cluster that was created in step 4.
    1. Get the ID of the gateway.
      Run a command like this:
      GW_ID=$(palmctl get gateway --name "<eca_gateway_name>" | yq .resource_id)
    2. Create the namespace where you want to deploy the gateway, if one does not exist already.
      For example, run a command like this:
      cat << EOM | palmctl create namespace --cloud-name "<cloud_name>" --cluster-name "<eca_cluster_name>" -f -
name: <eca_namespace_name>
unmanaged: true
EOM
    3. Set the network segment ID and gateway ID for the namespace.
      For example, run a command like this:
      cat << EOM | palmctl patch namespace --name "<eca_namespace_name>" --cloud-name "<cloud_name>" --cluster-name "<eca_cluster_name>" -f -
network_segment_id: <network_segment_id>
gateway_id: $GW_ID
unmanaged: false
EOM

What to do next

Use the Topology view in the Mesh console to monitor traffic and visualize relationships between the external client and the other Mesh resources in the network segment.

On the Gateway details page in the Mesh console, view the service entry points that are assigned to services at the gateway.