Network Load Balancer(NLB) Guide - cloud-barista/cb-spider GitHub Wiki

Network Load Balancer Management Guide

Language: English | 한국어

1. CB-Spider NLB Overview

Users can create and configure a Network Load Balancer (NLB) belonging to a specific VPC to manage load balancing for external client requests and input streams directed to VMs within the VPC.
- As shown in the diagram, you can create and configure an NLB belonging to a specific VPC.
- When creating an NLB, you can configure target VMs (VM Group) together, or you can add VMs after NLB creation.
- Exception: KT NLB can be created targeting Subnets rather than VPCs.
  - KT NLB only supports creation together with target VMs (VM Group), and the NLB is created in the Subnet where the configured VMs belong.
  - Additionally, only VMs in the same Subnet as the NLB can be added to and operated in the VM Group.
NLB can be created by selecting Public type or Internal type.
- Public type (default): Load balancing for client streams from external internet users
- Internal type: Load balancing for streams between internal VMs
- Developed and prioritized around Public type provision
NLB can be created by selecting Region scope or Global scope operation.
- Regional NLB (default): Load balancer operating in a single Region
- Global NLB: Load balancer operating in multi-Regions
- Developed and prioritized around Regional NLB provision

2. CB-Spider NLB Components

NLB is divided into Frontend and Backend tiers, and the main components for each tier are as follows.

[NLB-Frontend Tier]

(1) Frontend Listener
- The listener receives client requests and input streams and forwards them to the VM group in the backend tier.
- One NLB contains one listener, which consists of a receiving protocol, IP, and receiving port.
- Selectable receiving protocols are TCP and UDP, and the IP is automatically generated and managed by the CSP or target Driver.
- The receiving port can be set to a value in the range 1-65535.
- ※ Listener IP and DNS-Name: Both can be provided, or only one of them

[NLB-Backend Tier]

(2) Backend VM Group

A VM group is a collection of VMs providing the same service (nginx, redis, user-developed services, etc.), and VMs can be registered or excluded.
VMs that can be included in the VM group are limited to VMs belonging to the same VPC as the NLB.
One NLB contains one VM group, which consists of a receiving protocol, receiving port, and VMs.
Selectable receiving protocols are TCP and UDP,
The VM group can set one receiving port. (Port range: 1-65535)
VMs within the VM group can provide services through the same protocol and port number as the VM group settings.

(3) Health Checker

One NLB contains one health checker,
The health checker provides health status information for VMs included in the VM group.
- Provides Healthy VM list, Unhealthy VM list, etc.
- Initial health status check for added VMs takes a few seconds to minutes
Selectable protocols for the health checker are TCP and HTTP,
To check the health status of VMs belonging to the VM group, the same port as the VM group can be used,
Or a separate dedicated health check port (Port 81 in the diagram) can be configured separately.
Service daemons for each VM's service port and health check port must be prepared by the user.
The health checker can set status check period (Interval), Timeout, and Threshold values,

If the user does not set values or specifies default value, default values are set.

※ cf) Health Check Interval, Timeout, Threshold default values and configuration conditions

[Interval]

CSP	TCP `default`	HTTP `default`	Configuration Conditions, Range, and Notes
AWS	10	10	* Range: Only 10, 30 possible
Azure	10	10	* Range: 5 or more * Condition: Interval * Threshold < 2147483647
GCP	10	10	* Range: 1~300 * Condition: Timeout <= Interval
Alibaba	10	10	* Range: 1~50
Tencent	10	10	* Range: 2~300 * Condition: Timeout <= Interval
IBM	10	10	* Range: 2~60 * Condition: Timeout < Interval
OpenStack	10	10	* Range: 2147483647(int max) * Condition: Timeout <= Interval
NCP	10	10	* Range: 5~300
NHN	10	10	* Range: 1~5000 * Condition: Timeout < Interval

[Timeout]

CSP	TCP `default`	HTTP `default`	Configuration Conditions, Range, and Notes
AWS	10	6	* Cannot be set * TCP: 10s, HTTP: 6s fixed
Azure	10	10	* Cannot be set * Smaller of Interval and Azure default Timeout(`30`)
GCP	10	6	* Range: 1 or more * Condition: Timeout <= Interval
Alibaba	10	6	* Range: 1~300
Tencent	10	6	* Range: 2~60 * Condition: Timeout <= Interval
IBM	9	6	* Exception * Condition: Timeout < Interval
OpenStack	10	6	* Range: 2147483647(int max) * Condition: Timeout <= Interval
NCP	10	6	* Range: 1~3600
NHN	10	6	* Range: 1~5000 * Condition: Timeout < Interval

