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”
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.
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.
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.
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>
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).
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.
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
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.
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.