Agent
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:
export HOOP_KEY=$(hoop admin create agent dev)
hoop start agent
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:
export HOOP_KEY=$(hoop admin get orgkeys)
hoop run --name pgdemo --postgres 'postgres://user:pwd@127.0.0.1/test'
Database Connection
This example publishes a pgdemo
connection resource.
export HOOP_KEY=$(hoop admin get orgkeys)
hoop run --name pgdemo --postgres 'postgres://<user>:<pwd>@<host>:<port>/<db>'
Command Line & Applications
This example publishes a railsc
connection resource.
export HOOP_KEY=$(hoop admin get orgkeys)
hoop run --name railsc --command 'rails console'
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:
hoop run -- YOUR_COMMAND --YOUR_FLAGS
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.
hoop run --command 'rails console' -- \
bundle exec rails s -p 3000 -b '0.0.0.0'
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>://<name>:<auth-key>@<host>:<port>?mode=<agent-mode>
- 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
grpcs://dev:xagt-mzv7CRgUs23TgHpk0XNmll0TO37qfwM0D3JGQpwGPa8@use.hoop.dev:8443?mode=standard
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.
hoop admin create agent homolog
Revoke a Key
hoop admin delete agent homolog
List Keys
hoop admin get agents
UID NAME MODE VERSION HOSTNAME PLATFORM STATUS
22ab1d2f-... default standard unknown 5601881aa15e linux/arm64 ONLINE
7850eb2d-... homolog standard - - - -
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.
Get the Key
hoop admin get orgkeys
Revoke the Key
hoop admin delete orgkeys
Create the Key
hoop admin create orgkeys