kuberesolver

To use kuberesolver to resolve Kubernetes service addresses, you must register it with the gRPC resolver registry before calling grpc.NewClient.

For standard in-cluster usage, use kuberesolver.RegisterInCluster(). This uses a lightweight internal Kubernetes client to find service endpoints without significantly increasing binary size.

// Import the module
import "github.com/sercand/kuberesolver/v6"

// Register kuberesolver to grpc before calling grpc.NewClient
kuberesolver.RegisterInCluster()

To achieve zero-downtime deployments and connect to all available service endpoints, you must pass a loadBalancingPolicy via grpc.WithDefaultServiceConfig. Without this, gRPC will not create subconnections for each individual endpoint provided by the resolver.

Example using round_robin:

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

// ...

cc, err := grpc.NewClient(
    "kubernetes:///service:grpc", 
    grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`),
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)

The Event struct is the primary unit of notification. It wraps an EndpointSlice, which contains the actual network information (endpoints and ports) for a specific resource.

• Event: Contains the Type (EventType) and the Object (EndpointSlice).
• EndpointSlice: A collection of Endpoints and Ports available for a service.
• EndpointSliceList: A wrapper for a slice of EndpointSlice objects.

type Event struct {
	Type   EventType     `json:"type"`
	Object EndpointSlice `json:"object"`
}

type EndpointSlice struct {
	Endpoints []Endpoint
	Ports     []EndpointPort
}

type EndpointSliceList struct {
	Items []EndpointSlice
}

The kuberesolver supports several URI formats for resolving Kubernetes services. The resolver parses the service name, namespace, and port from these strings.

Port Resolution Logic:

• If the port is a number (e.g., :8080), it resolves to that specific port.
• If the port is a string (e.g., :http), it attempts to match the port by its name in the Kubernetes EndpointSlice.
• If no port is specified, it defaults to the first available port in the EndpointSlice.

If you want to use a different URI scheme (e.g., my-scheme://) instead of the default kubernetes://, use RegisterInClusterWithSchema. This allows you to define how the gRPC dialer identifies the resolver.

Note that you must provide a valid schema string.

import "github.com/sercand/sercand/kuberesolver"

// Register with a custom scheme
kuberesolver.RegisterInClusterWithSchema("my-custom-scheme")

To use kuberesolver as a gRPC name resolver, you must register its builder with the gRPC resolver registry. You can register it using the default kubernetes scheme or a custom schema.

If you are running inside a Kubernetes cluster, use RegisterInCluster() to automatically use the kubernetes scheme and an in-cluster Kubernetes client.

import "github.com/sercand/sercand/kuberesolver"

// Register with the default 'kubernetes://' scheme
kuberesolver.RegisterInCluster()

If you need to use a schema name other than the default kubernetes, use RegisterInClusterWithSchema(schema) during your application startup.

// Example of registering with a custom schema
kuberesolver.RegisterInClusterWithSchema("my-custom-schema")

Once registered, you can use the kubernetes:// scheme in your grpc.NewClient target string. The resolver supports several formats for specifying services and namespaces.

Note: The cluster_name part of a fully qualified domain name (e.g., test.default.svc.cluster.local) is supported for compatibility but is not actually used to resolve service endpoints.

// Standard formats
kubernetes:///service-name:8080
kubernetes:///service-name:portname
kubernetes:///service-name.namespace:8080
kubernetes:///service-name.namespace.svc.cluster_name
kubernetes:///service-name.namespace.svc.cluster_name:8080

// Alternative formats
kubernetes://namespace/service-name:8080
kubernetes://service-name:8080/
kubernetes://service-name.namespace:8080/
kubernetes://service-name.namespace.svc.cluster_name
kubernetes://service-name.namespace.svc.cluster_name:8080

Use NewInClusterK8sClient() to create a client configured for running inside a Kubernetes cluster. This constructor automatically loads the service account token and CA certificate from the standard Kubernetes secret paths (/var/run/secrets/kubernetes.io/serviceaccount/).

It also sets up a background file watcher to automatically update the client's bearer token if the service account token file is rotated or updated by Kubernetes.

Requirements:

• The environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT must be defined (standard for in-cluster pods).
• The service account token and CA cert must be present at their default locations.

client, err := kuberesolver.NewInClusterK8sClient()
if err != nil {
    log.Fatal(err)
}