[Threshold]

CSP	TCP `default`	HTTP `default`	Configuration Conditions, Range, and Notes
AWS	3	3	* Range: 2~10
Azure	3	3	* Range: 1 or more * Condition: Interval * Threshold < 2147483647
GCP	3	3	* Range: 1~10
Alibaba	3	3	* Range: 2~10
Tencent	3	3	* Range: 2~10
IBM	3	3	* Range: 1~10
OpenStack	3	3	* Range: 1~10
NCP	3	3	* Range: 2~10
NHN	3	3	* Range: 1~10

※ Service Group Auto-Scaling

Auto-scaling definition and support will be considered in the future

3. CB-Spider NLB Operation Flow

The main NLB operation flow is as follows.
- ① Client -> Frontend Service Request
  - Clients request services through the Frontend listener IP and listener port based on TCP, HTTP, or UDP protocols.
  - Client HTTP protocol calls are possible when the VMGroup receiving protocol is TCP.
- ② Frontend -> Backend Service Routing
  - User requests received by the listener are routed to the VM group port based on TCP or UDP.
- ③ Routing Target VM Selection and Routing (Performed by target CSP)
  - Client requests and input streams are routed to VMs in Healthy status among VMs included in the VM group.
  - If all VMs included in the VM group are in Unhealthy status, each CSP operates as follows:
    - CSPs that route to all VMs in the VM group: AWS, GCP, Tencent
    - CSPs that do not route client streams: Azure, IBM
- ※ Health Checking
  - The health checker periodically identifies and provides the Health status of VMs included in the VM group.

4. CB-Spider NLB API and Information Specification

Users can receive NLB information in JSON format using the following CB-Spider REST API.

4.1 NLB Management API

# NLB Creation and Query
POST   /spider/nlb                      - Create NLB
GET    /spider/nlb                      - List NLBs
GET    /spider/nlb/{Name}               - Get NLB
DELETE /spider/nlb/{Name}               - Delete NLB

# NLB Registration/Unregistration (Integration with existing CSP NLB)
POST   /spider/regnlb                   - Register NLB
DELETE /spider/regnlb/{Name}            - Unregister NLB
POST   /spider/getnlbowner              - Get NLB Owner VPC

# NLB VM Management
POST   /spider/nlb/{Name}/vms           - Add VMs to NLB
DELETE /spider/nlb/{Name}/vms           - Remove VMs from NLB

# NLB Health Information
GET    /spider/nlb/{Name}/health        - Get VM Group Health Info

# NLB List Query (All)
GET    /spider/allnlb                   - List All NLBs (CB-Spider + CSP)
GET    /spider/allnlbinfo               - List All NLB Info

# NLB Statistics
GET    /spider/countnlb                 - Count All NLBs
GET    /spider/countnlb/{ConnectionName} - Count NLBs by Connection

# Direct CSP NLB Deletion
DELETE /spider/cspnlb/{Id}              - Delete CSP NLB

4.2 Information Specification

NLB Information (NLBInfo)

Field	Description	Examples
IId	NLB identifier information (NameId, SystemId)	● {Name: "nlb-01", SystemId: "nlb-1234abcd"}
VpcIID	VPC identifier where NLB belongs	● {Name: "vpc-01", SystemId: "vpc-5678efgh"}
Type	NLB type	● "PUBLIC" or "INTERNAL"
Scope	NLB scope	● "REGION" or "GLOBAL"
Listener	Listener information	● See Listener information below
VMGroup	VM group information	● See VMGroup information below
HealthChecker	Health checker information	● See HealthChecker information below
TagList	List of tags assigned to NLB	● [{Key: "Environment", Value: "Production"}]
KeyValueList	Additional NLB information provided by CSP	● [{Key: "State", Value: "active"}]

Listener Information (ListenerInfo)

Field	Description	Examples
Protocol	Receiving protocol	● "TCP" or "UDP"
Port	Receiving port	● "80", "443", "22" (1-65535)
IP	Listener IP (automatically assigned by CSP)	● "52.12.34.56"
DNSName	Listener DNS name (optional)	● "nlb-12345.elb.amazonaws.com"
KeyValueList	Additional listener information provided by CSP	● [{Key: "Scheme", Value: "internet-facing"}]

VMGroup Information (VMGroupInfo)

