This guide demonstrates the deployment of an Airnode followed by an off-chain HTTP Gateway request. Configuration files are provided with only minor changes to be made. The latest release of the Airnode deployer image will be used to deploy the off-chain component of Airnode (a.k.a., the node) to GCP.
This Airnode contains a single API operation (GET /simple/price) from CoinGecko which returns the current value of a coin. This guide does not detail the overall configuration of an Airnode, it is just a quick start guide then lends itself to understanding an Airnode deployment.
Please note that this tutorial does not involve the blockchain nor an RRP (request-response protocol) call from a smart contract. If you wish to make an RRP call, please see the guides Making an RRP Request and Calling an Airnode.
An Airnode deployment on GCP uses the Docker deployer image which requires three files as input: config.json, secrets.env, and gcp.json. The config.json and secrets.env files have been created and only require a few minor changes to make the deployment of the Airnode successful. The changes are needed to supply a GCP project ID, a chain provider url, and a mnemonic.
First create a GCP project (or use an existing GCP project) where the Airnode will be deployed. Once the project is created, add the project ID to the secrets.env file.
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.
In order for Airnode to deploy successfully, you need to enable the App Engine Admin API specifically for the project. After enabling it, wait a few minutes before deploying the Airnode for this change to take effect.
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-start-gcp project directory. Rename it gcp.json.
This file requires no changes on your part. It has been created with just one API endpoint and configured to listen to requests on the Sepolia test network, though this tutorial will not make any such requests. There are a few variables this file will interpolate from secrets.env.
There are three values config.json interpolates from secrets.env. Add values for each of these fields.
CHAIN_PROVIDER_URL: A blockchain provider url (including its API key) from a provider such as Infura. Use a url for the Sepolia test network. If you need help creating one see the guide Create an Infura key.
AIRNODE_WALLET_MNEMONIC: Provide the seed phrase (mnemonic) to a new digital wallet. The wallet does not need to be funded. Use the Admin CLI command generate-airnode-mnemonic to create one.
npx @api3/airnode-admin generate-airnode-mnemonic
PROJECT_ID: Project ID of your GCP project. During step #3 above you should have added the project ID to the secrets.env file.
Make sure Docker is running and then execute the deployer image from the root of the quick-start-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 Airnode. 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 these variables.
:: For Windows, use CMD (and not PowerShell).docker run -it --rm ^ -v "%cd%:/app/config" ^ api3/airnode-deployer:latest deploy
1 2 3 4 5
Make note of the HTTP gateway URL in your output shown below as it will be different. You will need it to test the Airnode.
✔ Deployed Airnode 0x6A6cF2d0094c73b7aBb22Cd6196824BCBB830125 tutorial-gcp to gcp us-east1ℹ Outputted config/receipt.json This file does not contain any sensitive information.ℹ HTTP gateway URL: https://airnode-6a6cf2d-tutorial-gcp-httpgw-4fhnl4fi.ue.gateway.dev
Looking at the config.json code snippet below shows that the HTTP gateway is configured for the Airnode. Furthermore, the endpoint for /simple/price (with an endpointId of 0x6...af6) is present in triggers.http[n]. Only those endpoints added to the http array can be tested using the HTTP gateway.
Note the JSON response field 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.
rawValue: The API's response to Airnode. Presented by the HTTP gateway as a convenience. This is never sent to a requester on-chain.
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.
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.
When you are done with this guide you can remove the deployed Airnode. The following command uses the receipt.json file that was created when the Airnode was deployed.
docker run -it --rm \ -v "$(pwd):/app/config" \ api3/airnode-deployer:latest remove-with-receipt
1 2 3
:: For Windows, use CMD (and not PowerShell)docker run -it --rm ^ -v "%cd%:/app/config" ^ api3/airnode-deployer:latest remove-with-receipt
1 2 3 4 5
After removing an Airnode it may be necessary to wait several minutes before deploying or redeploying Airnode again to the same GCP project. GCP takes several minutes to complete its behind the scenes clean-up of configured resources.
You have deployed an Airnode on GCP with its HTTP gateway enabled. The Airnode, upon deployment, started contacting the AirnodeRrpV0 contract on the Sepolia test network to gather any requests made by requesters to this Airnode. However this guide did not address making a request on-chain as its purpose was to quickly deploy a functional Airnode. See the guides Making an RRP Request and Calling an Airnode to learn how your smart contract can make an RRP call to an Airnode.
Finally the API integration was tested using the Airnode's off-chain HTTP gateway. You made a CURL request (using HTTP) to the HTTP gateway. Airnode queried the API provider and sent back a response. All of this was performed without accessing the blockchain.
Learn more about GCP resources that Airnode uses in the Cloud Resources doc.