Skip to content

Nautobot ChatOps Installation Guide

This guide outlines the process of enabling Nautobot ChatOps, which includes:

Glossary

  • Chat Platform: A communication service (e.g., Mattermost, Microsoft Teams, Slack, Cisco Webex).
  • Command: A particular instruction sent by users via the Chat Platform, which is then processed by an Integration.
  • Dispatcher: A class specific to the Chat Platform that processes incoming chat messages, executes commands, and sends results back to the Chat Platform.
  • Integration: A component that defines commands, handles data retrieval, and manipulation for specific tools or services (e.g., IP Fabric, AWX / Ansible Tower, Palo Alto Panorama, Grafana, Cisco ACI, Cisco Meraki, Arista CloudVision).
  • Platform View: A Django View designed to handle Chat Platform data.
  • Sub-command: An instruction that is nested within a Command.
  • Worker: A module within an Integration, designed to handle and process a Command, receiving data from Platform Views and returning results via a Dispatcher's generic API.

Prerequisites

Ensure the following before beginning the installation:

  • Nautobot 1.5.4 or higher is installed.
  • Your chat platform can access Nautobot via an HTTPS URL.
    • Some chat platforms require SSL certificate verification to communicate with the Nautobot server.
    • For development, you may use HTTP.
  • You have sudo access on the Nautobot server.
  • You have administrative access within the Nautobot Web UI.

Potential Apps Conflicts

Warning

If upgrading from 1.x version to 2.x version of nautobot-chatops App, note that it now incorporates features previously provided by individual apps.

Conflicting Apps list:

  • nautobot_plugin_chatops_aci
  • nautobot_plugin_chatops_ansible
  • nautobot_plugin_chatops_arista_cloudvision
  • nautobot_plugin_chatops_ipfabric
  • nautobot_plugin_chatops_grafana
  • nautobot_plugin_chatops_meraki
  • nautobot_plugin_chatops_panorama

To prevent conflicts during nautobot-chatops upgrade:

  • Remove conflicting applications from the PLUGINS section in your Nautobot configuration before enabling the latest nautobot-chatops version.
  • Transfer the configuration for conflicting apps to the PLUGIN_CONFIG["nautobot_chatops"] section of your Nautobot configuration. See development/nautobot_config.py for an example. Each integration set up guide contains a chapter with upgrade instructions.
  • Remove conflicting applications from your project's requirements.

These steps will help prevent issues during nautobot-chatops upgrades. Always back up your data and thoroughly test your configuration after these changes.

Warning

If conflicting Apps remain in PLUGINS, the nautobot-chatops App will raise an exception during startup to prevent potential conflicts.

Chat Platforms Configuration

The nautobot-chatops package supports multiple chat platforms.

Set up your chosen chat platform:

Installation Guide

Note

Install the App manually or via Python's pip. For detailed information, visit the Nautobot documentation. The pip package for this App is nautobot-chatops.

Warning

Follow the Nautobot App Installation Instructions for complete and most recent guidelines.

Install Guide

Note

Apps can be installed from the Python Package Index or locally. See the Nautobot documentation for more details. The pip package name for this app is nautobot-chatops.

The app is available as a Python package via PyPI and can be installed with pip:

pip install nautobot-chatops

To use specific integrations, add them as extra dependencies:

pip install nautobot-chatops[ansible]

To auto-install Nautobot ChatOps during future upgrades, add nautobot-chatops to local_requirements.txt (create if not

present) in the Nautobot root directory, adjacent to requirements.txt:

echo nautobot-chatops >> local_requirements.txt

After installation, enable the App in your Nautobot configuration by updating your nautobot_config.py file:

  • Include "nautobot_chatops" in the PLUGINS list.
  • Add the "nautobot_chatops" dictionary to PLUGINS_CONFIG and override defaults if necessary.
# In your nautobot_config.py
PLUGINS = ["nautobot_chatops"]

PLUGINS_CONFIG = {
    "nautobot_chatops": {
        # ADD YOUR SETTINGS HERE
    }
}

Added in version 3.0.0

Some configuration settings have now been added to the Nautobot Admin Config page. See Nautobot Admin

Configuration Guide

Adjust the App's behavior with the following settings:

