# How to Deploy Models with Marin-Deploy: A Complete Guide to ML Model Serving

> Deploy ML models effortlessly with Marin-Deploy. This guide shows how to use its command-line interface for seamless deployment to Kubernetes and cloud platforms.

- Repository: [The Marin Project/marin](https://github.com/marin-community/marin)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Marin-Deploy is the command-line entry point that ships with the marin-deploy package, providing a unified interface for deploying machine-learning models to Kubernetes or cloud platforms using declarative YAML configurations.**

Deploying machine-learning models to production requires reproducible infrastructure and streamlined workflows. Marin-Deploy, part of the marin-community/marin repository, is the official CLI tool designed specifically to deploy models with Marin-Deploy configurations across various backends including Kubernetes and Google Cloud Run.

## Understanding Marin-Deploy Architecture

Marin-Deploy operates as a Click-based CLI defined in [`infra/deploy/src/marin_deploy/cli.py`](https://github.com/marin-community/marin/blob/main/infra/deploy/src/marin_deploy/cli.py). The tool registers multiple sub-commands that handle different deployment targets. When you deploy models with Marin-Deploy, you interact with two primary components:

- **Finelog**: The primary model-serving deployment system implemented in [`infra/deploy/src/marin_deploy/finelog.py`](https://github.com/marin-community/marin/blob/main/infra/deploy/src/marin_deploy/finelog.py)
- **Pulumi Services**: Cloud-specific abstractions defined in [`infra/deploy/src/marin_deploy/pulumi.py`](https://github.com/marin-community/marin/blob/main/infra/deploy/src/marin_deploy/pulumi.py) for CoreWeave, GCP Cloud Run, and other platforms

## Installation and Setup

Before you can deploy models with Marin-Deploy, install the package from the infrastructure directory:

```bash
uv pip install -e infra/deploy

```

This installs the `marin-deploy` command-line entry point and its dependencies, including the Finelog configuration loader and Pulumi integration libraries.

## Creating a Finelog Deployment Configuration

Model deployments in Marin rely on YAML configuration files. The configuration schema, defined in [`lib/finelog/src/finelog/deploy/config.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/config.py) (lines 65-227), specifies container images, resource requirements, and Kubernetes namespaces.

### Configuration Schema Structure

A valid Finelog configuration requires the following structure:

```yaml
deployment:
  name: my-model-service
  k8s:
    namespace: models
  image: gcr.io/my-project/my-model:latest
  resources:
    cpu: "4"
    memory: "16Gi"

```

The `load_finelog_config` function—referenced in utilities like [`scripts/ops/storage/coreweave_usage.py`](https://github.com/marin-community/marin/blob/main/scripts/ops/storage/coreweave_usage.py)—validates this YAML against the schema and loads it into memory for processing.

## Deploying Models with the Finelog Command

The `finelog` sub-command is the primary method to deploy models with Marin-Deploy to Kubernetes clusters.

### Basic Model Deployment

Execute the deployment using your configuration file:

```bash
marin-deploy finelog --config finelog/config/my_model.yaml

```

When invoked, the CLI performs three critical operations:

1. **Loads the YAML** configuration using `load_finelog_config`
2. **Resolves the container image** to an immutable digest using the helper in [`lib/finelog/src/finelog/deploy/image.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/image.py), ensuring reproducible deployments
3. **Creates or updates the Kubernetes Deployment** through Pulumi abstractions defined in [`infra/deploy/src/marin_deploy/pulumi.py`](https://github.com/marin-community/marin/blob/main/infra/deploy/src/marin_deploy/pulumi.py)

### Validating Deployments with Dry-Run

To inspect what would be deployed without applying changes:

```bash
marin-deploy finelog --config finelog/config/my_model.yaml --dry-run

```

This validates your configuration and previews resource changes without modifying cluster state.

## Rollback and Revision Management

Marin-Deploy tracks deployment revisions using Kubernetes annotations. The revision-tracking logic resides in [`lib/finelog/src/finelog/deploy/_k8s.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/_k8s.py) (lines 187-263).

### Performing Rollbacks

To rollback to a previous revision:

```bash

# Identify the target revision number

kubectl get deployment sentiment-analyzer -n ml-models -o=jsonpath='{.metadata.annotations.finlog\.revision}'

# Execute rollback

marin-deploy finelog --config finelog/config/my_model.yaml --rollback 3

```

The workflow is deliberately idempotent—running the same command twice reconciles the live state with your YAML configuration without recreating resources unnecessarily.

## Alternative Deployment Targets

While Finelog targets Kubernetes, Marin-Deploy supports Pulumi-backed cloud services through the service group registered in [`infra/deploy/src/marin_deploy/pulumi.py`](https://github.com/marin-community/marin/blob/main/infra/deploy/src/marin_deploy/pulumi.py).

### Deploying to Google Cloud Run

To deploy the same model configuration to GCP Cloud Run instead of Kubernetes:

```bash
marin-deploy cloud-run --config finelog/config/my_model.yaml

```

This leverages the same YAML configuration but provisions serverless infrastructure through Pulumi rather than Kubernetes Deployments.

## Summary

- **Marin-Deploy** provides a unified CLI for deploying ML models through the `marin-deploy` package
- Deployments rely on **Finelog YAML configurations** specifying container images, resources, and namespaces
- The `finelog` sub-command handles Kubernetes deployments, while Pulumi services manage cloud platforms like Cloud Run
- **Image resolution** pins container tags to immutable digests for reproducibility
- **Idempotent operations** ensure safe repeated executions without unnecessary resource recreation
- **Rollback capabilities** leverage Kubernetes annotations tracked in [`lib/finelog/src/finelog/deploy/_k8s.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/_k8s.py)

## Frequently Asked Questions

### What is the difference between marin-deploy finelog and marin-deploy cloud-run?

The `finelog` sub-command deploys models to Kubernetes clusters using native Deployment resources, while `cloud-run` and other Pulumi-backed services provision serverless infrastructure on specific cloud providers. Both use the same YAML configuration format defined in [`lib/finelog/src/finelog/deploy/config.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/config.py), but target different execution environments through the abstractions in [`infra/deploy/src/marin_deploy/pulumi.py`](https://github.com/marin-community/marin/blob/main/infra/deploy/src/marin_deploy/pulumi.py).

### How does Marin-Deploy ensure reproducible model deployments?

Marin-Deploy enforces reproducibility through immutable image resolution. The helper in [`lib/finelog/src/finelog/deploy/image.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/image.py) resolves container tags to specific digests before deployment, ensuring that `gcr.io/project/model:latest` translates to an immutable SHA256 reference. This prevents accidental deployment of untested image versions.

### Can I deploy multiple models using a single configuration file?

While each YAML configuration typically defines a single deployment resource, you can orchestrate multiple model services by creating separate configuration files under `lib/finelog/config/` and invoking `marin-deploy finelog` separately for each. The tool processes one deployment configuration per invocation to maintain clear resource boundaries and rollback capabilities.

### What happens if a deployment fails during execution?

Marin-Deploy leverages Pulumi's state management and Kubernetes native health checks. If deployment fails, the previous healthy revision remains active. You can explicitly rollback to any prior revision using the `--rollback` flag followed by the revision number obtained from Deployment annotations, as implemented in [`lib/finelog/src/finelog/deploy/_k8s.py`](https://github.com/marin-community/marin/blob/main/lib/finelog/src/finelog/deploy/_k8s.py).