Using MCI

Constraints

• Currently, MCI can be used only when CCE Turbo clusters 1.21 or later and other Kubernetes clusters whose network type is underlay are created.
• To ensure that the container networks of member clusters do not conflict and that the load balancer instance can connect to the pod IP address, you need to plan the network in advance. If the load balancer of MCI and the target cluster are in different VPCs, you need to enable the network between the VPCs in advance.
• A Service, with both MCI and Multi Cluster Service (MCS) configured, can only be delivered to the cluster where the Service is deployed, the cluster that accesses the Service, and the cluster where the corresponding workload is deployed in MCS.

Preparations

• If no load balancer is available, create one first. For details, see Creating a Dedicated Load Balancer. The load balancer to be created must:
  • Be a dedicated load balancer.
  • Be of the application type (HTTP/HTTPS).
  • Have a private IP address associated.
  • Support cross-VPC access if the load balancer and the member cluster are not in the same VPC.
• MCI provides a unified entry and Layer-7 network access to cross-cluster backends. You need to deploy available workloads (Deployments) and Services in the federation in advance. If no workload or Service is available, create one by referring to Deployments and ClusterIP.
• Set the cluster network type to underlay. For details about the cluster types that support the underlay network, see Configuring the Cluster Network.

Creating an MCI Object

