Agents
The agent serves as the component linking your private infrastructure to Hoop. It functions as a proxy, connecting to a central gateway and exposing services within its network scope.
You can install the agent on any Unix system. It requires an authentication key exposed as an environment variable: HOOP_KEY.
For deployment, the agent operates in two modes: as a standalone process (standard) or alongside any running application (embedded). Each mode has unique advantages.
Standard Mode
The standard mode runs the agent as a standalone process. This mode is recommended when you need to connect to multiple types of resources with a single agent or desire a more stable connection for your workloads. Consider using the standard mode if you want to connect to:
- Databases
- Port-Forward Internal Services
- Container Platforms (kubectl, aws ecs, etc)
- Act as a Jump Host
- To create and run an agent in standard mode, use the ‘hoop admin’ command line by issuing the command below:
Connection Auto Configuration
Use the hoop run subcommand to automatically configure and publish a connection. It’s a suitable option when you need to connect a single resource. For instance:
Database Connection
This example publishes a pgdemo connection resource.
Command Line & Applications
This example publishes a railsc connection resource.
Embedded Mode
The embedded mode is advised for situations where the context of a runtime application is needed. The agent can run as a background process in the operating system or as a separate process close to the underlying main application. This mode is recommended if you want to:
- Execute ad-hoc tasks (rake tasks, django-admin, elixir mix tasks)
- Interactive console access
- Access REPL language environments (rails console, elixir, clojure, etc)
- Connect a single resource like a database
To create and run an agent in the embedded mode, obtain the key in the webapp when creating a connection and issue the command below:
The command below demonstrates how to run the agent alongside your main application. The command that is set to run in the foreground is denoted after the -- delimiter, while the agent operates in the background.
Authentication Keys
To connect to a hoop gateway, the agent requires an authentication key. Each key can be revoked at any time, which allows for the disconnection of every resource associated with it.
- scheme - the protocol scheme to connect http(s) or grpc(s)
- name - the name of the authentication key
- auth-key - the authentication key
- host - the hostname or ip address of the gateway
- port - the port to connect to
- mode - the execution mode: standard or embedded
We recommend naming these resources with the name of your environment or the context of the network, examples:
aws-prod,aws-us-east-1,production.
Key Management
Agent Keys
Use the hoop command line to manage agent keys, these ones are only used with hoop start agent command.
Revoke a Key
List Keys
Organization Keys
Organization key is used to connect multiple agents with the same key. It only works with hoop run command and only one key is available by organization.