Introduction

Petabridge.Cmd is a tool provided by Petabridge to make it easy to manage remote Akka.NET systems. It can be used in production, staging, testing, and development environments to help perform common management tasks such inspecting logs, downing unreachable nodes in a cluster, and so forth.

How it Works

Petabridge.Cmd exists as two connected parts:

• The pbm client, which runs locally on an end-user work station as a stand-alone executable and
• The Petabridge.Cmd.Host component, which runs as an ActorSystem extension hosted inside your Akka.NET applications.

In order for the pbm client to be able to communicate with any part of your Akka.NET applications, it connects to one of your nodes and speaks directly to the PetabridgeCmd actor system extension running inside your Akka.NET application.

The pbm client connects directly to a single host and interacts with that host specifically. Some of the operations, such as cluster join and cluster down have the ability to affect nodes other than the Petabridge.Cmd.Host that pbm.exe is currently connected to, but that's a side-effect of how the commands are implemented, not an implementation detail of petabridge.cmd itself.

Setting this up requires installing the Petabridge.Cmd.Host NuGet package into your Akka.NET application and opening a port that can be used by pbm to contact the server. This is explained in more detail in the "Petabridge.Cmd.Host Configuration" section.

Once the pbm client is able to successfully establish a connection to a host, the client will then download the list of commands supported by the host. These are referred to as "command palettes" and you can read more about them here.

This is a key point of Petabridge.Cmd's extensibility and power: the client is automatically programmed to support only the commands that are implemented on the server. You can extend any of your Akka.NET applications with a combination of built-in command palettes and user-defined ones, and the pbm client will download the list of supported commands and expose them directly on the command line, including auto-complete and help documentation.

One Akka.NET application can have a totally different set of commands than another, and the pbm client will automatically adjust to support the commands that are available on the hosts it connects to.

Once a pbm client has downloaded the available set of commands from the server, it exposes that information to the end user and allows them to send commands to the Petabridge.Cmd.Host.

All of the pbm commands are sent over the network via Akka.IO, processed by the host, and a set of responses are streamed back to the pbm client for rendering. Once the stream terminates the client will be able to accept more input.