Akash Version 0.14.0

Prerequisites

The sections which follow detail Akash deployment configuration and management features introduced in version 0.14.0. Ensure the Akash CLI version is upgraded to 0.14.0 prior to command execution and usage.
The SDL code samples encompassed throughout this guide are available in the “Full SDL Code Base Utilized” section as a single complete code base.

Deployment Shell Access

Abilities to manage deployed Akash containers have been accentuated greatly within this release. Introduced deployment capabilities include:
  • Ability to execute commands within running Linux containers/Akash deployments. Such an ability resembles “docker exec” command execution within a live container instance.
  • Ability to gain access to the CLI/shell of a running Linux container/Akash deployment.
  • Ability to remote copy files from running Linux containers/Akash deployments to a local file instance for inspection.
In the subsections which follow granular details of these introduced features will be explored with example executions and depictions.

Remote Shell Command Execution

Execute command sets within a running Akash deployment
  • Command template with variable bracketing as such <variable-name>
  • Notes of interest pertaining to command execution:
    • The service-name variable must match the service value in the deployment’s SDL. For example - in the depicted segment of an SDL file below - the service-name in remote shell execution would be “web”
1
akash provider lease-shell --from <key-name> --dseq <dseq-number> --provider=<provider-address> <service-name> <command-to-execute>
Copied!
  • Example command fully populated
1
akash provider lease-shell --from mykey --dseq 226186 --provider=akash1gx4aevud37w4d6kfd5szgp87lmkqvumaz57yww web cat /etc/passwd
Copied!
  • Example command fully populated using environment variables
  • Prior establishment of the AKASH_KEY_NAME and AKASH_PROVIDER environment variables would be necessary to allow this syntax
1
akash provider lease-shell --from $AKASH_KEY_NAME --dseq 226186 --provider=$AKASH_PROVIDER web cat /etc/passwd
Copied!
  • Expected output example

Access the Deployment Shell (CLI)

Gain access to an active Akash deployment’s CLI/shell
  • Command template with variable bracketing as such <variable-name>
  • Command notes of interest:
    • The service-name variable must match the service value in the deployment’s SDL. For example - in the depicted segment of an SDL file below - the service-name in remote shell execution would be “web”
    • Note the “tty” switch dictating desire for shell/CLI access
1
akash provider lease-shell --from <key-name> --dseq <dseq-number> --tty --provider=<provider-address> <service-name> /bin/sh
Copied!
  • Example command fully populated
  • Note - the container instance must have a /bin/sh shell for the command to work in this exact syntax. If this were an Alpine container base image /bin/sh would need to become /bin/ash and this serves as an example of possible edit to the command syntax based on container type.
1
akash provider lease-shell --from mykey --dseq 226186 --tty --provider=akash1gx4aevud37w4d6kfd5szgp87lmkqvumaz57yww web /bin/sh
Copied!
  • Example command fully populated using environment variables
  • Prior establishment of the AKASH_KEY_NAME and AKASH_PROVIDER environment variables would be necessary to allow this syntax
1
akash provider lease-shell --from $AKASH_KEY_NAME --dseq 226186 --tty --provider=$AKASH_PROVIDER web /bin/sh
Copied!
  • Expected output example
  • Note - Linux commands “pwd” and “ls” are included and as executed within the deployment to validate Akash container shell access

Copy File from Akash Container/Deployment

Copy a file from an active Akash deployment to a local file instance for inspection
  • Command template with variable bracketing as such <variable-name>
  • Command notes of interest:
    • The service-name variable must match the service value in the deployment’s SDL. For example - in the depicted segment of an SDL file below - the service-name in remote shell execution would be “web”
1
akash provider lease-shell --from <key-name> --dseq <dseq-number> --provider=<provider-address> <service-name> <command-to-execute> > <local-file-name>
Copied!
  • Example command fully populated
1
akash provider lease-shell --from mykey --dseq 226186 --provider=akash1gx4aevud37w4d6kfd5szgp87lmkqvumaz57yww web cat /etc/passwd > local_copy_of_passwd
Copied!
  • Example command fully populated using environment variables
  • Prior establishment of the AKASH_KEY_NAME and AKASH_PROVIDER environment variables would be necessary to allow this syntax
1
akash provider lease-shell --from $AKASH_KEY_NAME --dseq 226186 --provider=$AKASH_PROVIDER web cat /etc/passwd > local_copy_of_passwd
Copied!
  • Expected output example
  • Note - Linux command “ls” and “cat” are included in the depiction to validate successful file copy from remote Akash container/deployment to local file

