Skip to main content

Plan load balancer requirements for Chef 360 Platform

Chef 360 Platform doesn’t include an external load balancer. If you deploy Chef 360 Platform across multiple nodes — whether using a Chef-managed embedded cluster or your own bring-your-own-Kubernetes (BYOK) cluster — put a load balancer in front of the cluster so that users and managed nodes can reach the platform through a single, highly available address instead of connecting to an individual node directly.

This guide describes the node roles in a multi-node deployment, the ports each platform service exposes, and how to configure a generic load balancer to distribute traffic across your cluster. Most of this guidance applies to both embedded cluster and BYOK deployments; a few items are specific to one deployment model, and those are called out where they appear.

Use this guide during deployment planning to compare supported architectures and decide how to handle service pools, DNS, TLS, network access, and health checks. The configuration, verification, and troubleshooting guidance is included so the deployment team can carry the approved design through implementation.

Note

Important: The examples and diagrams in this guide represent reference implementations. Your own load balancer configuration may vary based on security requirements, network segmentation, infrastructure standards, cloud provider capabilities, and organizational policies. Multiple deployment patterns are supported — see Supported reference architectures.

Note

Embedded cluster only: This guide covers the external, application-facing load balancer only. Load balancing between controller nodes for the Kubernetes control plane uses keepalived and is already handled for you. See Networking requirements for details. In a BYOK deployment, you manage your own Kubernetes control plane and its load balancing directly; see your BYOK system requirements.

Before you begin

  • Deploy a multi-node cluster using the Hyperconverged HA, Tiered-HA, or Hyperscale HA topology. A single-node Hyperconverged Non-HA deployment has only one node to reach, so it doesn’t need a load balancer. For BYOK deployments, see the BYOK system requirements page for the same topology options on a customer-managed cluster.
  • Confirm that your load balancer can reach every cluster node over the network.
  • Identify or provision the load balancer you’ll configure. The steps in this guide use generic terms—pool, URL, and health monitor—that apply to most load balancers; consult your load balancer’s documentation for the equivalent configuration objects. Pools are labeled Layer 7 (HTTP/HTTPS-aware) or Layer 4 (TCP pass-through) based on the traffic they carry; see Layer 4 and Layer 7 traffic requirements.
  • Reserve a Domain Name System (DNS)-registered, RFC 1123-compliant fully qualified domain name (FQDN) for the load balancer’s URL. System requirements describes Chef 360 Platform’s own FQDN requirement.

How Kubernetes routes traffic to your cluster

The architecture described in this guide is a recommended deployment model, not the only supported approach. Before you choose an architecture, understand how Kubernetes itself handles incoming traffic:

  • A Kubernetes service is reachable through any node in the cluster, not only the nodes running the workload that ultimately serves the request.
  • Traffic doesn’t need to arrive directly on the node hosting the target workload. Kubernetes can accept a request on one node and internally route it to a workload running on a different node.
  • The frontend, backend, and controller node role labels described in Node roles and pool membership are workload-placement constructs — they tell Kubernetes (and you) where a service’s pods run. They don’t inherently dictate network routing behavior or restrict which node can receive a client’s connection.

This means you have real flexibility in how you design your load balancer pools. The rest of this guide documents the straightforward, direct-routing model as a default, but see Supported reference architectures for alternatives better suited to security-conscious or network-segmented environments.

Supported reference architectures

Chef 360 Platform supports more than one way to route external traffic into a multi-node embedded cluster. Choose the option that best fits your security requirements, network topology, and operational preferences.

Option 1: Direct frontend and backend routing

Description: The load balancer routes each port directly to the pool of nodes running the matching role — the model documented in the rest of this guide.

Benefits:

  • More efficient routing — no extra network hop between the load balancer and the workload.
  • Fewer moving parts to configure and operate.

Limitations:

  • Backend nodes (and the controller nodes serving the admin console) are directly reachable from the load balancer, which increases the number of node types exposed to external-facing pools.

Recommended use cases: Most deployments where backend node exposure to the load balancer’s internal network is acceptable under your security policies.

Option 2: Frontend-only routing with backend isolation

