Skip to main content
Version: Weekly Build

gateway-and-load-balancing

title: "Gateway and Load Balancing" slug: /private-cloud/configure/gateway-and-load-balancing sidebar_position: 2 description: "Configure the platform and public gateway services and, where there is no cloud Load Balancer integration, MetalLB."​

Codesphere exposes two gateway services, each backed by a Kubernetes Service:

  • gateway-controller — the platform gateway, serving <base-domain> and <dc-id>.<base-domain>.
  • public-gateway-controller — the workspace gateway, serving *.<dc-id>.<base-domain>.

A third service, ssh-workspace-proxy, serves SSH traffic to workspaces at <dc-id>.ssh.<base-domain>. See Requirements and sizing and Networking, firewalls, and DNS for how these three addresses fit into the overall topology.

cluster.gateway and cluster.publicGateway​

Both are configured independently in config.yaml under cluster.gateway (platform gateway) and cluster.publicGateway (workspace gateway):

cluster:
  gateway:
    serviceType: LoadBalancer # or NodePort or ClusterIP
    ipAddresses:
      - <reserved-platform-gateway-ip>
    annotations: {}
  publicGateway:
    serviceType: LoadBalancer # or NodePort or ClusterIP
    ipAddresses:
      - <reserved-workspace-gateway-ip>
    annotations: {}

serviceType defaults to LoadBalancer. If LoadBalancer is used, a Cloud Controller Manager should be present in the cluster to pick up the Service and provision a Load Balancer. If the infrastructure has no native Kubernetes Load Balancer integration, use NodePort. In this case, an external Load Balancer configuration is required to forward traffic to the node ports of the gateway services on all K8s worker nodes.

You can use the annotations field to configure the Load Balancer implementation via annotations respected by your cloud provider's Load Balancer implementation. For example, on AWS you can use the service.beta.kubernetes.io/aws-load-balancer-type annotation to select the Load Balancer type.

The ipAddresses field is mapped to the externalIPs field of the gateway services.

ssh-workspace-proxy​

The workspace SSH proxy is not part of cluster. It is deployed as a pc-apps component (see Architecture) and configured under pcApps in config.yaml:

pcApps:
  applications:
    ssh-workspace-proxy:
      enabled: true
      valuesObject:
        service:
          enabled: true
          type: LoadBalancer # or NodePort
          externalTrafficPolicy: Local
          loadBalancerIP: <reserved-ssh-proxy-ip> # optional
KeyDescription
enabledDeploys the SSH proxy.
valuesObject.service.enabledCreates the Kubernetes Service that exposes the proxy.
valuesObject.service.typeLoadBalancer gives the proxy its own external address, like the two gateways.
valuesObject.service.externalTrafficPolicyLocal routes traffic only to nodes running a proxy pod. This preserves the client source IP and avoids an extra hop between nodes.
valuesObject.service.loadBalancerIPRequests a specific reserved address. Omit it when the Load Balancer implementation assigns the address on its own.

Point the <dc-id>.ssh.<base-domain> DNS record at the address the service receives. Allow inbound SSH traffic to that address as described in Networking, firewalls, and DNS.

MetalLB​

On bare metal or other infrastructure without a native cloud Load Balancer integration or another option to configure an external Load Balancer, an alternative solution is to enable MetalLB. MetalLB provides LoadBalancer Services in clusters that have no Cloud Controller Manager, by assigning IPs from a pool that your infrastructure provides, and it announces those IPs to the network. It does not proxy traffic or check application health. Once traffic reaches a node, it's forwarded within K8s like a NodePort.

Modes​

  • BGP: Several nodes advertise the same IP to your routers, which spread traffic across them with ECMP. This gives real load distribution and failover. It requires BGP-capable routers and peering to be set up by the customer’s network team.
  • L2 (ARP/NDP): One node at a time owns the IP and answers ARP for it. This gives failover only, with no load distribution, and it takes a few seconds. It requires all nodes and clients to be on the same L2 segment.

Requirements​

  • A dedicated IP range or pool that the customer reserves.
  • BGP mode: router peering details (ASNs, peer IPs).
  • L2 mode: nodes on a shared L2 segment.

Configuration​

You can configure MetalLB in config.yaml under cluster.metallb. By default, it's disabled.

cluster:
  metallb:
    enabled: true
    pools:
      - name: codesphere-pool
        ipAddresses:
          - <reserved-platform-gateway-ip>/32
          - <reserved-workspace-gateway-ip>/32
          - <reserved-ssh-proxy-ip>/32
    l2:
      - name: codesphere-l2
        pools:
          - codesphere-pool
    bgp: 
      - name: codesphere-bgp
        pools:
          - codesphere-pool

Next​

See Cluster ingress CA options for the certificates served through these gateways, and Complete the infrastructure integration for confirming the services receive their addresses after installation.