Deployment HTTP Options (SDL Definitions)

Akash deployment SDL services stanza definitions have been augmented to include “http_options” allowing granular specification of HTTP endpoint parameters. Inclusion of the parameters in this section are optional but will afford detailed definitions of attributes such as body/payload max size where necessary.

Overview

The following “http_options” have been introduced in this version. In subsequent sections of this guide the placement of “http_options” within the SDL services stanza will be detailed.
  • Max_body_size - sets the maximum size of an individual HTTP request body
  • Read_timeout - duration the proxy will wait for a response from the service
  • Send_timeout - duration the proxy will wait for the service to accept a request
  • Next_cases - defines the cases where the proxy will try another replica in the service. Reference the upcoming “Next Cases Attribute Usage” section for details pertaining to allowed values.
  • Next_tries - number of attempts the proxy will attempt another replica

Example HTTP Options Usage

  • Depiction displays the placement and structure of the http_options key within the greater services section and within a specific service’s expose key.
  • Service section of the greater SDL isolated for focus.
  • Depiction displays the placement of http_options within the entire, greater SDL definition

Next Cases Attribute Usage

The “http_options” key of “next_cases” accepts an array of values which may contain one or more of the following values. When included in the “next_cases” array value - the specified HTTP response code/message will provoke an attempt to service the request by one of the other container members/replicas of the deployment. The “next_cases” attempt to service via an additional container will only provoke if the SDL defines a count of greater than one (1). A deployment with a count of one (1) would have no other replicas to facilitate the additional service attempt.
  • “error”
  • “timeout”
  • “403”
  • “404”
  • “429”
  • “500”
  • “502”
  • “503”
  • “504”
  • “off”

Hostname Migration

Deployment of an updated workload encounters a challenge when the DNS hostname remains active on the existing deployment. An example scenario is presented to ensure understanding of the challenge - followed by a review of the mechanism introduced in this release to migrate a hostname to the new deployment.

Overview of Hostname Migration Need

In this scenario two identical deployments will be launched mimicking an initial instance/deployment and a secondary updated deployment.
The following SDL is utilized in this example. Note the presence of the highlighted accept key dictating the DNS name of the deployment (supermariotest.akash.network).
  • Two instances of the deployment are provoked (referred to as “OriginalDeployment” and “UpdatedDeployment” in this guide for clarity)
  • The OriginalDeployment lease status displays URIs for both the Akash full domain name (ending in akashian.io) and the SDL specified domain name of “supermariotest.akash.network”
  • Note - the DSEQ for this deployment is - 241027. The DSEQ reference point will be of importance for later validations.
  • The UpdatedDeployment lease status displays a single URI - the Akash full domain name (ending in akashian.io) - and the SDL specified domain name of “supermariotest.akash.network” is not present
  • The hostname of “supermariotest.akash.network” was not migrated when the new deployment generated despite the declaration of the hostname in the SDL’s accept key-value pair
  • If the initial deployment (OriginalDeployment) had been destroyed prior to the creation of the upgraded instance (UpdatedDeployment) the hostname would have been free and the new deployment would have assumed this domain name per the SDL specification.
  • But often to ensure continuity of services the desirable strategy would be to activate the new instance prior to removing a pre-existing instance and only migrate production traffic to a readied upgraded instance.
  • The hostname migration commands introduced - and discussed subsequently - allows such graceful migration.
  • Note - the DSEQ for the UpdatedDeployment is - 241064. The DSEQ reference point will be of importance for later validations.

Hostname Migration Command

The example hostname migration will continue with the two deployment scenarios provoked in the prior sub-section.
  • Hostname migration command syntax with variable bracketing as such <variable-name>
1
akash provider migrate-hostnames --from <key-name> --dseq <dseq-number> --provider=<provider-address> <hostname>
Copied!
  • Example, populated hostname migration command
  • In referencing the deployment DSEQ the hostname is migrated to the UpdatedDeployment instance with a DSEQ of 241064 and simultaneously removing the hostname from OriginalDeployment (DSEQ 241027)
1
akash provider migrate-hostnames --from mykey --dseq 241064 --provider=akash1gx4aevud37w4d6kfd5szgp87lmkqvumaz57yww supermariotest.akash.network
Copied!

Validation of Hostname Migration

Hostname/URI Configuration Validations

