# Migration Path from Deployment v1 to v2 Manifests in Akash

> Learn the easy migration path from Akash deployment v1 to v2 manifests. Update your binary and let the network handle the automatic conversion during the v0.24.0 upgrade.

- Repository: [Akash Network/node](https://github.com/akash-network/node)
- Tags: migration-guide
- Published: 2026-02-24

---

**The migration from deployment v1 to v2 manifests occurs automatically during the Akash Network v0.24.0 upgrade, requiring only a binary update and scheduled software-upgrade proposal to convert all stored deployment groups from v1beta2 to v2beta2 schema.**

The akash-network/node repository handles the transition between manifest schemas through an automated state migration introduced in upgrade `v0.24.0`. This process eliminates manual intervention for existing deployments while enabling the enhanced v2beta2 manifest format for new workloads.

## Understanding the Schema Versions

Akash Network maintains two distinct deployment schemas within the codebase. The legacy **v1beta2** schema (deployment v1) uses an older protobuf structure for deployment groups, while the modern **v2beta2** schema introduces the current manifest format with improved validation and structure. The migration path upgrades all on-chain state from the legacy format to the new standard.

## Automated Migration Architecture

The migration executes automatically when the network reaches the designated upgrade height. According to the Akash node source code, the process follows three distinct phases orchestrated through the Cosmos SDK upgrade module.

### Phase 1: Migration Registration

The upgrade registers the deployment migration during initialization. In [`upgrades/software/v0.24.0/init.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/init.go) (lines 21-22), the system calls:

```go
utypes.RegisterMigration(dv1beta3.ModuleName, 2, newDeploymentMigration)

```

The version **2** parameter signifies the migration from v1beta2 to v2beta2. This registration links the deployment module to the migration handler that executes at the upgrade height.

### Phase 2: Migrator Initialization

The `newDeploymentMigration` function returns a specialized struct that implements the migration interface. Located in [`upgrades/software/v0.24.0/upgrade.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/upgrade.go) (lines 31-44), this `deploymentMigrations` struct embeds `utypes.Migrator` and provides the context needed to access the KV store and codec during the upgrade.

### Phase 3: State Transformation

The core conversion logic executes within the `UpgradeHandler` function. The handler iterates through every stored deployment group in the database, converting each from the legacy format to v2beta2. The implementation in [`upgrades/software/v0.24.0/upgrade.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/upgrade.go) (lines 55-70) performs the following operations:

```go
func migrateDeploymentGroup(fromBz []byte, cdc codec.BinaryCodec) codec.ProtoMarshaler {
    var from dv1beta2.Group
    cdc.MustUnmarshal(fromBz, &from)

    // Convert legacy group → v2beta2 group
    to := dmigrate.GroupFromV1Beta2(from)
    return &to
}

```

The `dmigrate.GroupFromV1Beta2` function, imported from `github.com/akash-network/akash-api/go/manifest/v2beta2/dmigrate`, handles the structural translation between protobuf definitions. After conversion, the new v2beta2 group is serialized and written back to the KV store.

## Operator Implementation Steps

Network operators and validators must complete the following steps to execute the migration path:

1. **Upgrade the binary** to version `v0.24.0` or later to ensure the migration code exists in the node software.

2. **Submit the software-upgrade proposal** using the Akash CLI to schedule the upgrade at a specific block height:

   ```bash
   akash tx gov submit-proposal software-upgrade \
     --title "Akash v0.24.0" \
     --description "Migrate deployments to v2beta2 manifests" \
     --upgrade-name v0.24.0 \
     --upgrade-height 1234567 \
     --from <your-key>
   ```

3. **Wait for the upgrade height** — when the network reaches the specified block, the node automatically executes `up.MM.RunMigrations()`, triggering the deployment migration. Node logs will indicate: `"all migrations have been completed"` and `"deployment store migration complete"`.

4. **Deploy using the new schema** — after the upgrade, submit new deployments using the v2beta2 manifest format:

   ```yaml
   version: "2.0"
   services:
     web:
       image: nginx:latest
       expose:
         - port: 80
           as: 80
           proto: tcp
   profiles:
     compute:
       cpu: 500m
       memory: 256Mi
     storage:
       size: 1Gi
   ```

   Submit the manifest with: `akash tx deployment create my-deployment.yaml --from <your-key>`.

## Key Implementation Files

The migration path relies on specific files within the akash-network/node repository:

- **[`upgrades/software/v0.24.0/init.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/init.go)** — Registers the deployment migration with the upgrade manager.
- **[`upgrades/software/v0.24.0/upgrade.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/upgrade.go)** — Implements the `UpgradeHandler` and `migrateDeploymentGroup` function that performs the actual state conversion.
- **[`app/upgrades.go`](https://github.com/akash-network/node/blob/main/app/upgrades.go)** — Registers the v0.24.0 upgrade handler within the application's upgrade registry.
- **[`_docs/adr/adr-001-network-upgrades.md`](https://github.com/akash-network/node/blob/main/_docs/adr/adr-001-network-upgrades.md)** — Documents the network upgrade workflow and migration registration patterns.
- **[`_docs/adr/adr-002-manifest-v2beta2.md`](https://github.com/akash-network/node/blob/main/_docs/adr/adr-002-manifest-v2beta2.md)** — Defines the v2beta2 manifest specification and validation rules.

## Summary

- The migration from deployment v1 (v1beta2) to v2 (v2beta2) executes automatically during the **v0.24.0** network upgrade.
- Operators need only upgrade their node binary and pass a software-upgrade proposal; no manual state export or import is required.
- The migration handler in [`upgrades/software/v0.24.0/upgrade.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/upgrade.go) converts each stored deployment group using `dmigrate.GroupFromV1Beta2`.
- After the upgrade height, all existing deployments are accessible in the new format, and new deployments must use the v2beta2 manifest schema.

## Frequently Asked Questions

### What happens to existing deployments during the migration?

Existing deployments remain active and accessible throughout the migration. The upgrade handler reads each stored `dv1beta2.Group` from the database, converts it to `v2beta2.Group` format, and writes it back to the same KV store keys. The process preserves deployment state, lease relationships, and provider assignments without requiring workload restarts.

### Do I need to update my provider nodes separately?

Provider nodes must run a binary version compatible with v0.24.0 or later to process the new v2beta2 manifests. However, providers do not need to manually migrate any data; the on-chain deployment state migration handled by validators ensures that all deployment queries return the new format automatically after the upgrade height.

### Can I still submit manifests using the old v1beta2 format after the upgrade?

No. Once the network passes the v0.24.0 upgrade height, the deployment module only accepts manifests conforming to the v2beta2 schema. Clients attempting to submit v1beta2 manifests will receive validation errors. You must update your deployment YAML files to use the `version: "2.0"` structure and v2beta2-specific field definitions.

### Where is the core conversion logic located?

The protobuf conversion logic resides in the `github.com/akash-network/akash-api` repository, specifically within `go/manifest/v2beta2/dmigrate`. The Akash node imports this package and calls `dmigrate.GroupFromV1Beta2()` within the `migrateDeploymentGroup` function in [`upgrades/software/v0.24.0/upgrade.go`](https://github.com/akash-network/node/blob/main/upgrades/software/v0.24.0/upgrade.go) to perform the structural transformation between schema versions.