Documentation
A newer release of the API3 Technical documentation is available.
📂 API Providers > Tutorials > Quick Deploy GCP

# Instructions

Table of Contents

This demo is a simple Airnode deployment, using a hands-on approach, to better understand the overall deployment process of the Airnode deployer image which deploys the off-chain component of Airnode (a.k.a., the node) to GCP. It uses an API endpoint (GET /simple/price) from CoinGecko (opens new window) which returns the current value of a coin. This demo does not detail the overall configuration of an Airnode, it is just a quick start.

An Airnode cloud provider deployment uses a Docker image (called deployer image) which in turn requires three files as input.

For the purpose of this demo these files have been created and only require a few minor changes on your part to make the deployment of the demo Airnode successful. These changes are needed to supply a GCP project ID, chain provider url, and a mnemonic.

# Launch Docker Desktop

Launch the Docker Desktop app. You can install it from the Docker docs (opens new window) website.

# Project Folder

A project folder is needed for this demo. You can create it manually or download a zip file ready to go.

# Configuration

Prepare the configuration files, setup a GCP project and obtain credentials. By default, the Airnode deployer image looks for config.json and secrets.env in /config and writes receipt.json to the /output folder.

# config.json

This file requires no changes on your part. It has been created with just one API endpoint. It will instruct the Airnode to attach to the Rinkeby test network. There are three variables this file will extract (interpolation) from secrets.env.

# secrets.env

Add values for each of the these fields.

  • CHAIN_PROVIDER_URL: A chain provider url from a provider such as Infura (opens new window). Make sure the provider url you use is for the Rinkeby test network. Using another chain provider other than Infura is acceptable.

    • Sign-up or login to Infura.
    • Create a new project, select the Settings tab in the project.
    • Copy the URL (https) for Rinkeby under the Endpoints pick list.

  • AIRNODE_WALLET_MNEMONIC: Provide the seed phrase (mnemonic) to a digital wallet. For the purpose of this demo it does not need eth in it for the Rinkeby test network. If you don't have one use the Admin CLI command generate-mnemonic to create one or another method you prefer.

  • PROJECT_ID: Project ID of your GCP project. Create a GCP project (opens new window) under which will the Airnode be deployed and copy the project ID.

  • HTTP_GATEWAY_API_KEY: Make up an apiKey to authenticate calls to the HTTP Gateway. Used to test your Airnode with CURL later. The expected length is 30 - 128 characters.

# GCP Project Setup & Credentials

  1. First create a GCP project (opens new window) where the Airnode will be deployed. Once the project is created, add the project ID to the secrets.env file.

  2. Make sure you have billing enabled for your project. To do so, you will need to pair the project with your bank card, although no charges will be incurred since the resource usage fits well within the free tier limit.

  3. In order for Airnode to deploy successfully, you need to enable the App Engine Admin API (opens new window) specifically for the project. After enabling it, wait a few minutes before deploying the Airnode for this change to take effect.

  4. Enable the API Gateway (opens new window). Select the proper project on the GCP Gateway page, then select the Enable button. If the Manage button is present for the project, the GCP Gateway is already enabled.

  5. Create a new service account from the Service accounts (opens new window) menu. Grant this account access to the project by adding the role Owner during creation.

  6. Once the new service account is created, click on it to bring up its management page. Select the KEYS tab and add a new access key of type JSON for this account. Download the key file and place in the root of the /quick-deploy-gcp directory. Rename it gcp.json.

# Deploy

Make sure Docker is running and then execute the deployer image from the root of the quick-deploy-gcp folder. A receipt.json file will be created upon completion. It contains some deployment information and is used to remove the Airnode.

Warning about simultaneous deployments

Avoid running multiple deployments simultaneously as doing so might result in a broken deployment. If this occurs, the standard removal approach may not succeed and Manual Removal may be required.

Run the following command to deploy the demo Airnode. Note that the version of api3/airnode-deployer matches the nodeVersion in the config.json file. Normally (for Linux/Mac/WSL2) the deployer image deploy command is run by the user root. This may cause permission issues when the receipt.json file is generated. Optionally you can specify the UID (user identifier) and GID (group identifier) that the deployer image should use. Do so by setting the environment variables USER_ID and GROUP_ID, otherwise omit the line containing the variables.

# Test the Airnode

