Skip to content

README.md

Latest commit

 

History

History
293 lines (202 loc) · 7.89 KB

README.md

File metadata and controls

293 lines (202 loc) · 7.89 KB

Dev Environment: "Kube" configuration

The Kube dev environment builds:

  • A single-node blockchain network
  • An Akash Provider Services Daemon (PSD) for bidding and running workloads.
  • A Kubernetes cluster for the PSD to run workloads on.

The instructions below will illustrate how to run a network with a single, local node and execute workloads in kind:

Setup

Four keys and accounts are created. The key names are:

Key Name Use
main Primary account (creating deployments, etc...)
provider The provider account (bidding on orders, etc...)
validator The sole validator for the created network
other Misc. account to (receives tokens, etc...)

Most make commands are configurable and have defaults to make it such that you don't need to override them for a simple pass-through of this example.

Name Default Description
KEY_NAME main standard key name
PROVIDER_KEY_NAME provider name of key to use for provider
DSEQ 1 deployment sequence
GSEQ 1 group sequence
OSEQ 1 order sequence
PRICE 10uakt price to bid

Runbook

The following steps will bring up a network and allow for interacting with it.

Running through the entire runbook requires three terminals. Each command is marked t1-t3 to indicate a suggested terminal number.

If at any time you'd like to start over with a fresh chain, simply run:

t1 run

make clean kind-cluster-clean
make init

Initialize

Start and initialize kind.

Kubernetes ingress objects present some difficulties for creating development environments. Two options are offered below - the first (random port) is less error-prone and can have multiple instances run concurrently, while the second option arguably has a better payoff.

note: this step waits for Kubernetes metrics to be available, which can take some time. The counter on the left side of the messages is regularly in the 120 range. If it goes beyond 250, there may be a problem.

Option t1 Step: 1 Explanation
Map random local port to port 80 of your workload make kind-cluster-setup This is less error-prone, but makes it difficult to access your app through the browser.
Map localhost port 80 to workload KIND_CONFIG=kind-config-80.yaml make kube-cluster-create-kind If anything else is listening on port 80 (any other web server), this method will fail. If it does succeed, you will be able to browse your app from the browser.

Build Akash binaries and initialize network

Initialize keys and accounts:

t1 Step: 2

make init

Run local network

In a separate terminal, the following command will run the akash node:

t2 Step: 3

make node-run

You can check the status of the network with:

t1 status

make node-status

You should see blocks being produced - the block height should be increasing.

You can now view genesis accounts that were created:

t1 status

make query-accounts

Create a provider

Create a provider on the network with the following command:

t1 Step: 4

make provider-create

View the on-chain representation of the provider with:

t1 status

make query-provider

Run Provider

To run Provider as a simple binary connecting to the cluster, in a third terminal, run the command:

t3 Step: 5

make provider-run

Query the provider service gateway for its status:

t1 status

make provider-status

Create a deployment

Create a deployment from the main account with:

t1 run Step: 6

make deployment-create

This particular deployment is created from the sdl file in this directory (deployment.yaml).

Check that the deployment was created. Take note of the dseq - deployment sequence:

t1 status

make query-deployments

After a short time, you should see an order created for this deployment with the following command:

make query-orders

The Provider Services Daemon should see this order and bid on it.

make query-bids

When a bid has been created, you may create a lease:

t1 run Step: 7

To create a lease, run

make lease-create

You can see the lease with:

make query-leases

You should now see "pending" inventory in the provider status:

make provider-status

Distribute Manifest

Now that you have a lease with a provider, you need to send your workload configuration to that provider by sending it the manifest:

t1 Step: 8

make send-manifest

You can check the status of your deployment with:

t1 status

make provider-lease-status

You can reach your app with the following (Note: Host: header tomfoolery abound)

t1 status

make provider-lease-ping

Get service status

t1 service status

make provider-lease-status

Fetch logs from deployed service (all pods)

t1 service logs

make provider-lease-logs

If you chose to use port 80 when setting up kind, you can browse to your deployed workload at http://hello.localhost

Update Deployment

Updating active Deployments is a two step process. First edit the deployment.yaml with whatever changes are desired. Example; update the image field.

  1. Update the Akash Network to inform the Provider that a new Deployment declaration is expected.
  • make deployment-update
  1. Send the updated manifest to the Provider to run.
  • make send-manifest

Between the first and second step, the prior deployment's containers will continue to run until the new manifest file is received, validated, and new container group operational. After health checks on updated group are passing; the prior containers will be terminated.

Limitations

Akash Groups are translated into Kubernetes Deployments, this means that only a few fields from the Akash SDL are mutable. For example image, command, args, env and exposed ports can be modified, but compute resources and placement criteria cannot.

Terminate lease

There are a number of ways that a lease can be terminated.

Provider closes the bid:

t1 teardown

make bid-close

Tenant closes the lease

t1 teardown

make lease-close

Tenant pauses the group

t1 teardown

make group-pause

Tenant closes the group

t1 teardown

make group-pause

Tenant closes the deployment

t1 teardown

make deployment-close

Iterate development