Description: The external load balancer routes traffic only to frontend nodes. Frontend nodes then proxy traffic to backend workloads. Backend nodes remain isolated from the external load balancer and aren’t exposed to it directly.

Benefits:

  • Reduced exposure of backend infrastructure to the external load balancer.
  • Simpler external security posture — fewer node types reachable from outside the frontend tier.
  • Fewer backend nodes exposed to external-facing networking.

Limitations:

  • Introduces an additional network hop (frontend-to-backend proxying).
  • Slightly lower routing efficiency than direct backend routing.

Recommended use cases: Security-conscious environments where minimizing externally reachable node types is a priority, even at the cost of an extra hop.

Option 3: Segmented or VLAN deployment

Description: Frontend and backend services operate in separate network zones, VLANs, or segments, rather than on a shared network.

Benefits:

  • Stronger network isolation between tiers.
  • Better alignment with enterprise network security requirements that mandate segmentation.

Limitations:

  • Additional routing and load balancing complexity — segmented environments often need extra routing or load balancing components to bridge zones.

Recommended use cases: Environments with existing network segmentation policies or regulatory requirements that mandate VLAN or zone separation between tiers. See Network segmentation and routing validation for practical next steps if you choose this option.

Network segmentation and routing validation

The reference architecture described in this guide assumes network connectivity between all required components — the load balancer, every cluster node, and clients. If you deploy frontend and backend nodes on different VLANs or network segments (see Option 3: Segmented or VLAN deployment), validate the following before you implement your load balancer configuration:

  • Confirm routing exists between every network segment that hosts cluster nodes and the segment hosting your load balancer.
  • Confirm firewall rules permit traffic on the required ports (see Node roles and pool membership) between segments.
  • Determine whether your segmented environment needs additional routing or load balancing components to bridge VLANs or zones, and provision them before you proceed.
  • Re-validate routing and firewall rules whenever you add nodes to a segment that didn’t previously host cluster nodes.

Network topology can materially influence your load balancer design — validate these requirements with your network team before implementation, rather than after.

Node roles and pool membership

Chef 360 Platform assigns each node one or more roles used for workload placement: frontend and backend apply to both embedded cluster and BYOK deployments; controller and its admin console port (30000) are embedded cluster only — BYOK deployments don’t expose an admin console port or pool (see Keep the admin console on a separate URL). The load balancer sits in front of the cluster and routes each port to the pool of nodes that runs the matching role. Each pool also carries a traffic-type label — Layer 7 (HTTP/HTTPS-aware) or Layer 4 (TCP pass-through) — that determines how you configure it; see Layer 4 and Layer 7 traffic requirements for details.

Traffic flows from users and nodes, through the load balancer’s URLs, into the pool that matches each port’s role:

                        ┌───────────────────────┐
 Users and managed      │     Load balancer     │
 nodes connect here --> │                       │
                        │  URLs:                │
                        │  - app (31000/443)    │  Layer 7 (HTTP/HTTPS)
                        │  - admin (30000)      │  Layer 7 (HTTP/HTTPS, embedded cluster only)
                        │  - RabbitMQ (31050)   │  Layer 4 (TCP)
                        └──────────┬────────────┘
                                   │ routes each URL
                                   │ to its own pool
               ┌───────────────────┼───────────────────┐
               ▼                   ▼                   ▼
        Controller pool      Frontend pool        Backend pool
        (admin console)   (platform app, UI)      (RabbitMQ)
     Layer 7, embedded          Layer 7              Layer 4
       cluster only

How these roles map to physical nodes depends on your topology. The following table describes the embedded cluster role layout; BYOK deployments use the same topology names, but consult your own BYOK system requirements for the exact node labels your topology uses, since BYOK clusters don’t have a separate controller role for the admin console:

TopologyRole layout (embedded cluster)
Hyperconverged HAAll 3 nodes run all three roles; every node is identical.
Tiered-HAController and backend roles are combined on the same pool of 3 nodes. Frontend runs on a separate pool of 3 or more nodes.
Hyperscale HAController, frontend, and backend each run on their own dedicated pool of nodes (3, 3 or more, and 3, respectively). Roles can’t overlap.

For more information about each topology’s node counts and sizing, see multi-node deployment requirements and Cluster management.

Regardless of topology, confirm which nodes run each role in your actual cluster before you build load balancer pools, rather than relying on the table above alone. List each node’s assigned roles by running:

kubectl get nodes --show-labels

Look for the chef.io/frontend=true and chef.io/backend=true labels on each node, and (embedded cluster only) chef.io/controller=true. A node can carry more than one of these labels.

Create a separate load balancer pool for each port, and add the nodes carrying the matching role label:

PortServicePool contains nodes labeledTraffic typeRequired
30000Admin console (embedded cluster only — not applicable to BYOK)chef.io/controller=trueLayer 7Embedded cluster: yes. BYOK: not applicable.
31000Chef 360 Platform application (API and UI)chef.io/frontend=trueLayer 7Yes
31050RabbitMQchef.io/backend=trueLayer 4Yes

Note

Confirm the exact port numbers for your Chef 360 Platform version before you configure your load balancer. List the actual NodePort values in your cluster by running:

kubectl get svc --all-namespaces | grep NodePort

Keep the admin console on a separate URL

Embedded cluster only: this section, and port 30000, don’t apply to BYOK deployments — BYOK clusters don’t expose an admin console port, since node lifecycle on a customer-managed cluster isn’t handled through Chef 360 Platform’s admin console.

Regardless of topology, don’t include the admin console port (30000) in the same URL as the application port. New nodes joining the cluster and administrators managing the cluster need to reach the admin console independently of the load balancer that serves end-user application traffic. Choose one of the following ways to provide that access:

  • Connect directly to a controller node, bypassing the load balancer.
  • Create a separate URL dedicated to the admin console pool.

This separation still applies in a Hyperconverged HA or Tiered-HA topology, even though the admin console pool’s nodes also serve other roles there: keep the admin console’s URL distinct from the application’s URL.

Layer 4 and Layer 7 traffic requirements

Chef 360 Platform exposes both HTTP-based and non-HTTP, TCP-based services. Your load balancer needs to handle each type differently.

Layer 7 traffic

Layer 7 (application-layer) traffic is HTTP/HTTPS traffic. Examples in Chef 360 Platform:

  • Chef 360 Platform’s user interface (UI)
  • Platform application programming interfaces (APIs)
  • HTTP/HTTPS endpoints generally

Characteristics:

  • HTTP-aware — the load balancer can inspect requests at the protocol level.
  • Uniform Resource Identifier (URI) inspection and routing is possible.
  • TLS termination at the load balancer is commonly used (see SSL/TLS deployment options).

Layer 4 traffic

Layer 4 (transport-layer) traffic is TCP traffic without HTTP semantics. The only example in Chef 360 Platform is:

  • RabbitMQ, using the Advanced Message Queuing Protocol Secure (AMQPS)

Characteristics:

  • TCP pass-through — the load balancer forwards packets without parsing an application-layer protocol.
  • No HTTP inspection is possible or expected.
  • Requires Layer 4 forwarding at the load balancer, not Layer 7 routing rules.

Service classification

PortServiceTraffic typeLoad balancer handling required
30000Admin console (embedded cluster only)Layer 7 (HTTPS)HTTP-aware routing, or simple TCP forwarding if Layer 7 features aren’t needed
31000Chef 360 Platform application (API and UI)Layer 7 (HTTPS)HTTP-aware routing, or simple TCP forwarding if Layer 7 features aren’t needed
31050RabbitMQLayer 4 (AMQPS/TCP)Layer 4 (TCP) forwarding only — no Layer 7 inspection

Why RabbitMQ requires Layer 4 handling

RabbitMQ traffic on port 31050 is:

  • Non-HTTP traffic.
  • Layer 4 (transport-layer) traffic.
  • TCP-based, using AMQPS.
  • Not suitable for Layer 7 routing or inspection — there’s no HTTP request/response structure for the load balancer to parse.

Configure RabbitMQ’s pool and URL for TCP pass-through only. Don’t apply Layer 7 routing rules (URI-based routing, HTTP header inspection, and similar) to this pool — they don’t apply to AMQPS traffic and can prevent the connection from working. This is why RabbitMQ requires different handling than the HTTP-based admin console and application services.

SSL/TLS deployment options

