Import mechanism in (git) jobs

[u1735067]

Hello,

I have several questions / remarks about the import abilities in (git) jobs.

The documentation states that the directory must contains a __init__.py file but I found that it would work even without this file, as it seems jobs are imported independently by their file contents (https://github.com/nautobot/nautobot/blob/v1.0.3/nautobot/extras/jobs.py#L654) in ASCII order of file names[1].

This was noticed because I have multiple jobs reusing the same functions so I decided to put them in a common.py file, but I was unable to use it in say CheckDevice.py, Nautobot failing with the message Unable to locate job "git.testjobs/CheckDevice/MyTask" to run it!. After many tests I found that if I renamed CheckDevice.py to zCheckDevice.py it would work.

I also tested something like:

try:
  from common import myfunc
except ImportError:
  from .common import myfunc

without success.

So the questions are:

• is it normal the import system/resolution of imported jobs isn't working?
• is the empty __init__.py really required? From my tests, it doesn't seems to change things
• is it supported/right to have non-job source files in the jobs directory, as long as they don't inherit from the Job class?
  • if yes and the current import system is working as intended, what would be the correct way to import from another file? Prefix the common source files name with AAA_?

And a bit off-topic, when using test-only job, the log info Database changes have been reverted automatically. seems to be associated to the last test run which may be confusing, maybe it should be moved elsewhere?

[1]: If you want an import ASCII order reproduction, create the following files:

a.py

from nautobot.extras.jobs import Job
from b import hello


class WillFail(Job):
  class Meta:
    description = 'test'
    commit_default = False

  def run(self, data, commit):
    return self.log_info(message=hello)

b.py

hello = 'Hello World'

c.py

from nautobot.extras.jobs import Job
from b import hello


class WillSucceed(Job):
  class Meta:
    description = 'test'
    commit_default = False

  def run(self, data, commit):
    return self.log_info(message=hello)

Thanks,
Alexandre

[u1735067]

Nobody ?

To continue in the Jobs mechanics, test_* seems to be executed in an arbitrary order (or the dir() order, which seems to be by variable name length growing order) ; to implement some continue/stop tests (no need to continue on advanced checks if basic tests failed), could it be possible to sort the tests by name, and/or add some tests_order variable in the Meta class?

Using run() to sort tests as a workaround makes the logs going into the same container unfortunately (or it requires hacks to reproduce the test_* mechanics).

[glennmatthews]

The test_ functions are a carryover from NetBox's "Reports" functionality; the design there was (as I understand it) that each test function would be a self-contained set of tests to report on, so there wasn't really any concept of dependencies between tests and the like. Personally I'd recommend against relying on this behavior in new Jobs (again, perhaps something we should document better); I would agree with your proposal of putting your own control logic in run() instead.

It should be possible to influence which grouping the log messages go into by simply setting self.active_test to the desired grouping before calling the Job.log_*() methods; alternatively you can call self.job_result.log(..., grouping="my grouping", ...) directly if that's easier for you.

A PR to improve the Jobs documentation with more guidelines and best practices along these lines would be more than welcome! :-)

[glennmatthews]

Thank you for the question!

The Git repository Job discovery implementation, much like the $JOBS_ROOT Job discovery, is really designed more around importing individual files in isolation - as you've seen here, while it may be possible to work around this, it's definitely outside the scope of how the feature is "intended" to be used. We could probably stand to improve the documentation and recommendations here to make this more explicit.

I'll state that from my viewpoint, if there's enough complexity in your Jobs that you need to have a common "library" of code to be used across multiple Jobs, my general recommendation would be to package the library code (at least) into a Python package and/or a Nautobot plugin so that it all can take advantage of the standard Python packaging and source code discovery capabilities. You could include the Jobs themselves in this plugin as well (if they are not expected to change frequently and hence require re-installation when updated) or keep them separately in the Git repository (if they're actively being updated and you want the ease-of-use of being able to reload them on-the-fly from Git).

I'll reply to your follow-up questions in a separate post when I have some more time. Thanks again!

[u1735067]

A bit late, but thank you for your replies!

In the end, the code about Nautobot (jobs, config context schemas) was separated in it's own repository (to avoid repeating the code for multiple infras) and the AAA_ prefix was kept for the shared code for simplicity.

Gitlab is used to host the code, so to avoid manual sync, a pipeline was added to list the repos and if the slug+branch match, call the /sync endpoint. About this, the extra.git add + extra.git change permissions are required to execute a sync, maybe a custom permission could be used here?

For the test_ jobs, your suggestion was used: custom run() + self.active_test manually modified before calling the tests (to avoid setting the grouping_key each time).