Guide to Deploy CockcroachDB on Akash

Deploying CockroachDB on Akash Network

This guide demonstrates how to deploy CockroachDB, a cloud-native distributed SQL database, on the Akash Network. Akash is a decentralized cloud computing platform where you can host containerized applications.

Prerequisites

  1. Akash CLI: Installed and configured with your wallet and access to testnet/mainnet.
  2. Docker: To create a container for CockroachDB.
  3. CockroachDB Docker Image: Official image from cockroachdb/cockroach.
  4. Akash SDL Template: A pre-configured SDL file for deployment.

Steps

1. Prepare the CockroachDB Deployment

CockroachDB can be run as a standalone instance or as a cluster. For this guide, we will deploy a single-node instance.

2. Write the SDL File

Create a file named deploy.yaml and add the following SDL configuration:

version: "2.0"


services:
  cockroachdb:
    image: cockroachdb/cockroach:v23.1.1 # Replace with the desired version
    expose:
      - port: 26257
        as: 26257
        to:
          - global: true # Expose to the public internet
      - port: 8080
        as: 8080
        to:
          - global: true
    args:
      - start-single-node
      - --insecure # For simplicity, remove this for production use


profiles:
  compute:
    cockroachdb:
      resources:
        cpu:
          units: 2
        memory:
          size: 2Gi
        storage:
          size: 10Gi


  placement:
    cockroachdb:
      pricing:
        cockroachdb:
          denom: uakt
          amount: 100 # Specify your budget


deployment:
  cockroachdb:
    cockroachdb:
      profile: cockroachdb
      count: 1

Explanation of the SDL File:

  • image: The Docker image for CockroachDB.
  • expose: Ports 26257 (SQL) and 8080 (Web UI) are exposed for access.
  • args: Starts a single-node CockroachDB instance in insecure mode for simplicity.
  • resources: Configures compute, memory, and storage requirements.
  • pricing: Sets the budget in uakt (Akash tokens).

3. Deploy the SDL File

  • Create your Certificate

Akash requires an account to have a valid certificate associated with it to start participating in the deployment process. In this section of the guide, we will create a certificate locally, and then proceed to store this certificate on the Akash blockchain. To do this, ensure you have followed all the steps outlined in this guide up to this point. Additionally, these transactions must be executed from an Akash account in possession of some $AKT tokens.

Once an account has a certificate associated with it, it can begin deploying services on the Akash blockchain. A certificate needs to be created only once per account. After creation, it can be used across any number of deployments for as long as it remains valid.

provider-services tx cert generate client -from $AKASH_KEY_NAME
  • Publish Cert to the Blockchain
provider-services tx cert publish client -from $AKASH_KEY_NAME

  • Create your Deployment

  • CPU Support

Only x86_64 processors are officially supported for Akash deployments. This may change in the future and when ARM processors are supported it will be announced and documented.

  • Akash Deployment

NOTE: if your current terminal session has been used to create prior deployments, issue the command unset AKASH_DSEQ to prevent receipt of error message Deployment Exists

To deploy on Akash, run:

provider-services tx deployment create deploy.yaml -from $AKASH_KEY_NAME

You should see a response similar to:

{
  "height":"140325",
  "txhash":"2AF4A01B9C3DE12CC4094A95E9D0474875DFE24FD088BB443238AC06E36D98EA",
  "codespace":"",
  "code":0,
  "data":"0A130A116372656174652D6465706C6F796D656E74",
  "raw_log":"[{\"events\":[{\"type\":\"akash.v1\",\"attributes\":[{\"key\":\"module\",\"value\":\"deployment\"},{\"key\":\"action\",\"value\":\"deployment-created\"},{\"key\":\"version\",\"value\":\"2b86f778de8cc9df415490efa162c58e7a0c297fbac9cdb8d6c6600eda56f17e\"},{\"key\":\"owner\",\"value\":\"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj\"},{\"key\":\"dseq\",\"value\":\"140324\"},{\"key\":\"module\",\"value\":\"market\"},{\"key\":\"action\",\"value\":\"order-created\"},{\"key\":\"owner\",\"value\":\"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj\"},{\"key\":\"dseq\",\"value\":\"140324\"},{\"key\":\"gseq\",\"value\":\"1\"},{\"key\":\"oseq\",\"value\":\"1\"}]},{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"create-deployment\"},{\"key\":\"sender\",\"value\":\"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj\"},{\"key\":\"sender\",\"value\":\"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj\"}]},{\"type\":\"transfer\",\"attributes\":[{\"key\":\"recipient\",\"value\":\"akash17xpfvakm2amg962yls6f84z3kell8c5lazw8j8\"},{\"key\":\"sender\",\"value\":\"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj\"},{\"key\":\"amount\",\"value\":\"5000uakt\"},{\"key\":\"recipient\",\"value\":\"akash14pphss726thpwws3yc458hggufynm9x77l4l2u\"},{\"key\":\"sender\",\"value\":\"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj\"},{\"key\":\"amount\",\"value\":\"5000000uakt\"}]}]}]",
  "logs":[
    {
      "msg_index":0,
      "log":"",
      "events":[
        {
          "type":"akash.v1",
          "attributes":[
            {
              "key":"module",
              "value":"deployment"
            },
            {
              "key":"action",
              "value":"deployment-created"
            },
            {
              "key":"version",
              "value":"2b86f778de8cc9df415490efa162c58e7a0c297fbac9cdb8d6c6600eda56f17e"
            },
            {
              "key":"owner",
              "value":"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj"
            },
            {
              "key":"dseq",
              "value":"140324"
            },
            {
              "key":"module",
              "value":"market"
            },
            {
              "key":"action",
              "value":"order-created"
            },
            {
              "key":"owner",
              "value":"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj"
            },
            {
              "key":"dseq",
              "value":"140324"
            },
            {
              "key":"gseq",
              "value":"1"
            },
            {
              "key":"oseq",
              "value":"1"
            }
          ]
        },
        {
          "type":"message",
          "attributes":[
            {
              "key":"action",
              "value":"create-deployment"
            },
            {
              "key":"sender",
              "value":"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj"
            },
            {
              "key":"sender",
              "value":"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj"
            }
          ]
        },
        {
          "type":"transfer",
          "attributes":[
            {
              "key":"recipient",
              "value":"akash17xpfvakm2amg962yls6f84z3kell8c5lazw8j8"
            },
            {
              "key":"sender",
              "value":"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj"
            },
            {
              "key":"amount",
              "value":"5000uakt"
            },
            {
              "key":"recipient",
              "value":"akash14pphss726thpwws3yc458hggufynm9x77l4l2u"
            },
            {
              "key":"sender",
              "value":"akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj"
            },
            {
              "key":"amount",
              "value":"5000000uakt"
            }
          ]
        }
      ]
    }
  ],
  "info":"",
  "gas_wanted":"100000",
  "gas_used":"94653",
  "tx":null,
  "timestamp":""
}
  • Find your Deployment -