Field	Description	Examples
Protocol	VM group receiving protocol	● "TCP" or "UDP"
Port	VM group receiving port	● "80", "8080" (1-65535)
VMs	VM identifier list	● [{Name: "vm-01", SystemId: "i-1234"}, {Name: "vm-02", SystemId: "i-5678"}]
CspID	VM group ID assigned by CSP	● "tg-1234567890abcdef0"
KeyValueList	Additional VM group information provided by CSP	● [{Key: "TargetType", Value: "instance"}]

HealthChecker Information (HealthCheckerInfo)

Field	Description	Examples
Protocol	Health check protocol	● "TCP" or "HTTP"
Port	Health check port	● "80", "8080" (1-65535 or Listener Port)
Interval	Health check interval (seconds)	● 10, 30, etc. (default: -1 or "default")
Timeout	Health check timeout (seconds)	● 5, 10, etc. (default: -1 or "default")
Threshold	Health check threshold	● 3, 5, etc. (default: -1 or "default")
CspID	Health checker ID assigned by CSP	● "health-check-1234"
KeyValueList	Additional health checker information provided by CSP	● [{Key: "HealthCheckPath", Value: "/health"}]

HealthInfo Information

Field	Description	Examples
AllVMs	All VMs included in VM group	● [{Name: "vm-01", SystemId: "i-1234"}, ...]
HealthyVMs	List of VMs with normal health check results	● [{Name: "vm-01", SystemId: "i-1234"}]
UnHealthyVMs	List of VMs with abnormal health check results	● [{Name: "vm-02", SystemId: "i-5678"}]

5. CB-Spider NLB API and Information Examples

5.1 NLB Creation Example - Excluding VMGroup Configuration

API call example for creating an NLB without VMGroup configuration:

curl -sX POST http://localhost:1024/spider/nlb \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "nlb-01",
      "VPCName": "vpc-01",
      "Type": "PUBLIC",
      "Scope": "REGION",
      "Listener": {
        "Protocol": "TCP",
        "Port": "80"
      },
      "HealthChecker": {
        "Protocol": "TCP",
        "Port": "80"
      }
    }
  }' | jq

Response Example:

{
  "IId": {
    "NameId": "nlb-01",
    "SystemId": "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-01/1234567890abcdef"
  },
  "VpcIID": {
    "NameId": "vpc-01",
    "SystemId": "vpc-0a1b2c3d4e5f67890"
  },
  "Type": "PUBLIC",
  "Scope": "REGION",
  "Listener": {
    "Protocol": "TCP",
    "Port": "80",
    "DNSName": "nlb-01-1234567890.us-east-1.elb.amazonaws.com",
    "IP": "",
    "KeyValueList": [
      {
        "Key": "Scheme",
        "Value": "internet-facing"
      }
    ]
  },
  "VMGroup": {
    "Protocol": "TCP",
    "Port": "80",
    "VMs": [],
    "CspID": "arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/nlb-01-tg/1234567890abcdef",
    "KeyValueList": [
      {
        "Key": "TargetType",
        "Value": "instance"
      }
    ]
  },
  "HealthChecker": {
    "Protocol": "TCP",
    "Port": "80",
    "Interval": 10,
    "Timeout": 10,
    "Threshold": 3,
    "CspID": "",
    "KeyValueList": []
  },
  "KeyValueList": [
    {
      "Key": "State",
      "Value": "provisioning"
    },
    {
      "Key": "Type",
      "Value": "network"
    }
  ]
}

5.2 NLB Creation Example - Including VMGroup

API call example for creating an NLB including VMGroup(vm-01, vm-02):

curl -sX POST http://localhost:1024/spider/nlb \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "nlb-02",
      "VPCName": "vpc-01",
      "Type": "PUBLIC",
      "Scope": "REGION",
      "Listener": {
        "Protocol": "TCP",
        "Port": "22"
      },
      "VMGroup": {
        "Protocol": "TCP",
        "Port": "22",
        "VMs": ["vm-01", "vm-02"]
      },
      "HealthChecker": {
        "Protocol": "TCP",
        "Port": "22",
        "Interval": "default",
        "Timeout": "default",
        "Threshold": "5"
      }
    }
  }' | jq

Response Example:

