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:

1service:
2  type: ClusterIP
3  ports:
4    - name: polaris-http
5      port: 8181
6      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:

1managementService:
2  type: ClusterIP
3  clusterIP: None  # Headless service for metrics scraping
4  ports:
5    - name: polaris-mgmt
6      port: 8182
7      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.

 1extraServices:
 2  - nameSuffix: "lb"
 3    type: LoadBalancer
 4    ports:
 5      - name: polaris-http
 6        port: 8181
 7        targetPort: 8181
 8        protocol: TCP
 9    annotations:
10      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:

1kubectl 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:

 1gateway:
 2  enabled: true
 3  className: "cluster-gateway"
 4  listeners:
 5    - name: http
 6      protocol: HTTP
 7      port: 80
 8    - name: https
 9      protocol: HTTPS
10      port: 443
11      hostname: "polaris.example.com"
12      tls:
13        mode: Terminate
14        certificateRefs:
15          - name: polaris-tls
16            kind: Secret

Gateway with Static IP Address🔗

Request a specific IP address for the Gateway:

 1gateway:
 2  enabled: true
 3  className: "eg"
 4  listeners:
 5    - name: http
 6      protocol: HTTP
 7      port: 80
 8  addresses:
 9    - type: IPAddress
10      value: 192.168.1.100

HTTPRoute Configuration🔗

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

1httproute:
2  enabled: true
3  gatewayName: "polaris-gateway" # Name of the Gateway to attach to
4  gatewayNamespace: "polaris"    # Namespace where the Gateway is deployed
5  hosts:
6    - 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:

 1gateway:
 2  enabled: false
 3
 4httproute:
 5  enabled: true
 6  gatewayName: "shared-gateway"
 7  gatewayNamespace: "gateway-system"
 8  sectionName: "https"  # Optional: attach to a specific listener
 9  hosts:
10    - 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🔗

1ingress:
2  enabled: true
3  className: "traefik"  # Your ingress controller class (e.g., "traefik", "haproxy", "contour")
4  hosts:
5    - host: polaris.example.com
6      paths:
7        - path: /
8          pathType: Prefix

Ingress with TLS🔗

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

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

 1ingress:
 2  enabled: true
 3  className: "traefik"  # Your ingress controller class
 4  hosts:
 5    - host: polaris.example.com
 6      paths:
 7        - path: /
 8          pathType: Prefix
 9  tls:
10    - secretName: polaris-tls
11      hosts:
12        - 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:

1service:
2  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):

1service:
2  type: LoadBalancer
3  externalTrafficPolicy: Local  # Preserve client source IP

Traffic Distribution (Kubernetes 1.31+)🔗

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

1service:
2  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:

1service:
2  sessionAffinity: ClientIP