Find the Deployment Sequence (DSEQ) in the deployment you just created. You will need to replace the AKASH_DSEQ with the number from your deployment to configure a shell variable.

Terminal window
export AKASH_DSEQ=CHANGETHIS

Now set the Order Sequence (OSEQ) and Group Sequence (GSEQ). Note that if this is your first time deploying on Akash, OSEQ and GSEQ will be 1.

Terminal window
AKASH_OSEQ=1
AKASH_GSEQ=1

Verify we have the right values populated by running:

Terminal window
echo $AKASH_DSEQ $AKASH_OSEQ $AKASH_GSEQ
  • View your Bids

After a short time, you should see bids from providers for this deployment with the following command:

Terminal window
provider-services query market bid list -owner=$AKASH_ACCOUNT_ADDRESS -node $AKASH_NODE -dseq $AKASH_DSEQ -state=open
  • Choose a Provider

Note that there are bids from multiple different providers. In this case, both providers happen to be willing to accept a price of 1 uAKT. This means that the lease can be created using 1 uAKT or 0.000001 AKT per block to execute the container. You should see a response similar to:

bids:
- bid:
    bid_id:
      dseq: "140324"
      gseq: 1
      oseq: 1
      owner: akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj
      provider: akash10cl5rm0cqnpj45knzakpa4cnvn5amzwp4lhcal
    created_at: "140326"
    price:
      amount: "1"
      denom: uakt
    state: open
  escrow_account:
    balance:
      amount: "50000000"
      denom: uakt
    id:
      scope: bid
      xid: akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj/140324/1/1/akash10cl5rm0cqnpj45knzakpa4cnvn5amzwp4lhcal
    owner: akash10cl5rm0cqnpj45knzakpa4cnvn5amzwp4lhcal
    settled_at: "140326"
    state: open
    transferred:
      amount: "0"
      denom: uakt
- bid:
    bid_id:
      dseq: "140324"
      gseq: 1
      oseq: 1
      owner: akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj
      provider: akash1f6gmtjpx4r8qda9nxjwq26fp5mcjyqmaq5m6j7
    created_at: "140326"
    price:
      amount: "1"
      denom: uakt
    state: open
  escrow_account:
    balance:
      amount: "50000000"
      denom: uakt
    id:
      scope: bid
      xid: akash1vn06ycjjnvsvl639fet9lajjctuturrtx7fvuj/140324/1/1/akash1f6gmtjpx4r8qda9nxjwq26fp5mcjyqmaq5m6j7
    owner: akash1f6gmtjpx4r8qda9nxjwq26fp5mcjyqmaq5m6j7
    settled_at: "140326"
    state: open
    transferred:
      amount: "0"
      denom: uakt

For this example, we will choose akash10cl5rm0cqnpj45knzakpa4cnvn5amzwp4lhcal Run this command to set the provider shell variable:

AKASH_PROVIDER=akash10cl5rm0cqnpj45knzakpa4cnvn5amzwp4lhcal

Verify we have the right value populated by running:

echo $AKASH_PROVIDER
  • Create a Lease

Create a lease for the bid from the chosen provider above by running this command:

provider-services tx market lease create -dseq $AKASH_DSEQ -provider $AKASH_PROVIDER -from $AKASH_KEY_NAME
  • Confirm the Lease

You can check the status of your lease by running:

provider-services query market lease list -owner $AKASH_ACCOUNT_ADDRESS -node $AKASH_NODE -dseq $AKASH_DSEQ

Note the bids will close automatically after 5 minutes, and you may get the response:

bid not open

If this happens, close your deployment and open a new deployment again. To close your deployment run this command:

provider-services tx deployment close -dseq $AKASH_DSEQ  -owner $AKASH_ACCOUNT_ADDRESS -from $AKASH_KEY_NAME

If your lease was successful you should see a response that ends with:

    state: active

NOTE: Please note that once the lease is created, the provider will begin debiting your deployment’s escrow account, even if you have not completed the deployment process by uploading the manifest in the following step.

  • Send the Manifest

Upload the manifest using the values from above step:

provider-services send-manifest deploy.yaml -dseq $AKASH_DSEQ -provider $AKASH_PROVIDER -from $AKASH_KEY_NAME
  • Confirm the URL

Now that the manifest is uploaded, your image is deployed. You can retrieve the access details by running the below:

provider-services lease-status -dseq $AKASH_DSEQ -from $AKASH_KEY_NAME -provider $AKASH_PROVIDER

You should see a response similar to:

{
  "services": {
    "web": {
      "name": "web",
      "available": 1,
      "total": 1,
      "uris": [
        "rga3h05jetf9h3p6dbk62m19ck.ingress.ewr1p0.mainnet.akashian.io"
      ],
      "observed_generation": 1,
      "replicas": 1,
      "updated_replicas": 1,
      "ready_replicas": 1,
      "available_replicas": 1
    }
  },
  "forwarded_ports": {}
}

You can access the application by visiting the hostnames mapped to your deployment. Look for a URL/URI and copy it to your web browser.

  • View your logs

You can view your application logs to debug issues or watch progress like so:

Terminal window
provider-services lease-logs \
  -dseq "$AKASH_DSEQ" \
  -provider "$AKASH_PROVIDER" \
  -from "$AKASH_KEY_NAME"

  • Update the Deployment

  • Update the Manifest

Update the deploy.yaml manifest file with the desired change.

NOTE: Not all attributes of the manifest file are eligible for deployment update. If the hardware specs of the manifest are updated (I.e. CPU count), a re-deployment of the workload is necessary. Other attributes, such as deployment image and funding, are eligible for updates.

  • Issue Transaction for On Chain Update
provider-services tx deployment update deploy.yaml -dseq $AKASH_DSEQ -from $AKASH_KEY_NAME
  • Send Updated Manifest to Provider
provider-services send-manifest deploy.yaml -dseq $AKASH_DSEQ -provider $AKASH_PROVIDER -from $AKASH_KEY_NAME
### 4. Access CockroachDB
- **SQL Port**: Access the SQL interface on `26257`.
- **Web UI**: Access the CockroachDB web UI on `8080` using the Akash-leased hostname.


Example:

http://:8080

---


### 5. Test and Verify
1. Use the `cockroach sql` command to connect:

cockroach sql —url “postgresql://:26257?sslmode=disable”

2. Use the Web UI to verify that the database is running.


---


### 6. (Optional) Scaling to a Cluster


To deploy a multi-node CockroachDB cluster, adjust the SDL file as follows:


**Key Modifications**:


 Increase the `node count` under `deployment.cockroachdb.count`.
 Modify `args` to remove `start-single-node` and add `--join `for clustering.
 Use a shared network so nodes can communicate.


Updated deploy.yaml for Multi-Node Deployment:

version: “2.0”

services: cockroachdb: image: cockroachdb/cockroach

.1.1 expose: - port: 26257 as: 26257 to: - global: true - port: 8080 as: 8080 to: - global: true args: - start - —insecure - —join=cockroachdb-0,cockroachdb-1,cockroachdb-2

profiles: compute: cockroachdb: resources: cpu: units: 2 memory: size: 2Gi storage: size: 10Gi

placement: cockroachdb: pricing: cockroachdb: denom: uakt amount: 100

deployment: cockroachdb: cockroachdb: profile: cockroachdb count: 3 # Deploys 3 nodes

**Explanation of Changes**:


- `count: 3` → Deploys 3 CockroachDB nodes.
- `--join=cockroachdb-0,cockroachdb-1,cockroachdb-2` → Ensures nodes form a cluster.
- Retains `--insecure` for simplicity (remove for production).
- Exposed ports remain the same.






---


### Notes
- Replace `--insecure` with SSL certificates for production deployments.
- Monitor resources to ensure your Akash deployment meets CockroachDB’s performance requirements.
- Use persistent storage configurations if required.


This deployment method leverages CockroachDB's containerized image and Akash's decentralized cloud for a cost-effective and distributed database solution.
Edit page on github
AnzoGraph Couchbase
footer-logo-dark

© Akash Network 2025 The Akash Network Authors Documentation Distributed under CC BY 4.0

Open-source Apache 2.0 Licensed.

GitHub v0.38.2

Privacy