Use

Meshlet#

A meshlet is a logical entity, which can be a client that uses services provided by other meshlets, or a server that provides services for other meshlets to use, or both.

Define a Meshlet#

Define a Meshlet via CR:

apiVersion: ext.burningxflame.github.com/v1
kind: Meshlet
metadata:
  namespace: <ns>
  name: <name>
spec:
  # As a client using services provided by other meshlets.
  # Declare the services this meshlet uses.
  # Used for access control.
  # Optional.
  client:
    - namespace: <ns>
      meshlet: <meshlet-name>
      service: <service-name>
  # As a server providing services for other meshlets to use.
  # Optional.
  server:
    # Declare the label selector used to identify Pods that provide the following services.
    selector:
      <key>: <value>
    # Declare the services this meshlet provides.
    services:
      - name: <service-name>
        # Max number of concurrent connections for this service per pod.
        # Optional. Default to no limit.
        maxConn: ...
        # If no data is sent from a connection in the specified duration, close the connection.
        # Optional. Default to no timeout.
        idleTimeout: 1m
    # Canary deployment strategy.
    # Declare weight of each version.
    # Optional.
    canary:
      - version: v1
        weight: 99
      - version: v2
        weight: 1

The format of idleTimeout is defined by Go time.ParseDuration ↗ .

Attach Meshlet Label to Workload Definition#

Workload means Deployment, StatefulSet, DaemonSet.

apiVersion: apps/v1
kind: Deployment
metadata:
  ...
spec:
  template:
    metadata:
      labels:
        # Meshlet Label.
        # Declare which Meshlet the Pods of this workload belong to.
        meshless/meshlet: <meshlet-name>
        # Version of this workload. Used in canary deployment strategy.
        # Optional.
        version: v1
    spec:
      containers:
      ...

Canary Deployment Strategy#

Canary deployment strategy is used for safely rolling out a new version of a service, by first testing it using a small percentage of traffic, gradually directing more traffic to the new version, and finally directing all traffic to the new version.

You may declare the canary deployment strategy of your meshlet when defining a meshlet → and attaching Meshlet label to workload definition → .

As Server#

A meshlet can be a server that provides services for other meshlets to use.
You declare the services your meshlet provides when defining a meshlet → .

For each service your declare, please listen at the UDS address /meshlet/server/<service-name> in you Pods. The directory /meshlet/server is automatically generated by Meshless. <service-name> is the name of your service.

According to Linux manual, connecting to an UDS address requires write permission on that UDS file. Please set UDS file permission if necessary, so that Meshless Node Agent can connect to your service. Meshless Node Agent runs as UID 1000 and GID 1000.

Looking for SDK? Try Server-Side SDK →

As Client#

A meshlet can be a client that uses services provided by other meshlets.
You declare the services your meshlet uses when defining a meshlet → .

To access a service,

1. Connect to Meshless Node Agent by connecting to the UDS address /meshlet/client/meshless in your Pods. The directory /meshlet/client is automatically generated by Meshless.

2. Handshake with Meshless Node Agent. Client Handshake Protocol → .
   Meshless Node Agent will establish a secure tunnel between your meshlet and the destination service, as if your meshlet is directly connected to the destination service.

3. Proceed to communication with the destination service.

Looking for SDK? Try Client-Side SDK →

Client Handshake Protocol#

Request#

Client sends a request which is a stream of bytes as defined below.

Service ID#

Service ID is like FQDN. Its format is <service-name>.<meshlet-name>.<ns>.

Reply#

Meshless Node Agent validates the request, and establishes a secure tunnel between your meshlet and the destination service, and sends a reply which is a stream of bytes as defined below.

Reply Code 0 means your request is valid, and the destination service exists, and your meshlet has the right to access the destination service, and Meshless Node Agent establishes a secure tunnel between your meshlet and the destination service.
If anything wrong, a dedicated reply code will tell what happened.

SDK#

Server-Side#

To listen at an UDS address, in Go for example, is pretty straightforward:
net.Listen("unix", udsAddr).

For advanced features such as cleaning up UDS file before listening, setting UDS file permission, graceful shutdown, generating connection id, etc., try UDS Server → .

For HTTP, try HTTP Server over UDS → .

Client-Side#

To connect to an UDS address, in Go for example, is pretty straightforward:
net.Dial("unix", udsAddr).

For one-line API that connects to and handshakes with Meshless Node Agent, and handles connection timeout and handshake timeout, etc., try Meshless Client → .

For HTTP, try Meshless HTTP Client → .