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.

Using flags

bee-docker -i bee1 -k SUAIQUXSPI4SOQVGTB5GV5FWXZ7D4M5WC5FCH2CTDFH2IZT5QZUQZDUT54 -h localhost:3333

Using env vars

export BEE_ID=bee1
export BEE_KEY=SUAIQUXSPI4SOQVGTB5GV5FWXZ7D4M5WC5FCH2CTDFH2IZT5QZUQZDUT54
export HIVE_URI=localhost:3333
bee-docker

Using init file

bee-docker -c bee1.yaml

The init file is the easiest option if the beectl bind key command with --auto-generate flag was used.

The init file option or setting environment variables is the best option when using containers or deployments on Kubernetes, because it allows you to separate the connection data from the command process.

When 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.

Hive logs

INFO[0319] Connected: Bee (bee1:UDZZ57E7NQFXSJ72...) to Hub (AAKGNPVATHBPCCHU...)  

Bee logs

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:UDZZ57E7NQFXSJ72M56PWEUZA6H4S6FZTED4GFDNJLPGJ6FTTMF6YDCW

The hive logs the disconnection event when the bee is disconnected

Hive logs

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.

Bee logs

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.

bee1.json

{
  "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.json

The --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 bee1

Bee 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 bee1

If 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 bee1

Now 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 bee1

Bee 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 --sync