@threefold/grid_client

grid_client

Github repo: grid_client

grid_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.5.2 version

Warning: For Testnet, Please use @2.5.2 version

Warning: For Mainnet, Please use @2.5.2 version

External package

yarn add @threefold/grid_client

Local usage

• Clone the repository

git clone https://github.com/threefoldtech/tfgrid-sdk-ts.git

• Install it

yarn install

Note: If the used Python version is 3.12 or later, you need to install setuptools.

python3 -m pip install setuptools

Getting started

Client configuration

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

• Wallet connector: mnemonics (12 random words in a unique order) for your account to interact with the chain. 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.

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

Usage examples

• Scripts

API Docs

https://threefoldtech.github.io/tfgrid-sdk-ts/packages/grid_client/docs/api/index.html

Testing

• How to run tests

Related Documentations

• Contribution Guide
• Grid Client documentation