🚀 KubeSphere 3.2.1 was released on Dec 20, it brought enhancements and better user experience. Read the release notes for 3.2.1 → close
  • English
    • English
    • 简体中文
    1. 1.Experience account: demo1 / Demo1234
    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 users (for example, project-admin and project-regular). In the project, the role of admin must be project-admin and that of project-regular must be operator. For more information, see Create Workspaces, Projects, Users 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. Select Gateway Settings in Project Settings on the left navigation bar and click Enable Gateway on the right.

    3. In the displayed dialog box, set Access Mode to NodePort or LoadBalancer, and click OK.

      Note

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

    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.

    3. On the Basic Information 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.

    Step 2: Configure routing rules

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

    2. Select a mode, configure routing 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.

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

        • Domain Name: 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.

    (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.

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

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

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

      • If the Route access mode 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.

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

    Configure Domain Name Resolution

    If Auto Generate is selected in the routing 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 routing 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 mode

    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.

    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.

    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 routing rule configuration, you may need to manually edit the routing 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 routing 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.

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

      • Edit YAML: Edit the YAML configuration file of the Route.
      • Edit Routing 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.

    Resource status

    Click the Resource Status tab to view the Route rules.

    Metadata

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

    Events

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

    Receive the latest news, articles and updates from KubeSphere


    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