11. Bundle Configurations
A command bundle is a set of related commands that, when installed in Gort, may be executed by users from any connected (and allowed) chat service. A bundle configuration specifies which binary to execute, and who may execute the commands (i.e., which users with which permissions).
11.1. A Minimal Bundle Configurations
A minimal bundle configuration looks like the following:
--- gort_bundle_version: 1 name: my_bundle description: "Does bundle things" version: 0.1 image: ubuntu:20.04 commands: date: executable: [ "/bin/date" ] description: "Displays the current date and time" rules: - allow
commands fields are all required. Let’s go over what these do:
gort_bundle_versionis the version of Gort’s bundle system that your bundle was built for. The current bundle version is 1, which is used through out the rest of this document.
nameis the name of your bundle, which also serves as the namespace under all of the bundle’s commands are installed. In this case the date command’s fully-qualified name is
descriptionis a short, one-line description for your bundle. This will be printed along with a list of all installed bundles when a user runs the
versionis the semver version number of your bundle. If you want to install a new version of bundle then you first need to uninstall the old one.
dockerspecifies the Docker image that contains all of the bundle’s commands. Limit: one image per bundle.
commandsare a map of zero or more commands that can be invoked in the bundle, and their associated executables. The command name, as defined here, will be the command invoked by users; it doesn’t have to match the name of the binary.
Commands are possibly the most complex component of the bundle config.
As an example let’s look at an excerpt from the config for an
... commands: find: executable: [ /usr/local/bin/ec2_find ] description: Finds an AWS EC2 instance rules: - must have ec2:view ...
Here you can see the command name, “find”, under which are nested several fields.
executablepoints to the command script or binary that’s to be run when the command is executed. Optional. If omitted, this defaults to the image’s specified ENTRYPOINT.
descriptionis a short, one-line description for the command. This is the info that will appear along with a list of commands when a user runs the
rulesis a required list of strings that define what permissions are required to run the command. In this example, the
ec2:viewpermission is required. See Permissions and Rules to learn more about rules and their construction.
Most commands require permissions to run. Permissions are specified by
in the bundle config as a list of strings at the top level. Here is
another excerpt of the
ec2 config as an example.
--- gort_bundle_version: 1 name: ec2 description: Manage EC2 instances and related services version: 0.4.0 permissions: - view - destroy - create ...
In this example, three permissions are defined. When being referenced in
a command rule a permission’s fully-qualified name must be used: e.g.,
11.1.3. Documentation fields
There are a number of fields dedicated to rendering help output via the
help command, both for the bundle and the command.
The following documentation fields can also be used at the top level of a bundle configuration:
long_descriptionis a separate section for a longer form description, which can include things like what configuration is required, how commands should be used, and more details about the underlying implementation.
authoris where the bundle author can leave their name and email address if a user needs their contact information.
homepageis a URL for the bundle, typically a GitHub repository.
The following documentation field can also be used in each command configuration:
long_descriptionis a long-form description used to explain details of a command that don’t fit into other sections like an explanation of required arguments or about the structure of the output.
11.2. Bundle Installation
Command bundles can be explicitly installed using
gort bundle install. Bundles can only be installed this way by an
adequately-privileged user (an administrator or other user with the
gort:manage_bundles permission), and are disabled by default.
See Managing Bundles for more information on how to explicitly install command bundles.
11.3. A Complete Bundle Configuration Example
Below is a complete example of a bundle configuration. In fact, it’s the
default bundle used by Gort to install the
gort bundle (minus a few
commands, cut for brevity).
--- gort_bundle_version: 1 name: gort version: 0.0.1 author: Matt Titmus <firstname.lastname@example.org> homepage: https://guide.getgort.io description: The default command bundle. long_description: |- The default command bundle, which contains the administrative commands and the permissions required to use them. Don't change or override this unless you know what you're doing. permissions: - manage_commands - manage_groups - manage_roles - manage_users docker: image: getgort/gort tag: v0.9.0 commands: bundle: description: "Perform operations on bundles" long_description: |- Allows you to perform bundle administration. Usage: gort:bundle [command] Available Commands: disable Disable a bundle by name enable Enable the specified version of the bundle info Info a bundle install Install a bundle list List all bundles installed uninstall Uninstall bundles yaml Retrieve the raw YAML for a bundle. Flags: -h, --help help for bundle executable: [ "/bin/gort", "bundle" ] rules: - must have gort:manage_commands version: description: "Displays version and build information" long_description: |- Displays version and build information. Usage: gort:version [flags] Flags: -h, --help help for version -s, --short Print only the version number executable: [ "/bin/gort", "version" ] rules: - allow help: description: "Provides information about a command" long_description: |- Provides information about a command. If no command is specified, this will list all commands installed in Gort. Usage: gort:help [flags] [command] executable: [ "/bin/gort", "hidden", "commands" ] rules: - allow