grid3_client_ts

Github repo: grid3_client_ts

grid3_client is a client used for deploying workloads (VMs, ZDBs, k8s, etc.) on grid3.

Prerequisites

• node 16.13.1 or higher
• npm 8.2.0 or higher
• may need to install libtool apt-get install libtool

Installation

Warning: For Qanet, Please use @2.0.0 version

Warning: For Testnet, Please use @2.0.0 version

Warning: For Mainnet, Please use @1.5.0 version

External package

npm install grid3_client

or

yarn add grid3_client

Local usage

• Clone the repository

git clone https://github.com/threefoldtech/grid3_client_ts.git

• Install it

npm install

or

yarn install

Getting started

Client configuration

• Network environment: should select dev environment, qa, test or main.

• Mnemonic: 12 words for your account. create one

• Store secret: it's any word that will be used for encrypting/decrypting the keys on threefold key-value store.

• project name: it's a name to isolate the deployments into a namespace.

  Note: only network can't be isolated, all project can see the same network.

Create client instance

• Here's a simple example of creating a client instance with the default configurations.

• or you can check more advanced configuration here.

  async function getClient(): Promise<GridClient> {
  const gridClient = new GridClient({
      network: config.network,
      mnemonic: config.mnemonic,
  });
  await gridClient.connect();
  
  return gridClient;
  }

• You can set your configurations through environment variables or JSON config file as seen here.

• With clientOptions being added, all urls are now configured. So, you can easily get the proxy URL for the used network simply by:

  const proxyURL = gridClient.clientOptions.proxyURL

for more details, check client options

Important Note: grid client should be disconnected after finishing its usage.

gridClient.disconnect();

Using the client

This section assumes that you are using the client configuration from client_loader.ts

• After creating a client instance you can call it in any of your scripts using getClient().

  const grid3 = getClient();

• And then you can use this client instance with any of the client modules.

• For example to deploy a VM you will need to use the machines module with the client and it can be used as follows. you can find the full example script here.

  • To deploy a VM

    await grid3.machines.deploy(vms);

  • To delete a VM

    await grid3.machines.delete({ name: vms.name });

• More example scripts can be found here

Running the scripts

• Before Running the scripts make sure you have a tsconfig.json file. here is an example file.

  {
      "compilerOptions": {
          "noImplicitAny": false,
          "module": "commonjs",
          "target": "esnext",
          "lib": [
              "ESNext",
              "DOM"
          ],
          "types": [
              "node",
              "jest"
          ],
          "declaration": true,
          "declarationMap": true,
          "outDir": "./dist/node",
          "esModuleInterop": true,
          "emitDecoratorMetadata": true,
          "experimentalDecorators": true,
          "allowJs": true,
          "baseUrl": "."
      },
      "include": [
          "src/**/*"
      ]
  }

• After following the previous examples to create a client instance and using it in a script, you can then execute this script using ts-node.

  npx ts-node --project tsconfig-node.json filename.ts

  or

  yarn run ts-node --project tsconfig-node.json filename.ts

Usage examples

• Scripts
• HTTP Server
• RMB Server

API Docs

https://threefoldtech.github.io/grid3_client_ts/api/

Testing

• Test setup
• How to run tests

Related Documentations

• Configure the editor/IDE

• Contribution Guide

• Grid Client documentation

• Pipelines documentation

• Release process