Katello package actions in an Agent-less world

What’s happening

Katello has a number of APIs which perform actions against content hosts using the katello agent exclusively. Knowing that the agent will be removed in just a few release (3-5) after the REX equivalent is in production it’s time to consider the best path forward for our existing agent-focused APIs and hammer commands that use them.

Katello APIs affected

  • /api/v2/hosts/:host_id/packages/{install,upgrade,upgrade_all,remove}
  • /api/v2/hosts/:host_id/errata/apply
  • /api/v2/hosts/bulk/{install_content, update_content, remove_content}

Hammer commands affected

  • hammer host package {install,remove,upgrade,upgrade-all}
  • hammer host package-group {install,remove}
  • hammer host errata apply
  • hammer host-collection erratum install
  • hammer host-collection package {install,remove,update}
  • hammer host-collection package-group {install,remove,update}


There may be other options but these are some of the obvious ones the team discussed.

Option 1: Formally deprecate the existing agent-specific APIs and Hammer commands

This implies that users will fully migrate away from the above APIs/commands and choose their preferred REX method to update hosts content.


  • a lot less code to maintain and update to support both REX and Agent in short and long term


  • Potential user pain in migrating (ie “How do I translate the old command into a hammer job-invocation?”). Perhaps an opportunity to rename the job-invocation command or improve the UX around using job-invocations from the CLI.

Option 2: Deprecate APIs, Preserve Hammer commands and proxy to REX

Simplify our API by removing the server side of the existing hammer commands and re-implement them to use REX.


  • Commands remain consistent from today through to a future when the agent is removed and REX is the only option


  • Multiple interfaces to perform REX actions.
  • Supporting n REX mechanisms implies updating a number of APIs and hammer commands into the future
  • sprawl of package / errata related commands in general

Option 3: Keep existing APIs and Hammer commands, re-implement Katello APIs to use REX


  • Virtually no change as far as the user is concerned


  • Basically the same as Option 2

Let us know what you think about these options not limited to: technical hurdles, how the user experience might be affected, long term vs short term considerations, and feel free to share tweaks and entirely new options not listed! Thanks for taking the time to read and provide feedback.

Redmine Tracker

Tracker has been created with respect to Option 1 and the actions mentioned in this thread: Tracker #32155: Deprecate agent-based APIs and Hammer commands - Katello - Foreman


This would be my vote.

I think this is a great point. As there are likely more actions than just package related actions that might could do with an easy way to either reference them or have a “dedicated” command to them. Seeing if we can solve this more generally rather than maintain just package work around would have broad benefits worth investigating.


I’d prefer option 1, if we try to keep backwards compatibility, longer term it would only cause confusion. E.g. why I can’t schedule the action for future execution if it’s rex job? I’d prefer to have one way and focus the effort on improving it.

Today the command looks like this

hammer job-invocation create --feature=katello_package_install --search-query='host.example.com' --inputs 'package=vim'

which currently seems to be broken (cc @aruzicka, @ofedoren), the command complains about --search-query being blank

one needs to use the template id directly by

hammer job-invocation create --job-template-id 150 --search-query='host.example.com' --inputs 'package=vim'
1 Like

Judging from the PR[1] which introduced the option to use a feature when triggering a job through the api I’d say it was never meant to be user facing and therefore not used the way you and hammer are trying to use it.

If this is something we want to have, feel free to file an issue.

[1] - https://github.com/theforeman/foreman_remote_execution/pull/316


One thing that might be nice if we go with option 1) is to keep the hammer commands around for a while (2 releases or so) and have them spit out their rex equivalents, something like:

# hamer package install --host=host.example.com --packages=mypackage

Error, this command has been replaced with Remote Execution, this command should achieve the same result:

hammer job-invocation create --feature=katello_package_install --search-query='host.example.com' --inputs 'package=mypackage'


Thanks for all the feedback! It seems like Option 1 is getting full support and that’s the direction my team was favoring as well.

I’ve created a tracker in redmine to track the suggestions and actions identified here: Tracker #32155: Deprecate agent-based APIs and Hammer commands - Katello - Foreman

My goal is to get these deprecations in place for 4.1

1 Like