Welcome to the Cog Book!

Note

This book is released under the Apache 2 license. More information about contributing to this book along with access to the source code and previous releases is available at GitHub.

Cog is Built for ChatOps.

Use Cog to manage your infrastructure, support peer learning, and conduct collaborative research at the same time, right from chat. Cog is easy to install and simple to operate while remaining powerful enough to handle complex enterprise workflows.

Table of Contents

• 1. Getting Started
  • 1.1. Introducing Cog
  • 1.2. Current Features
    • 1.2.1. Extensibility
    • 1.2.2. Adaptability
    • 1.2.3. Security
    • 1.2.4. Chat-Provider Agnostic
  • 1.3. Get Started
  • 1.4. Communication
    • 1.4.1. GitHub Issues
    • 1.4.2. Cog Public Chat via Slack
  • 1.5. User experience feedback
  • 1.6. Installation Guide
    • 1.6.1. Installing and Running Cog with Docker Compose
    • 1.6.2. Connecting Cog To Slack
    • 1.6.3. Connecting Cog to HipChat
    • 1.6.4. Creating a User and Running a Command
    • 1.6.5. Installing and Configuring a Bundle
  • 1.7. Building and Running Cog from Scratch
• 2. Bootstrapping Cog
• 3. Installing and Managing Relays
  • 3.1. Configuring A New Relay
  • 3.2. Relays & Relay Groups
• 4. Commands and Bundles
  • 4.1. Commands
  • 4.2. Bundles
    • 4.2.1. Bundle Permissions and Rules
    • 4.2.2. Example: The operable Bundle
  • 4.3. Invoking Commands
    • 4.3.1. Shortcuts
  • 4.4. Implementation Details
• 5. Managing Bundles
  • 5.1. Prerequisites
  • 5.2. Installing bundles
  • 5.3. The config file
  • 5.4. Templates
  • 5.5. Enabling and Disabling Bundle Versions
    • 5.5.1. Relay Groups
  • 5.6. Uninstalling Bundles and Bundle Versions
• 6. Writing A Command Bundle
  • 6.1. Scenario: Tweet from Cog
  • 6.2. Tweet from Plain Ruby
  • 6.3. First Steps Toward Cog: Arguments
  • 6.4. Describe it to Cog: Bundle Definitions
  • 6.5. Installing the Bundle
  • 6.6. Dynamic Configuration
  • 6.7. Output
    • 6.7.1. Templating Output
  • 6.8. Tweet Permissions and Rules
  • 6.9. Options: Tweet from different accounts
  • 6.10. Packaging with Docker
  • 6.11. Handling Input
    • 6.11.1. Usecase: Getting Statistics on Recent Tweets
    • 6.11.2. A recent_tweets Command
    • 6.11.3. Tweet Statistics: Favorites and Retweets
  • 6.12. Error Handling
  • 6.13. Logging
  • 6.14. Summary
• 7. Configuring password resets
• 8. Permissions and Rules
  • 8.1. Authorization Rules
  • 8.2. Components of the Authorization System
    • 8.2.1. Permissions
    • 8.2.2. Roles
    • 8.2.3. Users
    • 8.2.4. Groups
  • 8.3. Bringing It All Together
• 9. Command Execution Rules
  • 9.1. Rule Structure
  • 9.2. Arguments and Options Qualifiers
  • 9.3. Permissions
  • 9.4. Site Namespace
• 10. Bundle Configs
  • 10.1. Simple bundle configs
  • 10.2. Commands
  • 10.3. Other fields
    • 10.3.1. Permissions
  • 10.4. Standard bundle configs
    • 10.4.1. Documentation fields
      • 10.4.1.1. Bundle
      • 10.4.1.2. Command
  • 10.5. Conclusion
• 11. Command Environment Variables
  • 11.1. Arguments
  • 11.2. Options
    • 11.2.1. List-valued Options
  • 11.3. General Metadata
• 12. Dynamic Command Configuration
  • 12.1. Core Concepts
    • 12.1.1. Layers
  • 12.2. How To Manage Dynamic Configuration Values
    • 12.2.1. Manual Management of Dynamic Configuration
    • 12.2.2. Cog-managed Dynamic Configuration
      • 12.2.2.1. Adding a base layer of dynamic configuration
      • 12.2.2.2. Showing the layers that exist
      • 12.2.2.3. Deleting Configuration Layers
