How the iris:// and gcp:// URL Schemes Enable Service Addressing in Marin

Marin uses iris:// and gcp:// URL schemes to abstract service locations, enabling cluster-aware resolution through Iris controllers or direct GCP lookups while maintaining backward compatibility with literal host:port addresses.

The Marin open-source project (marin-community/marin) implements a compact, URL-based notation to reference services across clusters and cloud providers. These schemes allow client code to remain agnostic of physical network locations while supporting both controlled cluster resolution and direct cloud provider addressing.

The Three Service Reference Forms

According to the Marin Service Architecture design document in docs/design/marin-service-architecture.md (lines 153-165), the system recognizes three distinct reference forms:

• host:port – A literal network address that bypasses all URL parsing and resolution logic.
• iris://<cluster>?endpoint=<name> – Resolves the service via the Iris controller of a named cluster.
• gcp://<vm-or-service-name> – Resolves a VM or managed service directly in Google Cloud Platform.

How the iris:// Scheme Resolves Services

The iris:// scheme implements cluster-aware service discovery through a deterministic four-step resolution process defined in docs/design/marin-service-architecture.md (lines 177-182).

Authority and Query Components

The URL structure contains two critical identifiers:

• Authority (<cluster>) – The cluster key (e.g., marin, openathena) that matches the --cluster flag and cluster-config files (lines 166-168).
• Query parameter – The endpoint=<name> value identifies a logical service name registered with the cluster's endpoints service.

The Resolution Algorithm

Resolution proceeds through these deterministic steps:

1. Locate the Iris controller VM for the specified cluster.
2. Connect to the controller's endpoints service.
3. Lookup the requested endpoint (e.g., /system/logger).
4. Return the concrete (host, port) tuple for client connection.

For example, accessing the system logging service uses:

client = LogClient.connect("iris://marin?endpoint=/system/logger")

The concrete implementation logic resides in the lib/iris/ directory, which contains the vm_address helper and endpoint lookup mechanisms referenced throughout the design document.

How the gcp:// Scheme Bypasses Iris Controllers

The gcp:// scheme provides direct cloud provider resolution that skips the Iris hop entirely. As documented in docs/design/marin-service-architecture.md (lines 197-199), this scheme maps provider-defined names to VM addresses using the generic vm_address helper.

This approach proves essential when services migrate off the Iris controller—such as dedicated logging VMs—while requiring no changes to existing client URLs. Rather than updating service references across the codebase, callers continue using gcp:// URLs that resolve directly to the underlying infrastructure.

# Direct GCP lookup without Iris mediation

db = DatabaseClient.connect("gcp://analytics-db")

Implementation Architecture

The current implementation uses Python 3.10+ pattern matching to dispatch URL schemes. The resolution logic contains a match statement (lines 93-100) that handles the three reference forms:

# Conceptual implementation based on design docs

match url.scheme:
    case "iris":
        return resolve_via_controller(url.cluster, url.endpoint)
    case "gcp":
        return vm_address(url.path)
    case _:
        return parse_literal_address(url)

This architecture supports extensibility; new schemes can be added by extending the match block. For deployments requiring numerous schemes, the design supports migrating to a resolver registry pattern when the number of schemes grows beyond a handful.

Practical Usage Patterns

Real-world usage in the Marin codebase demonstrates all three addressing strategies. The lib/finelog/ directory contains clients utilizing iris:// URLs, while bare addresses serve static infrastructure components.

Cluster-aware resolution:

logger = LogClient.connect("iris://marin?endpoint=/system/logger")

Direct cloud resolution:

db = DatabaseClient.connect("gcp://analytics-db")

Literal address (no resolution):

cache = CacheClient.connect("redis.internal:6379")

The bare host:port format provides a short-circuit that bypasses all URL parsing (lines 88-92), ensuring zero overhead for static network configurations.

Summary

• Marin abstracts service locations using iris:// for cluster-aware resolution and gcp:// for direct cloud provider lookups.
• The iris:// scheme resolves endpoints through a four-step process involving the Iris controller VM and endpoints service.
• The gcp:// scheme uses the vm_address helper to map names directly to GCP VM addresses without Iris mediation.
• Literal host:port addresses bypass all resolution logic for maximum performance.
• The implementation uses Python 3.10+ pattern matching defined in docs/design/marin-service-architecture.md, with concrete logic in lib/iris/ and usage examples in lib/finelog/.

Frequently Asked Questions

What is the difference between iris:// and gcp:// URLs in Marin?

iris:// URLs resolve services through the Iris controller, enabling cluster-aware discovery where the controller tracks which VM hosts a specific endpoint. gcp:// URLs resolve directly against Google Cloud Platform using the vm_address helper, bypassing the Iris controller entirely for services managed outside the cluster infrastructure.

How does Marin handle literal IP addresses or hostnames?

Marin treats strings matching the host:port pattern as literal addresses. According to the design document (lines 88-92), these bypass all URL parsing and resolution logic, connecting directly to the specified network location without consulting the Iris controller or GCP APIs.

Can I add custom URL schemes to Marin?

Yes. The current implementation uses a Python 3.10+ match statement to dispatch schemes (lines 93-100). You can extend this by adding new pattern cases to the match block. For production deployments with many schemes, the architecture supports migrating to a resolver registry pattern.

What cluster values are valid in iris:// URLs?

The authority component of an iris:// URL must match a cluster key defined in your cluster-config files, such as marin or openathena. This value corresponds to the --cluster flag used when deploying Iris controllers (lines 166-168).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}