🚀 KubeSphere 3.1.1 is now available as it extends Kubernetes from the cloud to the edge. Read the introduction for 3.1.x → close
  • English
    • English
    • 简体中文
    1. 1.Experience account: demo1 / Demo123
    2. 2.This account is only allowed to view parts of UI
    3. 3.It's recommended that install KubeSphere in your environment
  •  Star
  1. Documentation / 
  2. Project User Guide / 
  3. Application Workloads / 
  4. Routes

Project User Guide

Last updated:
    Edit

    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


    Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.

    Previous : CronJobs
    What’s on this Page