Chef 360 Platform’s application and admin console services terminate Transport Layer Security (TLS) themselves: each node serves HTTPS directly on its NodePort. This guide supports both of the following TLS deployment options for Layer 7 pools. Choose the one that fits your security and operational requirements — neither is a single preferred approach.

TLS termination at the load balancer

The load balancer ends the TLS session using its own certificate, then opens a new encrypted connection to the pool member.

Benefits:

  • Centralized certificate management for your user-facing FQDN.
  • Easier certificate rotation — one certificate to manage at the load balancer, rather than one for each node.
  • Integration with enterprise load balancer certificate management and advanced security controls.
  • Support for mutual TLS (mTLS) deployments.

Considerations:

  • Traffic is decrypted at the load balancer, so you need to trust (or disable validation for) each node’s certificate on the re-encrypted connection to the pool member.

TLS passthrough

The load balancer forwards encrypted TCP traffic to the pool members without decrypting it, and the node ends the TLS session.

Benefits:

  • End-to-end encryption — traffic stays encrypted from client to node.
  • Simple certificate ownership model — your load balancer doesn’t need a copy of the backend certificate.

Considerations:

  • Reduced load balancer functionality — no Layer 7 features that depend on decrypted traffic (URI-based routing, header inspection).
  • Limited traffic inspection capabilities at the load balancer.
  • Certificate management remains entirely on the platform (one certificate for each node, or a shared certificate you manage yourself).

RabbitMQ is always passthrough

RabbitMQ (31050) is Layer 4 (TCP) traffic and always uses TLS passthrough: the load balancer must forward raw TCP without inspecting or ending the AMQPS session. Terminate-and-re-encrypt doesn’t apply to this pool.

Health checks

Configure a health monitor for each pool so that the load balancer stops sending traffic to a node that isn’t ready:

PortMonitor typeNotes
30000TCP connect, or HTTPSEmbedded cluster only. Use a TCP connect monitor, or an HTTPS monitor. If you use TLS passthrough and the node’s certificate is self-signed, disable certificate validation on the monitor, or use TCP connect. If you use TLS termination, the load balancer can validate its own certificate instead.
31000TCP connect, or HTTPSSame as above.
31050TCP connectRabbitMQ’s NodePort serves AMQPS (TLS), not HTTP, so only a TCP connect monitor applies — this pool is always Layer 4.

Operational considerations for dynamic and autoscaling node environments

If you deploy Chef 360 Platform’s cluster nodes in an environment that supports automatic scaling or dynamic node replacement, plan for the following operational considerations. Not every environment behaves identically — validate your own design before relying on it in production.

  • Scaling activity adds operational complexity. Adding or removing nodes changes your pool membership; plan for how that membership gets updated.
  • Load balancer target/pool registration needs to track node changes. When a node is added or removed, confirm your load balancer’s pool membership is updated to match — either through automation or a documented manual process.
  • Node replacement has operational implications. A replaced node may get a new identity or address; confirm your pool membership and health monitor configuration account for this rather than assuming a node’s identity is stable indefinitely.
  • Validate your design before production. Test node addition, removal, and replacement against your load balancer configuration in a non-production environment first.
  • Some environments may require additional automation. Depending on your infrastructure and operational requirements, you may need to automate pool membership updates rather than manage them manually. Don’t assume every dynamic or autoscaling environment is simple or behaves the same way — validate the specific behavior of your own infrastructure.

Set up the load balancer

The steps below use the generic terms introduced earlier in this guide (pool, health monitor, URL); consult your load balancer’s documentation for the matching configuration objects and syntax. Steps for port 30000 apply to embedded cluster deployments only — skip them for BYOK. BYOK deployments may also front these ports with a Kubernetes Ingress controller instead of a load balancer pool, depending on your platform’s conventions; consult your own cluster’s ingress configuration if so.

  1. For each required port (31000 and 31050, plus 30000 for embedded cluster deployments), create a pool containing the nodes listed in Node roles and pool membership.

  2. Attach the matching health monitor from Health checks to each pool.

  3. Create a URL for the application pool (31000, Layer 7) using your reserved FQDN.

    • Optional: present port 443 on the URL and forward to port 31000 on the pool members. This gives users a conventional https://<fqdn> URL instead of https://<fqdn>:31000. If you use this option, confirm that no client configuration (for example, single sign-on redirect URIs) hardcodes port 31000.
  4. Embedded cluster only: create a separate URL for the admin console pool (30000, Layer 7), reachable only by administrators and joining nodes.

  5. Create a URL for the RabbitMQ pool (31050, Layer 4).

