Group-level configuration

With MarkLogic Operator 1.1, you may configure HAProxy at the group level for App Servers and TCP ports. This feature addresses common deployment challenges by enabling different groups within the same cluster to have distinct access patterns and service configurations. For example, you can configure a data ingestion group with specialized TCP ports for ODBC connections while keeping query-focused groups accessible only through HTTP endpoints. Group-level configuration also allows you to implement security boundaries, performance isolation, and different routing strategies based on each group's specific role in your architecture.

Configuration overview

Group-level HAProxy configuration provides enhanced flexibility by allowing:

• Independent App Server and port configurations for each group
• Separate HAProxy backends for identical ports across different groups
• Fine-grained control over load balancing behavior in each group

Group-level HAProxy settings follow a hierarchical inheritance model:

• When there is no group-level setting, the group inherits cluster-level HAProxy settings.
• When group-level settings are present, group-level settings override cluster-level defaults for that specific group.

Configuration scenarios

The following scenarios provide detailed examples that show how different group-level configurations affect HAProxy behavior.

HTTP App Server scenarios

• Port-based routing with same port for shared backend
• Port-based routing with different ports for separate backends
• Path-based routing with same path for shared backend
• Path-based routing with different paths for separate backends
• Mixed use of path-based and port-based routing

TCP port scenarios

• TCP Ports with same port for shared listener
• TCP Ports with different ports for separate listeners

Port-based routing with the same port for shared backend

This example shows how identical port configurations automatically create a shared HAProxy backend that load balances across all groups.

markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      pathBasedRouting: false       # Disables path-based routing
      appServers: 
        - name: "app-service"
          port: 8000                # Same port as enode group
          targetPort: 8000
          path: "/console"          # Path will be ignored for port-based routing
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      pathBasedRouting: false       # Disables path-based routing
      appServers: 
        - name: "app-service"
          port: 8000                # Same port as dnode group - creates shared backend
          targetPort: 8000
          path: "/console"          # Path ignored - only port matters for backend sharing

Generated HAProxy configuration:

frontend marklogic-8000-frontend
    bind *:8000
    default_backend marklogic-8000-backend

backend marklogic-8000-backend
    balance leastconn
    server dnode-0 dnode-0.marklogic:8000 check
    server enode-0 enode-0.marklogic:8000 check
    server enode-1 enode-1.marklogic:8000 check

In this configuration:

• Both groups use port 8000 with port-based routing
• HAProxy creates a single frontend (marklogic-8000-frontend) and backend (marklogic-8000-backend)
• All servers from both groups are included in the same backend
• The path parameter is ignored since pathBasedRouting is false
• Load balancing occurs across all nodes in both groups

Port-based routing with different ports for separate backends

This example demonstrates how different external ports create completely separate HAProxy backends, providing isolated access to each group.

markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      pathBasedRouting: false       # Port-based routing enabled
      appServers: 
        - name: "app-service"
          port: 8000                # External port 8000 for dnode
          targetPort: 8000
          path: "/console"
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      pathBasedRouting: false       # Port-based routing enabled
      appServers: 
        - name: "app-service"
          port: 18000               # Different external port - creates separate backend
          targetPort: 8000          # Same internal MarkLogic port
          path: "/console"

Generated HAProxy configuration:

frontend marklogic-8000-frontend
    bind *:8000
    default_backend marklogic-8000-backend

frontend marklogic-18000-8000-frontend
    bind *:18000
    default_backend marklogic-18000-8000-backend

backend marklogic-8000-backend
    balance leastconn
    server dnode-0 dnode-0.marklogic:8000 check

backend marklogic-18000-8000-backend
    balance leastconn
    server enode-0 enode-0.marklogic:8000 check
    server enode-1 enode-1.marklogic:8000 check

In this configuration:

• dnode group uses external port 8000, accessible via :8000
• enode group uses external port 18000, accessible via :18000
• Both groups connect to the same internal MarkLogic port (8000) via targetPort
• HAProxy creates separate frontend/backend pairs for each external port
• Each group maintains its own isolated load balancing pool
• This provides complete separation between groups while using the same internal service

Path-based routing with same path for shared backend

This example demonstrates how groups with identical path configurations automatically share the same HAProxy backend, providing unified load balancing across all groups using the same path.

haproxy:
   enabled: true
   frontendPort: 8080
markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      pathBasedRouting: true        # Enables path-based routing
      appServers: 
        - name: "app-service"
          port: 8000                # Port ignored in path-based routing
          targetPort: 8000
          path: "/console"          # Same path as enode - creates shared backend
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      pathBasedRouting: true        # Enables path-based routing
      appServers: 
        - name: "app-service"
          port: 8000
          targetPort: 8000
          path: "/console"          # Identical path - shares backend with dnode

Generated HAProxy configuration:

frontend marklogic-pathbased-frontend
    bind *:8080
    use_backend marklogic-8000-console-path-backend if { path_beg /console }

backend marklogic-8000-console-path-backend
    balance leastconn
    server dnode-0 dnode-0.marklogic:8000 check
    server enode-0 enode-0.marklogic:8000 check
    server enode-1 enode-1.marklogic:8000 check

In this configuration:

• Both groups use the same path /console with path-based routing enabled
• HAProxy creates a single frontend (marklogic-pathbased-frontend) binding to the configured frontendPort (8080)
• All servers from both groups are included in the same backend (marklogic-8000-console-path-backend)
• The port parameter is ignored since pathBasedRouting is true
• Requests to http://hostname:8080/console are load balanced across all nodes in both groups
• Path-based routing allows multiple services to share the same external port through different URL paths

Path-based routing with different paths for separate backends

This example demonstrates how different path configurations create separate HAProxy backends while sharing a single frontend, enabling isolated group access through unique URL paths.

markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      frontendPort: 8080
      pathBasedRouting: true        # Enables path-based routing
      appServers: 
        - name: "app-service"
          port: 8000
          targetPort: 8000
          path: "/newconsole"       # Unique path - creates separate backend
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      pathBasedRouting: true        # Enables path-based routing
      appServers: 
        - name: "app-service"
          port: 8000
          targetPort: 8000
          path: "/console"          # Different path - creates separate backend

Generated HAProxy configuration:

frontend marklogic-pathbased-frontend
    bind *:8080
    use_backend marklogic-8000-console-path-backend if { path_beg /console }
    use_backend marklogic-8000-newconsole-path-backend if { path_beg /newconsole }

backend marklogic-8000-console-path-backend
    balance leastconn
    server enode-0 enode-0.marklogic:8000 check
    server enode-1 enode-1.marklogic:8000 check

backend marklogic-8000-newconsole-path-backend
    balance leastconn
    server dnode-0 dnode-0.marklogic:8000 check

In this configuration:

• dnode group uses path /newconsole, accessible via http://hostname:8080/newconsole
• enode group uses path /console, accessible via http://hostname:8080/console
• HAProxy creates a single frontend with multiple routing rules
• Each unique path gets its own dedicated backend
• Requests are routed to different groups based on the URL path
• This provides complete separation between groups while sharing the same external port

Mixed use of path-based and port-based routing

This example demonstrates how to combine different routing strategies within the same cluster, allowing legacy and modern approaches to coexist with separate frontends for each routing type.

markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      frontendPort: 8080
      pathBasedRouting: false       # Uses port-based routing strategy
      appServers: 
        - name: "app-service"
          port: 8000                # Creates port-based frontend on 8000
          targetPort: 8000
          path: "/console"          # Path ignored for port-based routing
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      pathBasedRouting: true        # Uses path-based routing strategy
      appServers: 
        - name: "app-service"
          port: 8000
          targetPort: 8000
          path: "/console"          # Creates path-based frontend on frontendPort