1. Use kubectl to connect to the federation. For details, see Using kubectl to Connect to a Federation.
2. Create and edit the mci.yaml file as follows. For details about the parameters in this file, see Table 1.
   vi mci.yaml

   apiVersion: networking.karmada.io/v1alpha1 
   kind: MultiClusterIngress
   metadata:
     name: nginx-ingress
     namespace: default
     annotations:
       karmada.io/elb.conditions.nginx-svc: 
         '[{ 
             "type": "header", 
             "headerConfig": { 
                 "key":"x-header", 
                 "values": [ 
                 "green" 
                 ] 
             } 
         }]'
       karmada.io/elb.id: 90f9f782-1243-41cc-a57d-6157f6cb85bf
       karmada.io/elb.projectid: 65382450e8f64ac0870cd180d14e684b
       karmada.io/elb.port: "883"              # Controls the port
       karmada.io/elb.health-check-flag.nginx-svc: "on"   # Controls whether to enable health checks for a Service
       karmada.io/elb.health-check-option.nginx-svc: '{"protocol":"TCP"}'   # Controls whether to enable health checks for a Service
   spec:
     ingressClassName: public-elb
     rules:
     - host: demo.localdev.me
       http:
         paths:
         - backend:
             service:
               name: nginx-svc       # Creates a Service named nginx-svc.
               port:
                 number: 8080        # Sets the port to 8080.
           path: /web
           pathType: Prefix

   The structure definition of the MCI object is the same as that of the Ingress of networking.kubernetes.io/v1 except that the backend must be set to a Service created on the UCS console. For details, see ClusterIP.

   

   Parameters in the MCI file must meet the following requirements:

   • apiVersion, kind, and name must be specified.
   • spec cannot contain the TLS and DefaultBackend fields.
   • rules and paths cannot be left blank.
   • The value of host must be a domain name and cannot be an IP address.
   • There must be a backend service specified for a Service, with correct information (such as the port number). Otherwise, the Service cannot be accessed. If you have created an MCI object with incorrect information, update the MCI object by referring to 4.
   • In paths, the more advanced forwarding policies configured for a backend server, the earlier the backend server is configured. (karmada.io/elb.conditions.{service name} indicates the advanced forwarding policy.) The earlier the backend server is configured, the higher the forwarding priority is.

     For example, if two forwarding policies a and b are configured for backend X, and one forwarding policy a is configured for backend Y, X must be configured earlier than Y in paths. Otherwise, traffic that meets both forwarding policies is forwarded to Y with the higher priority.

   • backend cannot contain the resource field.
   • The value of path must be an absolute path. An invalid path is as follows: invalidPathSequences = []string{"//", "/./", "/../", "%2f","%2F"}, invalidPathSuffixes = []string{"/..", "/."}.
   • The value of pathType can be Exact, Prefix, or ImplementationSpecific.
   • By default, a Service name can contain a maximum of 50 characters.

   Table 1 Key parameters

   Parameter	Mandatory	Type	Description
   karmada.io/elb.id	Yes	String	ID of the load balancer associated with MCI. This parameter cannot be left blank. The value ranges from 1 to 32.
   karmada.io/elb.projectid	Yes	String	ID of the project of the load balancer associated with MCI. For details about how to obtain the project ID, see Obtaining a Project ID. The value ranges from 1 to 32.
   karmada.io/elb.port	No	String	Port number of the load balancer associated with MCI. If this parameter is not specified, 80 is used by default. The value ranges from 1 to 65535.
   karmada.io/elb.health-check-flag.{service name}	No	String	Whether to enable health checks. The options are as follows: on: health checks enabled off: health checks disabled If this parameter is left blank, off is used by default. NOTE: The label is karmada.io/elb.health-check-flag.{serviceName}, which is only valid for the corresponding Service.
   karmada.io/elb.health-check-option.{service name}	No	HealthCheck Object	Health check parameters. For details, see HealthCheck. {service name}: name of the Service. NOTE: The following is an example of health check parameter settings: karmada.io/elb.health-check-option.nginx-svc: '{"protocol":"TCP","delay":"5","connect_port":"80","timeout":"1","max_retries":"1","path":"/wd"}' If health check is enabled for annotations, the Service name can contain a maximum of 39 characters.
   karmada.io/elb.conditions.{service name}	No	Array of Condition Object	Advanced forwarding policy. For details, see Condition. {service name}: name of the Service.
   karmada.io/elb.lb-algorithm.{service name}	No	String	Forwarding algorithms. The options are as follows: ROUND_ROBIN: weighted round robin LEAST_CONNECTIONS: weighted least connections SOURCE_IP: source IP hash The default value is ROUND_ROBIN. {service name}: name of the Service.
   karmada.io/elb.keepalive_timeout	No	String	Timeout for an idle client connection, in seconds. If there are no requests reaching the load balancer during the timeout duration, the load balancer will disconnect the connection from the client and establish a new connection when there is a new request. If this parameter is not specified, 60s is used by default. The value ranges from 0s to 4000s
   karmada.io/elb.client_timeout	No	String	Timeout for waiting for a request from a client, in seconds. If this parameter is not specified, 60s is used by default. The value ranges from 1s to 300s.
   karmada.io/elb.member_timeout	No	String	Timeout for waiting for a response from a backend server, in seconds. After a request is forwarded to the backend server, if the backend server does not respond during the timeout duration, the load balancer will stop waiting and return HTTP 504 Gateway Timeout. If this parameter is not specified, 60s is used by default. The value ranges from 1s to 300s.
   ingressClassName	Yes	String	Ingress controller. The value must be public-elb.
   host	No	String	Domain name for accessing the Service. By default, this parameter is left blank, which means the domain name needs to be fully matched. Ensure that the domain name has been registered and licensed. Once a forwarding policy is configured with a domain name specified, you must use the domain name for access.
   backend	No	Backend Object	A backend is a combination of Service and port names. If HTTP and HTTPS requests to MCI match the host and path in the rule, they will be sent to the listed backend. CAUTION: The earlier a backend server is configured in paths, the higher the forwarding priority is. For example, if two forwarding policies a and b are configured for backend X, and one forwarding policy a is configured for backend Y, X must be configured earlier than Y in paths. Otherwise, traffic that meets both forwarding policies is forwarded to Y with the higher priority.
   path	Yes	String	Route path, which is user-defined. All external access requests must match host and path. NOTE: The access path added here must exist in the backend application. Otherwise, the forwarding fails. For example, the default access URL of the Nginx application is /usr/share/nginx/html. When adding /test to the ingress forwarding policy, ensure the access URL of your Nginx application contains /usr/share/nginx/html/test. Otherwise, error 404 will be returned.
   pathType	Yes	String	Path type. The options are as follows: ImplementationSpecific: The URL paths are matched using a regular expression. Exact: The URL path is exactly matched and case-sensitive. Prefix: The URL path is matched by path prefix and is case-sensitive. With this method, the URL path is separated into multiple elements by slashes (/) and the elements are matched one by one. If each element in the URL matches the path, the subpaths of the URL can be routed normally. NOTE: During prefix matching, each element must be exactly matched. If the last element of the URL is the substring of the last element in the request path, no matching is performed. For example, /foo/bar matches /foo/bar/baz but does not match /foo/barbaz. If the URL or request path ends with a slash (/), the slash (/) will be ignored. For example, /foo/bar matches /foo/bar/. See examples of Ingress path matching.

   Table 2 HealthCheck parameters

   Parameter	Mandatory	Type	Description
   protocol	No	String	Protocol used for health checks. The value can be TCP or HTTP. The default value is HTTP.
   connect_port	No	Integer	Port used for health checks. This parameter is optional and its value ranges from 1 to 65535. NOTE: By default, the default service port on each backend server is used. You can also specify a port for health checks.
   delay	No	Integer	The interval between the time when the application is delivered and the time when a health check is started, in seconds. The value ranges from 1 to 50. The default value is 5.
   timeout	No	Integer	Health check timeout duration, in seconds. The value ranges from 1 to 50. The default value is 10.
   path	No	String	Health check request URL. This parameter is valid only when type is set to HTTP or HTTPS. The default value is /. Enter 1 to 80 characters starting with a slash (/). Only letters, digits, hyphens (-), slashes (/), periods (.), percent signs (%), question marks (?), number signs (#), ampersands (&), and extended character sets are allowed.
   max_retries	No	Integer	Maximum number of retries. The value ranges from 1 to 10. The default value is 3.

   Table 3 Condition parameters

   Parameter	Mandatory	Type	Description
   type	Yes	String	Type of the advanced forwarding policy. Currently, only header is supported.
   headerConfig	Yes	headerConfig Object	Advanced forwarding policy object. For details, see headerConfig.

   Table 4 headerConfig parameters

   Parameter	Mandatory	Type	Description
   key	Yes	String	Name of the header parameter. Enter 1 to 40 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed.
   values	Yes	String array	Values of the header parameter. Enter 1 to 128 characters. Asterisks (*) and question marks (?) are allowed, but spaces and double quotation marks are not allowed. An asterisk can match zero or more characters, and a question mark can match 1 character.

3. Run the following command to create an MCI object:

   kubectl apply -f mci.yaml

   Information similar to the following is displayed:

   multiClusterIngress.networking.karmada.io/nginx-ingress created

4. After creating the MCI object, perform operations on it. nginx-ingress is the name of the MCI object.
   • To obtain the MCI object, run kubectl get mci nginx-ingress.
   • To update the MCI object, run kubectl edit mci nginx-ingress.
   • To delete the MCI object, run kubectl delete mci nginx-ingress.

Accessing Services Through MCI

After an MCI object is created, you can access the backends through http://IP:port/path. IP:port indicates the IP address and port number of the load balancer associated with the MCI object, and path indicates the path defined in the MCI object.

You can also set an external domain name in the MCI object so that you can access the load balancer using the domain name and then access backend services.

spec:
   rules:
   - host: www.example.com       # Domain name
     http:
       paths:
       - path: /
         backend:
           serviceName: nginx    # Prepare a Service named nginx.
           servicePort: 80       # Set the port number to 80.

• To access the load balancer using a domain name, you need to point the domain name to the IP address of the load balancer. For details about how to configure record sets for the domain name, see Domain Name Service (DNS).
• If the Service fails to be accessed, see What Can I Do If I Fail to Access a Service Through MCI?