FixDoc

FixDoc is a command-line interface (CLI) tool designed for cloud engineers to efficiently capture and search for infrastructure fixes. By addressing the issue of losing vital knowledge embedded in Slack threads or personal notes, FixDoc aids teams in preventing the repeated debugging of already resolved infrastructure errors.

Problem Addressed

Infrastructure errors frequently recur, such as S3 bucket naming collisions or Terraform state locks. These resolved issues often get lost in conversations, leading to wasted hours as teams search for previously solved problems that might also leave with departing engineers.

Key Functionality

FixDoc streamlines the error resolution process by allowing users to pipe error output directly from tools like Terraform or kubectl into the CLI. It automatically detects the source of the error, extracting essential details including the provider, resource type, file location, line number, and error code. Users can then input a resolution for future reference. This creates a searchable history of fixes, enabling rapid retrieval when similar issues arise.

Example Usage

To capture a Terraform fix, simply execute:

terraform apply 2>&1 | fixdoc capture

For example, FixDoc captures:

Captured from Terraform:

  Provider: AWS
  Resource: aws_s3_bucket.data
  File:     storage.tf:12
  Code:     BucketAlreadyExists
  Error:    BucketAlreadyExists: error creating S3 Bucket...

  Suggestions:
    - S3 bucket names are globally unique. Use a different name
    - Add a random suffix to the bucket name

What fixed this?: Added account ID suffix to bucket name
Tags [comma-separated]: terraform,aws,s3

Later, searching for the S3 error can be done efficiently with:

$ fixdoc search "S3"
  [a1b2c3d4] Terraform AWS: S3 BucketAlreadyExists  (terraform,aws,s3)

Features

• Direct Error Piping: Capture errors from terraform apply or kubectl without manual copying.
• Automatic Error Parsing: Supports Terraform (AWS, Azure, GCP) and Kubernetes.
• Efficient Search: Quickly find fixes by keywords, tags, or error messages.
• Pre-apply Analysis: Review Terraform plans against documented fixes.
• Team Synchronization: Share fixes through a shared Git repository.
• Markdown Export: Each fix is saved as a shareable .md file.

Demo Availability

A built-in demo allows users to try FixDoc without a live cloud environment, walking through the capture pipeline with sample errors:

pip install fixdoc
fixdoc demo tour

Development and Contribution

The project is open for contributions. Developers interested in improving or extending the functionality can clone the repository, run tests, and format the code using the provided guidelines.

Future Developments

FixDoc aims to evolve with features like similar fix suggestions, improved import/export capabilities, additional parsers for more infrastructure tools, and AI-generated fix suggestions based on historical data.