Upgrading

Help with upgrading the Beer Garden application from 2.x to 3.x.

Should I Upgrade?

For most users, the answer is yes. Beer Garden v2 is no longer supported and stopped receiving updates around the end of 2020. There are, however, changes in v3 that should be considered when making the upgrade decision. Specifically:

  • Users / Roles / Permissions. This has been completely rebuilt for v3 in a way that is fundamentally not compatible with what existed in v2. If you were using these features, be aware that you will need to recreate all users and roles. See the section on security for more information.

  • Publishing events to a RabbitMQ topic. This capability was fairly basic, but was not carried over to v3. If you depend on this capability you would need to come up with an alternative solution in order to move to v3.

What’s different?

A bunch of stuff! But here we’re only going to cover the most important changes. So if you only read one thing, this should be it.

If you want to see all the changes then feel free to check out the changelog :)

Goodbye Bartender & Brew-view

Brew-view and bartender are no more. The functionality that lived in each of those applications has been combined into a single "beer-garden" application.

This has some implications:

Install and Run

If you use docker you’ll no longer use the bgio/bartender and bgio/brew-view docker images. Instead, you’ll use bgio/beer-garden.

If you use the rpm the bartender and brew-view services no longer exist. Instead, you’ll start and stop the beer-garden service. This service already existed in version 2, but it was just a wrapper that invoked the other two "real" services. Now beer-garden is the "real" service.

Configuration Files

With the rpm install, the two config files (/opt/beer-garden/conf/brew-view-config.yaml and /opt/beer-garden/conf/bartender-config.yaml) have been superseded by the new consolidated /opt/beer-garden/conf/config.yaml file. The two old files will be renamed to have a .old extension. The old files aren’t needed to run Beer Garden anymore, but unfortunately you’ll need to migrate the values in them to the new file yourself. After that’s done it’s fine to delete them.

Configuration Options

The configuration names and structure have changed quite a bit between v2 and v3.

The largest change is the switch from two config files (one for brew-view, one for bartender) to just one. This is nice since it removes some annoying failure cases relating to redundant configuration (for example, if you changed db.name in one config file but not the other you’d have a bad time). With this change that’s no longer a possibility.

Unfortunately, it also means that our normal automated configuration migration won’t work in this case. So if you use configuration files to run Beer Garden you’ll need to do the migration manually. If you’re using the rpm the v3 install process will generate a new config.yaml file which will be used going forward. It’ll also rename the old config files to have a .old suffix.

For a complete guide to exactly how the configurations have changed see the tables below. Each table represents the changes in the configuration structure. Items with an "*" indicate that the change applies to everything nested under that item. Everything that’s *not* listed in the tables is unchanged.

Some examples are provided below.

Table 1. Table Brew-view Configuration Mapping
Brew-view (v2) Beer Garden (v3) Comments

amq.*

mq.*

application.allow_unsafe_output

ui.execute_javascript

These two items have been combined

application.allow_unsafe_templates

application.icon_default

ui.icon_default

application.name

ui.name

backend.*

This section has been removed

cors_enabled

ui.cors_enabled

debug_mode

ui.debug_mode

event.*

This section has been removed

log.file

This item has been removed

log.level

log.fallback_level

metrics.*

metrics.prometheus.*

plugin_logging.config_file

plugin.local.logging.config_file plugin.remote.logging.config_file

Local and remote plugins now have separate configurations

plugin_logging.level

plugin.local.logging.fallback_level plugin.remote.logging.fallback_level

Local and remote plugins now have separate configurations

scheduler.auth.*

This section has been removed

shutdown_timeout

This item has been removed

web.*

entry.http.*

web.public_fqdn

This item has been removed
Table 2. Table Bartender Configuration Mapping
Bartender (v2) Beer Garden (v3) Comments

amq.*

mq.*

db.ttl.event

This item has been removed

log.file

This item has been removed

log.level

log.fallback_level

plugin.local.log_directory

This item has been removed

publish_hostname

plugin.mq.host

This one is super important

thrift.*

This section has been removed

web.*

This section has been removed

Examples

Config file

Both config files must be combined into a single, new file.

bartender-config.yaml
db:
  connection:
    host: localhost
    password: null
    port: 27017
    username: null
  name: beer_garden
  ttl:
    action: -1
    event: 15
    info: 15