After a successful deployment the Airnode can be tested directly using the HTTP Gateways without accessing the blockchain. You provide endpoint parameters to get a response from an integrated API.

# HTTP Gateway

Looking at the config.json code snippet below shows the HTTP gateway was activated for the Airnode. Furthermore the endpoint for /simple/price (with an endpointId of 0x6...af6) has been added to triggers.http[n]. Only those endpoints added to the http array can be tested.

"nodeSettings": {
  ...
  "httpGateway": {
    "enabled": true, // The gateway is activated for this Airnode
    "apiKey": "${HTTP_GATEWAY_API_KEY}", // Gateway apiKey
    "maxConcurrency": 20
  },
  ...
},
"triggers": {
  "rrp": [
    {
      "endpointId": "0x6db9e3e3d073ad12b66d28dd85bcf49f58577270b1cc2d48a43c7025f5c27af6",
      "oisTitle": "CoinGecko Basic Request",
      "endpointName": "coinMarketData",
    }
  ],
  "http": [
    {
      "endpointId": "0x6db9e3e3d073ad12b66d28dd85bcf49f58577270b1cc2d48a43c7025f5c27af6",
      "oisTitle": "CoinGecko Basic Request",
      "endpointName": "coinMarketData",
    }
  ],
  ...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Execute Endpoint

Use CURL to execute the Airnode and get the results from the CoinGecko endpoint /simple/price bypassing the Rinkeby test network that Airnode was deployed for. As an alternative to CURL try an app such as Insomnia (opens new window) or Postman (opens new window). Windows users can also use Windows Subsystem for Linux (opens new window) (WSL2) to run CURL for Linux.

In order to test an endpoint make a HTTP POST request with the endpointId as a path parameter, the Content-Type header set to application/json, the x-api-key header set to the key and place the endpoint parameter in the request body as a key/value pair.

  • -X: POST
  • -H: The Content-Type using the value of application/json.
  • -H: The x-api-key using the value of HTTP_GATEWAY_API_KEY from secrets.env file.
  • -d: Use request body data to pass the endpoint parameter key/value pair.

URL:

<httpGatewayUrl>/0xf466b8feec41e9e50815e0c9dca4db1ff959637e564bb13fefa99e9f9f90453c

  • <httpGatewayUrl>: The base URL to the gateway, found in the receipts.json file. Update the placeholder in the CURL example below with its value.
  • 0xf466b8feec41e9e50815e0c9dca4db1ff959637e564bb13fefa99e9f9f90453c: Passed as a path parameter, the endpointId to call, see triggers.rrp[0].endpointId in the config.json file.

# Request

# Response

{
  "encodedValue": "0x0000000000000000000000000000000000000000000000000000000000362b30",
  "rawValue": {
    "api3": {
      "usd": 3.55
    }
  },
  "values": ["3550000"]
}
1
2
3
4
5
6
7
8
9

Note the JSON response values is the API3 price multiplied by 1e6, which results from setting the _times reserved parameter to 1000000 in config.json. This manipulation is necessary in order to correctly handle floating point numbers.

  • encodedValue: This is the only field that gets sent to a requester (smart contract) on-chain. It is the encoded bytes of the values field. A requester must decode it to read the response values.
  • rawValue: The API's response to Airnode. Presented by the HTTP gateway as a convenience. This is never sent to a requester on-chain.
  • values: A array of values after they are extracted and converted from the encodedValue to the target type, in this case api3.usd from _path in reservedParameters. The HTTP gateway provides this as a convenience and never sends the decoded values to a requester on-chain.

# Remove the Airnode

When you are done with this demo you can remove it. When the Airnode was deployed a receipt.json file was created in the /output folder. This file is needed to remove an Airnode.

Post Removal

After removing an Airnode it may be necessary to wait several minutes before deploying / redeploying Airnode again to the same project. GCP takes several minutes to complete its behind the scenes clean-up of configured resources.

# Summary

You have deployed an Airnode on GCP. The Airnode, upon deployment, started contacting the AirnodeRrp contract on the Rinkeby testnet to gather any requests made by requesters to this Airnode. This tutorial did not address making a request as its purpose was simply to quickly deploy a functional Airnode.

Learn more about GCP resources that Airnode uses in the Cloud Resources doc.

Last Updated: 8/9/2022, 2:28:25 PM

← config.json →