# Airnode Deployer Image
Use the deployer image to deploy or remove an Airnode with a cloud provider such as AWS. The simplest way is to use the pre-built packages. If you would rather build the images yourself see the README (opens new window) in the deployer package.
Quick Deploy Demos
See the Quick Deploy Demos to quickly deploy and remove a preconfigured Airnode using the deployer image.
# Configuration Files
The files config.json and secrets.env are used to configure the Airnode. The
aws.env and gcp.json files are used to define environment information the
deployer uses to connect to these cloud providers.
my-airnode
├── aws.env <- Used for AWS deployment
├── gcp.json <- Used for GCP deployment
├── config.json
└── secrets.env
2
3
4
5
# Cloud Provider Credentials
In order to deploy Airnode to a serverless cloud provider, you need to provide could provider credentials to the Airnode deployer image. The deployer image currently supports deploying to AWS and GCP. For AWS deployment, see the AWS Setup and for GCP deployment, see the GCP Setup.
# Deployer Logs
The deployer saves log files by default into the config/logs/ direcotry, but
this can be changed by passing a --logs argument to the command.
# Deployer Image Commands
All three commands are similar for AWS and GCP, with differences noted where they exist.
# deploy
The deploy command will create the Airnode with a cloud provider or update it if it already exists. Three files are needed to run the deploy command.
- config.json
- secrets.env
- aws.env (AWS only)
- gcp.json (GCP only)
See Deploying an Airnode for deployment commands specific to various operating systems and cloud providers.
Note that 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.
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.
Re-deployments
A unique deployment is defined by the value of
nodeSetting.stage. If
you deploy again, using the same nodeSetting.stage value, then you are
re-deploying or updating the previous deployment.
By default the deployer will attempt to remove the Airnode should either a
deployment or re-deployment fail. But if either fails (and
--auto-remove is false) then the
Airnode will not be removed, however it could be left in an unstable state. You
can alter the deploy command to change this behavior using the following.
--auto-remove true|false: defaults to true--no-auto-remove
Auto removal is usually recommended for development deployments. For production
deployments, consider changing the value of nodeSetting.stage to create a new
deployment and follow-up by removing the previous deployment.
Use the following example to avoid the automatic removal of the Airnode.
docker run -it --rm \
-e USER_ID=$(id -u) -e GROUP_ID=$(id -g) \
-v "$(pwd):/app/config" \
api3/airnode-deployer:0.10.1 deploy --auto-remove false
2
3
4
# list
Once one or more Airnodes were deployed using the
deploy command above, the
list command can be used to list
currently deployed Airnodes. Files for cloud provider authentication are needed
for the command to run correctly: aws.env (for AWS) and/or gcp.json (for
GCP).
By default, the deployer will attempt to list Airnode instances from all the
supported cloud providers. You can use the --cloud-providers option to select
just the cloud providers you want the deployer to list from.
# info
You can retrieve more information about the deployment with the
info command. Use the deployment ID
from the list command above to request information
about a specific deployment. The retrieved information include deployment's
Airnode address, stage, Airnode version and the update history. Files for cloud
provider authentication are needed for the command to run correctly: aws.env
(for AWS) or gcp.json (for GCP).
# rollback
In case you want to revert to one of the previous versions of your deployment, you can do so with the rollback command. You need to provide the deployment ID from the list command above to specify what deployment you want to revert. You also need to provide the deployment version ID from the info command above to specify the deployment version to which you want to revert. The rollback command will then fetch your configuration files of the specified version and deploy a new version with the same configuration. You can check this with the info command above.
# fetch-files
During the Airnode deployment, your config.json and secrets.env are uploaded
to the cloud provider of your choosing. You can use the
fetch-files command to
retrieve them. You need to provide the deployment ID from the
list command above to specify the desired
deployment. By default, the files from the latest version of this deployment are
fetched. Alternatively, you can additionally provide a deployment version ID
from the info command above to specify the desired
deployment version. By default, the archive with the files is stored in the
config directory within the Docker container that is, in the example
below, mapped to your current working directory. You can change the output
directory by providing an --output-dir option specifying a different directory
instead. Don't forget to add a mapping for the new output directory so you'll be
able to access the files. Files for cloud provider authentication are needed for
the command to run correctly: aws.env (for AWS) or gcp.json (for GCP).
# remove
A deployed Airnode can be removed via the
remove command. To remove
Airnode, use the deployment ID from the list command
above. Airnode's update history, that can be seen by the
info command, will be removed as well. Files for
cloud provider authentication are needed for the command to run correctly:
aws.env (for AWS) or gcp.json (for GCP). This is the recommended way to
remove a deployment, but there are alternatives as described below.
# remove-with-receipt
When an Airnode was deployed using the deploy command, a receipt.json file
was created. This file is used to remove the Airnode. The
remove-with-receipt
command is identical for AWS and GCP. Files for cloud provider authentication
are needed for the command to run correctly: aws.env (for AWS) or gcp.json
(for GCP).
# Manual Removal
Optionally you can remove an Airnode manually though it is highly recommended
that you do so using the deployer image's remove-with-receipt or remove
commands. When removing manually, you will need the Airnode's deployment ID,
deploymentId (e.g., awsef86dfad) and the Airnode stage name (e.g.,
production). They can be found in the
receipt.json file generated
when deploying the Airnode. These are included in the element name of AWS and
GCP deployed features. Airnode has a presence in several areas of both AWS and
GCP as listed below.
Remember
Only delete elements of a feature with the deploymentId address and stage
name contained in the element's name. There can be more than one Airnode.
Example: (airnode-awsef86dfad-production-run), where awsef86dfad is the
deploymentId and production is the stage name.
Learn more about AWS or GCP resources that Airnode uses in the Cloud Resources doc.