publish_hostname: localhost
brew-view-config.yaml
db:
  connection:
    host: localhost
    password: null
    port: 27017
    username: null
  name: beer_garden

BECOMES

config.yaml
db:
  connection:
    host: localhost
    password: null
    port: 27017
    username: null
  name: beer_garden
  ttl:
    action: -1
    info: 15
plugin:
  mq:
    host: localhost
Environment Variables

Environment variables need their names changed according to the mapping.

Old

New

Rule

BG_PUBLISH_HOSTNAME

BG_PLUGIN_MQ_HOST

publish_hostname → plugin.mq.host

BG_WEB_PORT

BG_ENTRY_HTTP_PORT

web.* → entry.http.*

BG_DB_NAME

BG_DB_NAME

Unchanged

User Interface

The user interface has been split out from the rest of the Beer Garden application. In v2 brew-view did double duty: it served the static resources for the frontend as well as the REST endpoints for the application. In v3 the Beer Garden application only does the latter.

To run the frontend you’ll need to either use the docker image (bgio/ui) or install a server capable of serving static files and proxying the REST API. If you’re using the rpm we recommend you install the "nginx" rpm before installing or upgrading the beer-garden rpm. If you install in that order we’ll create a symlink in nginx’s configuration directory to a config file that will serve everything for you.

Local Plugins

Local plugins got a bit of a makeover in version 3.

Logging

In version 2 local plugins traditionally logged to STDOUT. Bartender would capture that output and would write it to a "logging" file.

In version 3 that’s no longer the case. Plugins (all plugins, not just local ones) now ask the Beer Garden server for a logging configuration when they’re created. This allows them to log directly to a file themselves, which simplifies things.

However, the logging configuration doesn’t kick in until the Plugin is able to make a successful connection to Beer Garden. What if something bad occurs before that happens? To help troubleshoot that case there’s a new option you can set in a Plugin’s beer.conf: CAPTURE_STREAMS. Setting CAPTURE_STREAMS=True in beer.conf will cause two files, plugin.stdout and plugin.stderr, to be created in the plugin directory. These will contain whatever the plugin process generates.

beer.conf

The main change is that most of the items in beer.conf that were previously required are now optional. The only item still required is PLUGIN_ENTRY, all others can be omitted.

Note that you’ll still need to provide required information somehow when running a plugin. The typical way to do this is to pass things like system name to the Plugin as kwargs. Doing things this way will allow you to run a plugin as either local or remote with minimal duplication.

How Do I Upgrade?

That depends on how you run Beer Garden:

rpm

  • If you don’t already have nginx installed, install it first (yum install nginx)

  • Upgrade with yum upgrade beer-garden

  • Migrate your config settings from bartender-config.yaml and brew-view-config.yaml to the new consolidated config.yaml

  • Start both Beer Garden and nginx: systemctl start nginx beer-garden

Docker

  • You’ll need to use the bgio/beer-garden and bgio/ui images

  • You don’t need the bgio/bartender or bgio/brew-view images anymore

  • Any configuration you were applying (such as environment variables or command line arguments) to the bartender and brew-view containers needs to be applied to the beer-garden container instead. HOWEVER, the names of the configuration items have changed, so please consult the configuration guide when migrating.

Potential Pitfalls

Just some other things to be aware of:

Local Plugins

Local plugins have changed a bit, so be on the lookout for these:

  • If a Plugin you’re expecting to see just doesn’t show up in the Systems list, try adding CAPTURE_STREAMS=True to its beer.conf and looking at the plugin.stdout and plugin.stderr files that are generated in the plugin directory.

  • If a Plugin isn’t logging like you think it should, make sure that you aren’t configuring logging in your Plugin’s main() method. Plugins now get their logging configuration from Beer Garden during initialization. However, if you configure logging yourself the Plugin will respect that configuration and will NOT overwrite it. This is most likely not what you want. If you’d like to change the level the Plugin logs at, a better way to do that is to add LOG_LEVEL="DEBUG" to the beer.conf, or pass log_level="DEBUG" as a kwarg when creating the Plugin.

  • The version of Python used to run Beer Garden has been bumped from 3.6 to 3.7. If you’re using local plugins and have any additional packages (a vendor directory) then you may run into problems if any of those vendored packages have been built for a specific Python version. This should be fairly straightforward to fix - just make a new version with vendor dependencies installed on 3.7.