Routes

This document describes how to create, use, and edit a Route on KubeSphere.

A Route on KubeSphere is the same as an Ingress on Kubernetes. You can use a Route and a single IP address to aggregate and expose multiple Services.

Prerequisites

  • You need to create a workspace, a project and two accounts (for example, project-admin and project-regular). In the project, the role of project-admin must be admin and that of project-regular must be operator. For more information, see Create Workspaces, Projects, Accounts and Roles.
  • If the Route is to be accessed in HTTPS mode, you need to create a Secret that contains the tls.crt (TLS certificate) and tls.key (TLS private key) keys used for encryption.
  • You need to create at least one Service. This document uses a demo Service as an example, which returns the Pod name to external requests.

Configure the Route Access Method

  1. Log in to the KubeSphere web console as project-admin and go to your project.

  2. Choose Advanced Settings in Project Settings on the left navigation bar and click Set Gateway on the right.

    Note

    If the access method has been set, you can click Edit and choose Edit Gateway to change the access method.

    set-gateway

  3. In the displayed Set Gateway dialog box, set Access Method to NodePort or LoadBalancer, and click Save.

    Note

    If Access Method is set to LoadBalancer, you may need to enable the load balancer plugin in your environment according to the plugin user guide.

    access-method-nodeport

    access-method-loadbalancer

Create a Route

Step 1: Configure basic information

  1. Log out of the KubeSphere web console, log back in as project-regular, and go to the same project.

  2. Choose Routes in Application Workloads on the left navigation bar and click Create on the right.

    create-route

  3. On the Basic Info tab, configure the basic information about the Route and click Next.

    • Name: Name of the Route, which is used as a unique identifier.
    • Alias: Alias of the Route.
    • Description: Description of the Route.

    basic-info

Step 2: Configure Route rules

  1. On the Route Rules tab, click Add Route Rule.

  2. Select a mode, configure Route rules, click √, and click Next.

    • Auto Generate: KubeSphere automatically generates a domain name in the <Service name>.<Project name>.<Gateway address>.nip.io format and the domain name is automatically resolved by nip.io into the gateway address. This mode supports only HTTP.

      • Paths: Map each Service to a path. You can click Add Path to add multiple paths.

      auto-generate

    • Specify Domain: A user-defined domain name is used. This mode supports both HTTP and HTTPS.

      • HostName: Set a domain name for the Route.
      • Protocol: Select http or https. If https is selected, you need to select a Secret that contains the tls.crt (TLS certificate) and tls.key (TLS private key) keys used for encryption.
      • Paths: Map each Service to a path. You can click Add Path to add multiple paths.

      specify-domain

(Optional) Step 3: Configure advanced settings

  1. On the Advanced Settings tab, select Add Metadata.

  2. Configure annotations and labels for the Route and click Create.

    Note

    You can use annotations to customize the behavior of the Route. For more information, see the official Nginx Ingress controller document.

    add-metadata

Step 4: Obtain the domain name, Service path, and gateway address

  1. Choose Routes in Application Workloads on the left navigation bar and click the name of the Route on the right.

    route-list

  2. Obtain the domain name and Service path in the Rules area and the gateway address in the Details area.

    • If the Route access method is set to NodePort, the IP address of a Kubernetes cluster node is used as the gateway address and the NodePort is displayed after the domain name.

      obtain-address-nodeport

    • If the Route access method is set to LoadBalancer, the gateway address is assigned by the load balancer plugin.

      obtain-address-loadbalancer

Configure Domain Name Resolution

If Auto Generate is selected in the route rule configuration, you do not need to configure domain name resolution and the domain name is automatically resolved by nip.io into the gateway address.

If Specify Domain is selected in the route rule configuration, you need to configure domain name resolution on your DNS server or add <Route gateway address> <Route domain name> to the etc/hosts file of your client machine.

Access the Route

NodePort access method

  1. Log in to a client machine connected to the Route gateway address.

  2. Use the <Route domain name>:<NodePort>/<Service path> address to access the backend Service of the Route.

    access-route-nodeport

LoadBalancer access method

  1. Log in to a client machine connected to the Route gateway address.

  2. Use the <Route domain name>/<Service path> address to access the backend Service of the Route.

    access-route-loadbalancer

Note

If you need to access the Route from outside your private network by using either NodePort or LoadBalancer, depending on your network environment:

  • You may need to configure traffic forwarding and firewall policies in your infrastructure environment so that the gateway address and port number of the Route can be accessed.
  • If Auto Generate is selected in the route rule configuration, you may need to manually edit the Route rules to change the gateway address in the Route domain name to the external IP address of your private network.
  • If Specify Domain is selected in the route rule configuration, you may need to change the configuration on your DNS server or in the etc/hosts file of your client machine so that the domain name can be resolved into the external IP address of your private network.

Check Route Details

Operations

  1. Choose Routes in Application Workloads on the left navigation bar and click the name of the Route on the right.

    route-list

  2. Click Edit Info, or click More and choose an operation from the drop-down list.

    • Edit Info: Edit the basic information of the Route. The Route name cannot be edited.
    • Edit YAML: Edit the YAML configuration file of the Route.
    • Edit Rules: Edit the Route rules.
    • Edit Annotations: Edit the Route annotations. For more information, see the official Nginx Ingress controller document.
    • Delete: Delete the Route and return to the Route list page.

    edit-route

Resource status

Click the Resource Status tab to view the Route rules.

resource-status

Metadata

Click the Metadata tab to view the labels and annotations of the Route.

metadata

Events

Click the Events tab to view the events of the Route.

events