Minidisc is a zero-configuration service discovery tool designed specifically for Tailscale networks, facilitating the advertisement and discovery of gRPC or REST services within a Tailnet without the need for a central server. This peer-to-peer model ensures that as long as a service is operational, it can be readily discovered by clients.

Status

Currently, primary support for Minidisc is available for Python and Go. While users of other programming languages can utilize the command line tool md as a temporary solution, the only verified operating platform is Linux. As of now, Minidisc is actively employed in real-world scenarios, performing reliably, although it is still suggested for those looking for experimental enhancements rather than production-ready solutions.

How to Use

Client

Minidisc associates service names and corresponding key-value labels with IP:port pairs. To find a service, users need to specify the service name along with relevant labels. Minidisc will return the address of the first matching service it locates.

Example usage in Python:

import grpc
import minidisc

endpoint = minidisc.find_service('myservice', {'env': 'prod'})
channel = grpc.insecure_channel(endpoint)
# ... now use the channel to create gRPC stubs.

In Go, service discovery can be performed similarly:

import (
    "log"
    "github.com/mscheidegger/minidisc/go/pkg/minidisc"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    labels := map[string]string{"env": "prod"}
    addr, err := minidisc.FindService("myservice", labels)
    if err != nil {
	log.Fatalf("Minidisc is unavailable: %v", err)
    }
    clientConn, err := grpc.NewClient(
	addr.String(),
	grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    // ... now use the clientConn.
}

For those utilizing Go and gRPC exclusively, a custom resolver can simplify usage through URLs:

import (
    "github.com/mscheidegger/minidisc/go/pkg/mdgrpc"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    mdgrpc.RegisterResolver()
    clientConn, err := grpc.NewClient(
	"minidisc://myservices?env=prod",
	grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    // ... now use the clientConn.
}

Server

To advertise services within the Tailnet, a server must initialize a Minidisc Registry and add entries as needed. Both Go and Python offer similar mechanisms for starting the registry. Example in Go:

import (
    "github.com/mscheidegger/minidisc/go/pkg/minidisc"
)

func main() {
    registry, err := minidisc.StartRegistry()
    if err != nil {
	log.Fatalf("Minidisc is unavailable: %v", err)
    }
    labels := map[string]string{"env": "prod"}
    registry.AdvertiseService(port, "myservice", labels)
    // Now enter the serving loop.
}

Example in Python:

import minidisc

registry = minidisc.start_registry()
registry.advertise_service(port, 'myservice', {'env': 'prod'})
# Now enter the serving loop.

Command Line

Apart from the programming libraries, Minidisc includes a command line tool md, offering functionalities for service listing and discovery. To list services on the Tailnet:

md list

To locate a specific service:

md find myservice env=prod

To advertise services even from servers not directly compatible with Minidisc:

md advertise my-services.yaml

Check the example configuration here.

Docker

Running Minidisc within a Docker environment requires special setups due to Tailscale constraints. Below is a sample configuration demonstrating a shared volume for successful operation:

name: "foobar"
volumes:
  tailscale-socket: {}
services:
  ts-sidecar:
    image: tailscale/tailscale:latest
    hostname: foobar
    environment:
      - TS_AUTHKEY=$YOURKEY
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=false
      - TS_ACCEPT_DNS=true
      - TS_SOCKET=/var/run/tailscale/tailscaled.sock
    volumes:
      - ${PWD}/tailscale-foobar/state:/var/lib/tailscale
      - tailscale-socket:/var/run/tailscale
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
    restart: unless-stopped
  foobar:
    image: your/image:latest
    volumes:
      - tailscale-socket:/var/run/tailscale
    depends_on:
      - ts-sidecar
    network_mode: service:ts-sidecar
    restart: unless-stopped

Behind the Scenes

Minidisc operates as a simple peer-to-peer network, leveraging the trusted environment provided by Tailnets, thus bypassing complex routing typically found in standard peer-to-peer systems. Minidisc nodes aim to bind to port 28004 on their local Tailnet address. To enumerate available services, the client probes all active IP addresses on the Tailnet at this port, facilitating straightforward service discovery.