Using MCI

Constraints

• MCI is only available in CCE Turbo clusters 1.21 or later.
• 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 in the VPC of the cluster, create a load balancer 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 to route traffic over a private network.
• 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.

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 a 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.health-check-flag: "on"
       karmada.io/elb.health-check-option.nginx-svc: '{"protocol":"TCP"}'
   spec:
     ingressClassName: public-elb
     rules:
     - host: demo.localdev.me
       http:
         paths:
         - backend:
             service:
               name: nginx-svc       # Prepare a federated Service named nginx-svc.
               port:
                 number: 8080        # Set the port number 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 federated 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.

   Table 1 Key parameters

   Parameter	Mandatory	Type	Description
   karmada.io/elb.id	Yes	String	ID of the load balancer associated with the MCI. This parameter cannot be left blank and its value must be 1 to 32 characters long.
   karmada.io/elb.projectid	Yes	String	ID of the project that the load balancer associated with the MCI belongs to. The value must be 1 to 32 characters long.
   karmada.io/elb.port	No	String	Port number of the load balancer associated with the MCI. If this parameter is left blank, 80 is used by default. The value ranges from 1 to 65535.
   karmada.io/elb.health-check-flag	No	String	Whether to enable health check. The options are as follows: on: Enable off: Disable The default value is off.
   karmada.io/elb.health-check-option	No	HealthCheck Object	Health check parameters. For details, see HealthCheck. 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"}'
   karmada.io/elb.conditions.{service name}	No	Array of Condition Object	Advanced forwarding policy. For details, see Condition. {service name}: name of the federated 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 federated Service.
   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, and 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. HTTP (and HTTPS) requests to MCI that match the host and path of the rule are 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	User-defined route path. 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 matching method varies with the Ingress controller. The matching method defined by ingress.beta.kubernetes.io/url-match-mode is used in CCE. Exact: exact matching of the URL, which is case-sensitive. Prefix: prefix matching, which 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.
   connect_port	No	Int	Port used for health checks. The value ranges from 1 to 65535.
   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.
   timeout	No	Integer	Health check timeout duration, in seconds. The value ranges from 1 to 50.
   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.

   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 federated 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).