{
  "IId": {
    "NameId": "nlb-02",
    "SystemId": "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-02/abcdef1234567890"
  },
  "VpcIID": {
    "NameId": "vpc-01",
    "SystemId": "vpc-0a1b2c3d4e5f67890"
  },
  "Type": "PUBLIC",
  "Scope": "REGION",
  "Listener": {
    "Protocol": "TCP",
    "Port": "22",
    "DNSName": "nlb-02-abcdef1234.us-east-1.elb.amazonaws.com",
    "IP": "",
    "KeyValueList": []
  },
  "VMGroup": {
    "Protocol": "TCP",
    "Port": "22",
    "VMs": [
      {
        "NameId": "vm-01",
        "SystemId": "i-0a1b2c3d4e5f67890"
      },
      {
        "NameId": "vm-02",
        "SystemId": "i-1b2c3d4e5f678901"
      }
    ],
    "CspID": "arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/nlb-02-tg/abcdef1234567890",
    "KeyValueList": []
  },
  "HealthChecker": {
    "Protocol": "TCP",
    "Port": "22",
    "Interval": 10,
    "Timeout": 10,
    "Threshold": 5,
    "CspID": "",
    "KeyValueList": []
  },
  "KeyValueList": [
    {
      "Key": "State",
      "Value": "active"
    }
  ]
}

5.3 NLB Query Example

API call example for querying created NLB information:

curl -sX GET 'http://localhost:1024/spider/nlb/nlb-01?ConnectionName=aws-config01' | jq

5.4 NLB List Query Example

API call example for querying all NLB lists created in a Connection:

curl -sX GET 'http://localhost:1024/spider/nlb?ConnectionName=aws-config01' | jq

Response Example:

{
  "nlb": [
    {
      "IId": {
        "NameId": "nlb-01",
        "SystemId": "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-01/1234567890abcdef"
      },
      "VpcIID": {
        "NameId": "vpc-01",
        "SystemId": "vpc-0a1b2c3d4e5f67890"
      },
      "Type": "PUBLIC",
      "Scope": "REGION",
      ...
    },
    {
      "IId": {
        "NameId": "nlb-02",
        "SystemId": "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-02/abcdef1234567890"
      },
      "VpcIID": {
        "NameId": "vpc-01",
        "SystemId": "vpc-0a1b2c3d4e5f67890"
      },
      "Type": "PUBLIC",
      "Scope": "REGION",
      ...
    }
  ]
}

5.5 VM Addition Example

API call example for adding VMs to NLB's VM Group:

curl -sX POST http://localhost:1024/spider/nlb/nlb-01/vms \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "VMs": ["vm-03", "vm-04"]
    }
  }' | jq

Response Example:

{
  "IId": {
    "NameId": "nlb-01",
    "SystemId": "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-01/1234567890abcdef"
  },
  "VMGroup": {
    "Protocol": "TCP",
    "Port": "80",
    "VMs": [
      {
        "NameId": "vm-03",
        "SystemId": "i-2c3d4e5f67890123"
      },
      {
        "NameId": "vm-04",
        "SystemId": "i-3d4e5f6789012345"
      }
    ],
    ...
  },
  ...
}

5.6 VM Removal Example

API call example for removing VMs from NLB's VM Group:

curl -sX DELETE http://localhost:1024/spider/nlb/nlb-01/vms \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "VMs": ["vm-04"]
    }
  }' | jq

Response Example:

{
  "Result": "true"
}

5.7 VM Group Health Status Information Example

API call example for querying VM Group health status information:

curl -sX GET 'http://localhost:1024/spider/nlb/nlb-01/health?ConnectionName=aws-config01' | jq

Response Example:

{
  "healthinfo": {
    "AllVMs": [
      {
        "NameId": "vm-01",
        "SystemId": "i-0a1b2c3d4e5f67890"
      },
      {
        "NameId": "vm-02",
        "SystemId": "i-1b2c3d4e5f678901"
      },
      {
        "NameId": "vm-03",
        "SystemId": "i-2c3d4e5f67890123"
      }
    ],
    "HealthyVMs": [
      {
        "NameId": "vm-01",
        "SystemId": "i-0a1b2c3d4e5f67890"
      },
      {
        "NameId": "vm-02",
        "SystemId": "i-1b2c3d4e5f678901"
      }
    ],
    "UnHealthyVMs": [
      {
        "NameId": "vm-03",
        "SystemId": "i-2c3d4e5f67890123"
      }
    ]
  }
}

5.8 NLB Deletion Example

API call example for deleting an NLB:

curl -sX DELETE 'http://localhost:1024/spider/nlb/nlb-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

Response Example:

{
  "Result": "true"
}

5.9 Force Deletion Example

API call example for forcefully deleting an NLB (deletes even with connected VMs):

curl -sX DELETE 'http://localhost:1024/spider/nlb/nlb-01?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

6. CB-Spider NLB AdminWeb Usage Examples