Generated HAProxy configuration:

frontend marklogic-pathbased-frontend
    bind *:8080
    use_backend marklogic-8000-console-path-backend if { path_beg /console }

frontend marklogic-8000-frontend
    bind *:8000
    default_backend marklogic-8000-backend

backend marklogic-8000-backend
    balance leastconn
    server dnode-0 dnode-0.marklogic:8000 check

backend marklogic-8000-console-path-backend
    balance leastconn
    server enode-0 enode-0.marklogic:8000 check
    server enode-1 enode-1.marklogic:8000 check

In this configuration:

• dnode group uses port-based routing, accessible via http://hostname:8000
• enode group uses path-based routing, accessible via http://hostname:8080/console
• HAProxy creates two separate frontends:
  • marklogic-pathbased-frontend for path-based routing on port 8080
  • marklogic-8000-frontend for port-based routing on port 8000
• Each routing strategy maintains its own isolated backend
• This allows legacy and modern routing approaches to coexist in the same cluster

TCP Ports with same port for shared listener

This example demonstrates how identical TCP port configurations across multiple groups automatically create a shared HAProxy listener that load balances connections across all participating groups.

markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      tcpPorts:
        enabled: true
        ports:
          - name: odbc
            type: TCP
            port: 5432              # Same external port as enode
            targetPort: 5432        # Internal MarkLogic ODBC port
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      tcpPorts:
        enabled: true
        ports:
          - name: odbc
            type: TCP
            port: 5432              # Identical port - creates shared listener
            targetPort: 5432        # Same internal MarkLogic ODBC port

Generated HAProxy configuration:

listen marklogic-TCP-5432
    bind *:5432
    mode tcp
    balance leastconn
    server dnode-0 dnode-0.marklogic:5432 check
    server enode-0 enode-0.marklogic:5432 check
    server enode-1 enode-1.marklogic:5432 check

In this configuration:

• Both groups configure the same TCP port 5432 for ODBC connections
• HAProxy creates a single listener (marklogic-TCP-5432) in TCP mode
• All servers from both groups are included in the same listener
• TCP connections to port 5432 are load balanced across all nodes in both groups
• This provides unified access to ODBC services across the entire cluster
• TCP mode ensures pure Layer 4 load balancing without HTTP-specific features

TCP Ports with different ports for separate listeners

This example demonstrates how different external TCP ports create completely separate HAProxy listeners, providing isolated access to each group while connecting to the same internal MarkLogic service.

markLogicGroups:
  - replicas: 1
    groupConfig:
      name: dnode
    haproxy:
      enabled: true
      tcpPorts:
        enabled: true
        ports:
          - name: odbc
            type: TCP
            port: 15432             # Different external port - creates separate listener
            targetPort: 5432        # Same internal MarkLogic ODBC port
  - replicas: 2
    groupConfig:
      name: enode
    haproxy:
      enabled: true
      tcpPorts:
        enabled: true
        ports:
          - name: odbc
            type: TCP
            port: 5432              # Standard external port - creates separate listener
            targetPort: 5432        # Same internal MarkLogic ODBC port

Generated HAProxy configuration:

listen marklogic-TCP-5432
    bind *:5432
    mode tcp
    balance leastconn
    server enode-0 enode-0.marklogic:5432 check
    server enode-1 enode-1.marklogic:5432 check

listen marklogic-TCP-15432-5432
    bind *:15432
    mode tcp
    balance leastconn
    server dnode-0 dnode-0.marklogic:5432 check

In this configuration:

• dnode group uses external port 15432, accessible via hostname:15432
• enode group uses external port 5432, accessible via hostname:5432
• Both groups connect to the same internal MarkLogic ODBC port (5432) via targetPort
• HAProxy creates separate listeners for each external port
• Each group maintains its own isolated TCP connection pool
• This provides complete separation between groups while accessing the same internal service
• Useful for scenarios requiring dedicated ODBC access per group or environment