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

> Learn how iris:// and gcp:// URL schemes in Marin abstract service locations for cluster-aware resolution and backward compatibility with host:port addresses.

- Repository: [The Marin Project/marin](https://github.com/marin-community/marin)
- Tags: internals
- Published: 2026-08-28

---

**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`](https://github.com/marin-community/marin/blob/main/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`](https://github.com/marin-community/marin/blob/main/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:

```python
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`](https://github.com/marin-community/marin/blob/main/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.

```python

# 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:

```python

# 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:**

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

```

**Direct cloud resolution:**

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

```

**Literal address (no resolution):**

```python
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`](https://github.com/marin-community/marin/blob/main/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).