Migration Path from Deployment v1 to v2 Manifests in Akash

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 (lines 21-22), the system calls:

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 (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 (lines 55-70) performs the following operations:

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:

   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:

   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 — Registers the deployment migration with the upgrade manager.
• upgrades/software/v0.24.0/upgrade.go — Implements the UpgradeHandler and migrateDeploymentGroup function that performs the actual state conversion.
• app/upgrades.go — Registers the v0.24.0 upgrade handler within the application's upgrade registry.
• _docs/adr/adr-001-network-upgrades.md — Documents the network upgrade workflow and migration registration patterns.
• _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 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 to perform the structural transformation between schema versions.

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