Validations of hostname migration are provided in the sample OriginalDeployment and UpdatedDeployment scenario.
  • The lease-status command is utilized in the section to display active URIs/hostnames associated with specific deployments
  • The syntax for the lease-status command is as follows
1
akash provider lease-status --node $AKASH_NODE --home ~/.akash --dseq $AKASH_DSEQ --from $AKASH_KEY_NAME --provider $AKASH_PROVIDER
Copied!
  • In the depiction which follows the state of the OriginalDeployment instance proves:
    • Prior to the migrate-hostnames command invoke the hostname specified in the SDL is married to the instance
    • The migrate-hostnames command is invoked specifying the DSEQ of the upgraded deployment instance
    • Post invoke of migrate-hostnames the SDL specified hostname is no longer married to the original instance
  • In the depiction which follows the state of the UpgradedDeployment instance proves:
    • Post migrate-hostnames command invoke the hostname has been migrated to the upgraded deployment instance
    • If desired and in an event in which the upgrade deployment was not servicing traffic correctly - the hostname could be migrated back to OriginalDeployment using the identical migrate-hostname command set but with the OriginalDeployment DSEQ specified

Connectivity Test Validations

As discussed prior - in a production environment it may be advantageous to leave the pre-existing deployment (I.e. OriginalDeployment in this guide’s scenario) in place post migration for possible fallback scenarios. But to validate connectivity has migrated successfully - the legacy deployment will be removed in our example scenario to prove connectivity to the upgraded deployment post hostname migration.
  • Prior to hostname migration a CuRL test was conducted to the pre-existing deployment (OriginalDeployment). At the time of this test the upgraded deployment did not exist. A CuRL header rewrite is utilized to successfully test connectivity to the hostname (supermariotest.akash.network).
1
curl --header 'Host: supermariotest.akash.network' 2gkpg7qhghetb7tu1ku9aspbl8.wwwp1.h18.akashian.io
Copied!
  • Post deployment of the upgraded instance and hostname migration - the pre-existing deployment is removed, connectivity to the hostname via CuRL is conducted anew, and the successful HTML response validates the hostname was migrated properly.
1
curl -v --header 'Host: supermariotest.akash.network' t3r1sn9c5991beqe90hfu6facg.wwwp1.h18.akashian.io
Copied!

Requirements and Limitations of Migrate Hostname

DNS CNAME Update

  • When planning a hostname migration ensure that proper public DNS record updates are planned and executed to limit interruption in services.
  • In the example scenario utilized and to highlight necessary public DNS record adjustments:
    • The organization owning the akash.network DNS record would have a DNS canonical name (CNAME) record for supermariotest.akash.network pointing to the Akash deployment destination of 2gkpg7qhghetb7tu1ku9aspbl8.wwwp1.h18.akashian.io (OriginalDeployment)
    • The organization would need to update the CNAME record once the hostname migration was completed to the destination of t3r1sn9c5991beqe90hfu6facg.wwwp1.h18.akashian.io (UpgradedDeployment)
    • An interruption in service may be provoked as the public DNS records are published and distributed

Requirements

  • A domain name migration may be migrated to any deployment associated with the same wallet.
  • The hostname must be declared in the SDL’s accept key-value pair of the deployment to allow use of the migrate-hostnames command.

Limitations

  • A domain name used by another wallet may not be utilized. This is a pre-existing limitation - there may not be conflicts in domain names across wallets - and re-emphasizing to ensure clarity that this limitation remains.

SDL Example Utilized

Full SDL code samples used throughout this guide
1
---
2
version: "2.0"
3
services:
4
web:
5
image: pengbai/docker-supermario
6
expose:
7
- port: 8080
8
as: 80
9
to:
10
- global: true
11
http_options:
12
max_body_size: 3145728
13
read_timeout: 50000
14
send_timeout: 51000
15
next_cases: ["error", "500"]
16
next_tries: 2
17
accept:
18
- supermariotest.akash.network
19
profiles:
20
compute:
21
web:
22
resources:
23
cpu:
24
units: 0.1
25
memory:
26
size: 512Mi
27
storage:
28
size: 512Mi
29
placement:
30
westcoast:
31
signedBy:
32
anyOf:
33
- "akash1365yvmc4s7awdyj3n2sav7xfx76adc6dnmlx63"
34
pricing:
35
web:
36
denom: uakt
37
amount: 3000
38
deployment:
39
web:
40
westcoast:
41
profile: web
42
count: 1
Copied!
Last modified 2mo ago