The NLB management procedure through AdminWeb is as follows:
1. Select Connection: Select target CSP Connection from the top of AdminWeb
2. Access NLB Menu: Select "NLB" from the left menu
3. Create NLB: Click "Create NLB" button and enter required information
4. Manage NLB: Check NLB status, add/remove VMs, check health, delete, etc.

6.1 NLB List Screen Example

When viewing the NLB list in AdminWeb, the following information is displayed:

NLB Name
VPC Name
Type (PUBLIC/INTERNAL)
Scope (REGION/GLOBAL)
Listener Information (Protocol, Port, DNS Name)
VM Group Information (Number of VMs)
Action Buttons (Details, VM Management, Health Check, Delete, etc.)

6.2 NLB Creation Screen Example

When creating an NLB in AdminWeb, enter the following information:

NLB Name: NLB name to be managed in CB-Spider
VPC Name: Select VPC to which NLB will belong
Type: Select PUBLIC or INTERNAL
Scope: Select REGION or GLOBAL
Listener:
- Protocol: Select TCP or UDP
- Port: Port number in the range 1-65535
VMGroup (optional):
- Protocol: Select TCP or UDP
- Port: Port number in the range 1-65535
- VMs: Select VMs to add (multiple selection possible)
HealthChecker:
- Protocol: Select TCP or HTTP
- Port: Port number in the range 1-65535
- Interval: Health check period (seconds) or "default"
- Timeout: Health check timeout (seconds) or "default"
- Threshold: Health check threshold or "default"
Tags (optional): Resource tag information

6.3 NLB Details Screen Example

The NLB details screen displays the following information:

Basic Information:

NLB IId (NameId, SystemId)
VPC Information
Type, Scope

Listener Information:

Protocol, Port
DNS Name or IP

VMGroup Information:

Protocol, Port
List of registered VMs
Add/Remove VM buttons

HealthChecker Information:

Protocol, Port
Interval, Timeout, Threshold

Health Status:

All VMs
Healthy VMs
Unhealthy VMs

Action Buttons:

Add/Remove VMs
Refresh Health Information
Delete NLB

7. Precautions and Limitations

7.1 NLB Creation Precautions

Pre-created Resources: VPC must be created in advance
VM Preparation: VMs to be added to VM Group must belong to the same VPC as the NLB
Service Daemon: Services must be running on VMGroup Port and HealthChecker Port on each VM
Security Group: VMGroup Port and HealthChecker Port must be allowed in VM's security group
KT Exception: KT NLB is created based on Subnets and must be created together with VMs

7.2 NLB Deletion Precautions

Force Deletion: Using force=true option forcefully deletes without validating relationships with connected resources (caution!)

7.3 Health Check Precautions

Initial Health Check: Initial health status check after adding VMs takes a few seconds to minutes
Service Preparation: A service that can respond to the health check port must be running on the VM
Protocol Compatibility: For HTTP health checks, VMs must provide HTTP responses

7.4 CSP-specific Characteristics

AWS: Interval can only select 10, 30
Azure: Timeout cannot be set (automatically set to smaller of Interval and default value)
IBM: Timeout must be less than Interval
KT: Subnet-based NLB, must be created together with VMs

Network Load Balancer(NLB) Guide - cloud-barista/cb-spider GitHub Wiki

Network Load Balancer Management Guide

1. CB-Spider NLB Overview

2. CB-Spider NLB Components

[NLB-Frontend Tier]

(1) Frontend Listener

[NLB-Backend Tier]

(2) Backend VM Group

(3) Health Checker

※ Service Group Auto-Scaling

3. CB-Spider NLB Operation Flow

4. CB-Spider NLB API and Information Specification

4.1 NLB Management API

4.2 Information Specification

5. CB-Spider NLB API and Information Examples

5.1 NLB Creation Example - Excluding VMGroup Configuration

5.2 NLB Creation Example - Including VMGroup

5.3 NLB Query Example

5.4 NLB List Query Example

5.5 VM Addition Example

5.6 VM Removal Example

5.7 VM Group Health Status Information Example

5.8 NLB Deletion Example

5.9 Force Deletion Example

6. CB-Spider NLB AdminWeb Usage Examples

6.1 NLB List Screen Example

6.2 NLB Creation Screen Example

6.3 NLB Details Screen Example

7. Precautions and Limitations

7.1 NLB Creation Precautions

7.2 NLB Deletion Precautions

7.3 Health Check Precautions

7.4 CSP-specific Characteristics

8. References