Running bee agents
How to connect and configure a bee agent
Before connecting a bee agent to a hive server, it must be registered following the steps shown in the section that explains how to register bees.
Without the registration step the bee is not allowed to connect because it cannot authenticate with the server.
Connecting bees
Each type of bee agent has a different executable. In this section, a Docker client bee is being used, so the executable is bee-docker. For bees of type http it would be bee-http. See the bee types section to explore how to configure and start each bee type.
The bee has to provide three parameters in order to connect to the server: Hive location, bee ID and the seed key. These parameters can be passed via command line parameters (flags) when running the bee process, as environment variables, or using a configuration file.
bee-docker -i bee1 -k SUAIQUXSPI4SOQVGTB5GV5FWXZ7D4M5WC5FCH2CTDFH2IZT5QZUQZDUT54 -h localhost:3333export BEE_ID=bee1
export BEE_KEY=SUAIQUXSPI4SOQVGTB5GV5FWXZ7D4M5WC5FCH2CTDFH2IZT5QZUQZDUT54
export HIVE_URI=localhost:3333
bee-dockerbee-docker -c bee1.yamlWhen a bee is connected it is shown in the hive output logs. It logs the bee ID with its public key and which is the hub where the bee is connected.
INFO[0319] Connected: Bee (bee1:UDZZ57E7NQFXSJ72...) to Hub (AAKGNPVATHBPCCHU...) INFO[0000] -(//·) Running Docker bee
INFO[0000] Using config file: ./bee1.yaml
INFO[0000] Connected to Hive: nats://127.0.0.1:4222. Hub:default. Bee:bee1. PubKey:UDZZ57E7NQFXSJ72M56PWEUZA6H4S6FZTED4GFDNJLPGJ6FTTMF6YDCWThe hive logs the disconnection event when the bee is disconnected
INFO[0359] Disconnected: Bee (bee1:UDZZ57E7NQFXSJ72...) from Hub (AAKGNPVATHBPCCHU...)Reconnecting behavior
An important part of any bee to hive connection is what to do when a connection drops off and the agent needs to reconnect. BeeOS has built-in reconnection support that can be configured to behave in ways that suit the application.
When a bee agent is starting and connecting for the first time, if it is not able to connect to hive it will try to reconnect until it can do it. Once connected to the hive, if the connection closes for whatever reason the bee will attempt to reconnect to the hive indefinitely until the connection is re-stablished again.
INFO[0000] -(//·) Running Docker bee.
INFO[0000] Using config file: ./bee1.yaml
WARN[0002] Hive not reachable. Trying to connect... Configuring bees
Once the bee is connected, it must be given instructions on how to proceed. This is done through configuration. A JSON file with the necessary settings must be created and uploaded to the hive server. Next, the recently uploaded configuration must be synchronized with the bee so that it can receive the settings to be carried out.
For this example we have used the Docker client bee (bee-docker exec). All bees have the same JSON schema, except for some section that is specific to each type of bee. Below is an example of JSON for Docker's bee client. The contents of the settings section is specific to this type of bee (image, volumes, ports, etc)
The goal of a Docker client bee (bee-docker) is to run containers on the host where the bee is installed (in the same way as a command line Docker client). The image to pull, registry, volumes, port mappings and other advanced options are available to be set at settings section.
In that case we want to run a "nginx:1.18-alpline" image from the public Docker registry mapping the container port 80 to the host 8080.
{
"channels": [
{
"metadata": {
"id": "web1",
"type": "default",
"name": "Web Server",
"schemaVersion": 1
},
"settings": {
"image": {
"repository": "nginx",
"tag": "1.18-alpine",
"registry": ""
},
"volumes": [],
"ports": [
{
"hostPort": "8080",
"containerPort": "80"
}
]
}
}
]
}A bee1.json file is created with the contents shown above. Then the following beectl command is used to send the configuration to the hive server.
beectl set config -b bee1 -f bee1.jsonThe --bee (-b) flag specifies the bee ID and the --file (-f) is the path of the JSON file containing the configuration.
When a new configuration is uploaded the config version number is increased
beectl get bee -b bee1Bee information
ID bee1
Name MyBee
Description (No available)
Hub default
Public keys UDZZ57E7NQFXSJ72M56PWEUZA6H4S6FZTED4GFDNJLPGJ6FTTMF6YDCW
Configuration version 1
Resources (No resources uploaded)
State Disconnected
Last synchronization (No sync)
Swarm No
Schemas (No available) The current configuration can be seen or downloaded using the get config command. It prints at the console the requested configuration
beectl get config -b bee1If the --file (-f) flag is used it is downloaded to the specified file instead of being printed at the console.
Synchronizing configurations
The configured bees has its configuration stored in the hive internal database. To send the configuration to the bees, a synchronization should be done. The synchronization is an important concept because sometimes your bee configurations need to be synchronized at the same time, not when you are uploading the config file.
The following command performs a synchronization for a given bee
beectl sync bee -b bee1Now the synchronization is performed. The corresponding bee will receive its configuration as soon as it is connected if is not connected at the moment of executing the sync command. We can see the synchronization state using the get command
beectl get bee -b bee1Bee information
ID bee1
Name MyBee
Description (No available)
Hub default
Public keys UDZZ57E7NQFXSJ72M56PWEUZA6H4S6FZTED4GFDNJLPGJ6FTTMF6YDCW
Configuration version 1
Resources (No resources uploaded)
State Disconnected
Last synchronization 27 Jan 23 19:42 CET
Swarm No
Schemas (No available)There is the possibility to synchronize while uploading a configuration file using the --sync flag. It avoids the need to perform two steps to upload and sync a configuration file.
beectl set config -b bee1 -f bee1.json --syncLast updated