The following example illustrates the configuration objects for the application pool (port 31000) using generic, invented syntax. It isn’t any specific load balancer product’s configuration format—use it to confirm you’ve captured the same information in your own load balancer’s syntax.

# Illustrative syntax only --- not any specific product's configuration format.
pool: chef360-app-pool
  members:
    - frontend-node-1:31000
    - frontend-node-2:31000
    - frontend-node-3:31000
  health_monitor:
    type: tcp
    port: 31000

url: chef360.example.com
  listen_port: 31000      # or 443, if you forward to port 31000 on the pool members
  tls_mode: passthrough    # or terminate_and_re_encrypt --- see SSL/TLS deployment options
  pool: chef360-app-pool

Mailpit (development and test environments only)

Mailpit is intended for development, testing, and laboratory environments only and should not be included in production deployment designs.

If you enable Mailpit in a non-production environment, its test email viewer is exposed on NodePort 31101, through a pool of nodes labeled chef.io/backend=true, using a Layer 4 (TCP) or Layer 7 (HTTP) monitor depending on how you access it. Don’t add this pool, port, or URL to any production load balancer configuration, diagram, or runbook.

Verify the configuration

After you create the pools, health monitors, and URLs, confirm the load balancer is routing traffic correctly before you hand the FQDN to users:

  1. Confirm each pool reports all expected members as healthy. A misconfigured health monitor—not a connectivity problem with the platform—is usually the first thing to check if a node shows as down.

  2. Confirm the application URL is reachable and returns the platform’s login page:

    curl -vk https://<fqdn>:31000
    

    Replace <fqdn> with your reserved domain name. If you configured the optional 443 listener, test that port instead. A successful response returns an HTTP status code from the platform (for example, 200 or a redirect to the login page), not a connection timeout or reset.

  3. Embedded cluster only: confirm the admin console is reachable on its own URL, and not reachable through the application URL:

    curl -vk https://<admin-fqdn-or-ip>:30000
    
  4. Test failover: take one application pool member out of rotation (for example, drain it or stop the platform service on that node), then repeat step 2. The request should still succeed, served by a remaining healthy pool member. Return the member to rotation when you’re done testing.

  5. Confirm RabbitMQ’s URL accepts connections on 31050 from a test client, using a tool like openssl s_client or nc to test the AMQPS (TLS) connection. A successful connection confirms basic reachability; full message-queue functionality is verified separately when you enroll nodes or run platform health checks.

Troubleshooting

SymptomLikely causeWhat to check
A pool member shows as down or unhealthyThe health monitor targets the wrong port, or an HTTPS monitor is rejecting the node’s self-signed-style certificateConfirm the monitor’s port matches Health checks; switch to a TCP connect monitor or disable certificate validation.
The FQDN doesn’t resolve, or resolves to the wrong addressThe DNS record for the URL is missing, stale, or points at an individual node instead of the load balancerConfirm the DNS record matches the load balancer’s URL, not a node’s IP address.
Clients get a TLS/certificate error connecting through the load balancerThe URL’s configured TLS mode (passthrough or terminate-and-re-encrypt) doesn’t match what the client or backend expectsReview SSL/TLS deployment options; confirm the URL’s TLS mode is the one you intended, and that certificates are in place for that mode.
The admin console is reachable through the main application URL (embedded cluster only)The admin console port (30000) was added to the application pool or URL instead of its ownReview Keep the admin console on a separate URL and move port 30000 to its own pool and URL.
A new node fails to join the cluster (embedded cluster only)The joining node can’t reach the admin console’s URL or poolConfirm the admin console pool includes the current controller nodes and that the joining node has network access to its URL.

Next steps

After you configure and verify your load balancer, continue to access the platform using the load balancer’s FQDN.

Thank you for your feedback!

×