• 13. Returning data from Cog
• 14. Services
  • 14.1. Overview
  • 14.2. Design Journey
  • 14.3. Cog Services API
    • 14.3.1. Authentication and Authorization
    • 14.3.2. Routes
    • 14.3.3. /v1/services/meta
  • 14.4. Memory Service
    • 14.4.1. Data Model
      • 14.4.1.1. Accumulate (Default)
      • 14.4.1.2. Replace
  • 14.5. Chat Service
• 15. Templates
  • 15.1. Basic Greenbar Syntax
  • 15.2. Overall Template Processing Logic
    • 15.2.1. All pipelines return a “results” list
    • 15.2.2. Commands can specify a template when they return to Cog
    • 15.2.3. Last output “wins”
    • 15.2.4. Meta-templates, not Templates
  • 15.3. Advanced Greenbar Usage
  • 15.4. Writing a custom tag
  • 15.5. Customizing the standard error template
    • 15.5.1. Configuring
    • 15.5.2. error.greenbar
• 16. Installing Your First Command Bundle
  • 16.1. Creating your bundle
  • 16.2. Assigning your bundle to a relay
  • 16.3. Enabling your bundle
  • 16.4. Profit!
• 17. Developing a Trigger
  • 17.1. Let’s Make It More Interesting
  • 17.2. Going Further: Composability and Flexibility
  • 17.3. Filtering
  • 17.4. Validation
  • 17.5. Conclusion
• 18. Cog Architecture
  • 18.1. Cog
  • 18.2. PostgreSQL
  • 18.3. MQTT
  • 18.4. Relay
    • 18.4.1. Code isolation
    • 18.4.2. Availability
    • 18.4.3. Language Choice
  • 18.5. cogctl
    • 18.5.1. More information
• 19. Command pipelines
  • 19.1. Pipelines
    • 19.1.1. Command Execution
      • 19.1.1.1. Collecting results
    • 19.1.2. Variable Substitution
• 20. Redirecting Pipeline Output
  • 20.1. Redirection Destinations
  • 20.2. Multiple Redirect Destinations
  • 20.3. Easter Egg: Trolling Your Coworkers
• 21. Triggers
  • 21.1. Anatomy of a Trigger
  • 21.2. Manipulating Triggers
    • 21.2.1. Create a Trigger
    • 21.2.2. Show a Trigger
    • 21.2.3. Showing all Triggers
    • 21.2.4. Update a Trigger
  • 21.3. Deleting a Trigger
    • 21.3.1. Enabling / Disabling a Trigger
  • 21.4. Invoking a Trigger
  • 21.5. Initial Calling Environment for Trigger-Invoked Pipelines
  • 21.6. Response Disposition In Triggers
    • 21.6.1. Redirect Destinations in Triggered Pipelines
    • 21.6.2. Trigger Timeouts
    • 21.6.3. Errors and “Empty” Pipelines
• 22. User management
  • 22.1. Self Registration
  • 22.2. User Management via Cogctl
  • 22.3. User Management via Cog’s API
• 23. Contributor License Agreement
• 24. Cog Server Configuration
• 25. Relay Configuration
• 26. Command Output Tags
  • 26.1. Examples
  • 26.2. Tags
• 27. Greenbar Tags
  • 27.1. if
    • 27.1.1. Example
    • 27.1.2. Operators
  • 27.2. Each
    • 27.2.1. Examples
  • 27.3. Join
    • 27.3.1. Examples
  • 27.4. Count
    • 27.4.1. Examples
  • 27.5. Break
    • 27.5.1. Examples
  • 27.6. Attachment
    • 27.6.1. Attributes
    • 27.6.2. Examples
  • 27.7. Json
    • 27.7.1. Examples
• 28. Audit Log Events
  • 28.1. API Events
    • 28.1.1. API Event Types
    • 28.1.2. Common Fields
    • 28.1.3. API Event-specific Data
  • 28.2. Pipeline Events
    • 28.2.1. Pipeline Event Types
    • 28.2.2. Common Fields
    • 28.2.3. Pipeline Event-specific Data
• 29. Glossary
• 30. Designing ChatOps Commands
  • 30.1. Small Sharp Tools
  • 30.2. Naming
  • 30.3. Designing Command Interfaces
  • 30.4. Pipeline Friendly Output
• 31. Notes on Chat Platform Support
  • 31.1. No Emoji or Auto-Linking in HipChat

• Index
• Search Page