Configuration Setting Description Mandatory? Default Available on Admin Config
delete_input_on_submission Removes the input prompt from the chat history after user input No False No
restrict_help Shows Help prompt only to users based on their Access Grants No False No
send_all_messages_private Ensures only the person interacting with the bot sees the responses No False No
fallback_chatops_user Nautobot User for Chat Commands to use if the user has not linked their account Yes chatbot Yes
session_cache_timeout Controls session cache No 86400 No

Granting Access to the Chat Platform

Nautobot provides an HTTP endpoint(s) for each supported chat platform. Although these endpoints do implement authentication to prevent arbitrary HTTP requests from triggering bot actions, they can accept and act on any validly-formed request from the chat platform, which could originate from any organization, team, channel(room), or user who has access to the chat system.

For most realistic deployments, open and unrestricted access to the bot from any chat account is undesirable. Therefore, in this version, access to the chatbot defaults to "deny all" when initially installed, but varying scopes (per organization, per channel, per user) and degrees (all commands, all sub-commands of a single command, single sub-command of a single command) of access can be granted through Nautobot.

The access grants are maintained in Nautobot's database for persistence, and are change-logged like other Nautobot records.

access grants

Note that access grants are based on the chat platform's internal ID values for users, channels, and organizations; although you can and should attach a user-friendly name to each access grant for reference, it is the ID value that is actually enforced by Nautobot. On some platforms and for some access scopes, the Nautobot UI "Look up Value from Name" button can be used to auto-discover the ID value corresponding to a given name; if this fails, you can always attempt to send a request to Nautobot from the desired user/channel/organization and retrieve the ID value from the resulting error message to use to define a new access grant.

The specific access grants you will want to define will depend on your operational requirements, but some examples are provided below to help you get started.

Example: Unrestricted Access Within a Single Organization

In the simplest realistic configuration example, access to all chatbot commands is granted for all users and all channels in a single organization scope.

Command Sub-command Grant type Name Value
* * organization my-org T202B88NN
* * channel(room) any *
* * user any *

Example: Split Command Access to Different Channels

In this example, Nautobot is providing two separate command groupings, each of which is intended for use by a different team within the organization. Each team has a dedicated channel on the chat platform, to which access is already controlled by other means, so we can allow all users within a given channel access.

Command Sub-command Grant type Name Value
* * organization my-org T202B88NN
support * channel(room) support C2020H455
devops * channel(room) devops C3030I566
* * user any *

Example: Restrict Specific Command and Sub-command to Specific Users in a Specific Channel

In this example, Nautobot has a potentially-destructive sub-command that should only be used by a handful of admin users. Other sub-commands under this sub-command can be used by anyone in the devops channel. Other commands are harmless fun and can be used by any user in the organization in any channel.

Command Sub-command Grant type Name Value
* * organization my-org T202B88NN
jokes * channel(room) any *
jokes * user any *
network * channel(room) devops C3030I566
network history user any *
network redeploy user admin1 U2049K991
network redeploy user admin2 U2039K725
network redeploy user admin3 U7924K784
network status user any *
weather * channel(room) any *
weather * user any *

Added in version 3.0.0

Nautobot ChatOps now uses the built-in Nautobot permissions for Nautobot Objects (Devices, Locations, Racks, etc.). Each user will need to link their Nautobot Account with their Chat Platform User Account. Login to Nautobot then access the Link ChatOps Account within the Plugins menu. Here you can provide your email address and select the ChatOps Platform you are using, then click the Look up User ID from Email to get your Chat User ID.

A Nautobot user can have multiple Chat users connected, but the Chat User can only be linked to one Nautobot user. As an example my team is transitioning from Slack to Mattermost. My Slack User ID and my Mattermost User ID can both be connected to the same Nautobot User.

Link Accounts

Admins have the ability to access the Nautobot Admin page and can use ChatOps Account Links page to link multiple accounts, but you will need to know the Chat Platforms user IDs for each user you are linking.

Test Your Chatbot

Finally, test your chatbot's functionality within your chosen chat application, using a command like /nautobot get-devices.

Integrations Configuration

The nautobot-chatops package includes multiple integrations. Each requires extra dependencies defined in pyproject.toml. See the installation guide for instructions on installing these dependencies.

Set up integrations using the specific guides: