Services & Networking

This guide describes the Kubernetes services created by the Polaris Helm chart and how to configure external access using the Gateway API or Ingress.

Services🔗

The Polaris Helm chart creates the following services by default:

Main Service🔗

The main service exposes the Polaris REST APIs. By default, it is a ClusterIP service listening on port 8181.

Example configuration:

service:
  type: ClusterIP
  ports:
    - name: polaris-http
      port: 8181
      protocol: TCP

Management Service🔗

The management service exposes health checks and metrics endpoints. By default, it is a headless service (clusterIP: None) listening on port 8182, which is ideal for Prometheus scraping and service monitoring.

Example configuration:

managementService:
  type: ClusterIP
  clusterIP: None  # Headless service for metrics scraping
  ports:
    - name: polaris-mgmt
      port: 8182
      protocol: TCP

Extra Services🔗

You can define additional services using extraServices. This is useful when you need to expose the same pods with different service configurations, such as exposing the API via a LoadBalancer in addition to the default ClusterIP service.

extraServices:
  - nameSuffix: "lb"
    type: LoadBalancer
    ports:
      - name: polaris-http
        port: 8181
        targetPort: 8181
        protocol: TCP
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: "nlb-ip"

This creates an additional service named <release-name>-polaris-lb of type LoadBalancer.

Gateway API🔗

The Kubernetes Gateway API is a more expressive and extensible alternative to Ingress. The Polaris Helm chart supports creating Gateway and HTTPRoute resources.

Prerequisites🔗

The Gateway API CRDs must be installed in your cluster. In most production environments, this is handled by cluster administrators. To install manually:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/latest/download/standard-install.yaml

You also need a Gateway controller (e.g., Envoy Gateway, Istio, Contour) installed and a GatewayClass defined.

Gateway Configuration🔗

The chart can create a Gateway resource that defines how traffic enters the cluster:

gateway:
  enabled: true
  className: "cluster-gateway"
  listeners:
    - name: http
      protocol: HTTP
      port: 80
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "polaris.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: polaris-tls
            kind: Secret

Gateway with Static IP Address🔗

Request a specific IP address for the Gateway:

gateway:
  enabled: true
  className: "eg"
  listeners:
    - name: http
      protocol: HTTP
      port: 80
  addresses:
    - type: IPAddress
      value: 192.168.1.100

HTTPRoute Configuration🔗

HTTPRoute defines how requests are routed from a Gateway to the Polaris service:

httproute:
  enabled: true
  gatewayName: "polaris-gateway" # Name of the Gateway to attach to
  gatewayNamespace: "polaris"    # Namespace where the Gateway is deployed
  hosts:
    - polaris.example.com

Using an External Gateway🔗

If you have a shared Gateway managed separately (e.g., by cluster administrators), you can create only the HTTPRoute:

gateway:
  enabled: false

httproute:
  enabled: true
  gatewayName: "shared-gateway"
  gatewayNamespace: "gateway-system"
  sectionName: "https"  # Optional: attach to a specific listener
  hosts:
    - polaris.example.com

Ingress🔗

Ingress provides HTTP(S) routing from outside the cluster to services within the cluster. Enable Ingress to expose Polaris externally.

Basic Ingress Configuration🔗

ingress:
  enabled: true
  className: "traefik"  # Your ingress controller class (e.g., "traefik", "haproxy", "contour")
  hosts:
    - host: polaris.example.com
      paths:
        - path: /
          pathType: Prefix

Ingress with TLS🔗

To enable TLS termination, create a Kubernetes secret containing your TLS certificate and reference it in the Ingress configuration:

kubectl create secret tls polaris-tls \
  --namespace polaris \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

ingress:
  enabled: true
  className: "traefik"  # Your ingress controller class
  hosts:
    - host: polaris.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: polaris-tls
      hosts:
        - polaris.example.com

Traffic Policies🔗

Both the main service and management service support traffic distribution policies:

Internal Traffic Policy🔗

Controls how traffic from within the cluster is routed:

service:
  internalTrafficPolicy: Local  # Route only to node-local endpoints

External Traffic Policy🔗

Controls how traffic from outside the cluster is routed (only applicable for NodePort and LoadBalancer services):

service:
  type: LoadBalancer
  externalTrafficPolicy: Local  # Preserve client source IP

Traffic Distribution (Kubernetes 1.31+)🔗

For Kubernetes 1.31 and later, you can use traffic distribution hints:

service:
  trafficDistribution: PreferClose  # Prefer topologically closer endpoints

Session Affinity🔗

For better performance, consider enabling session affinity to route requests from the same client to the same pod:

service:
  sessionAffinity: ClientIP