Azqr Developer

Azure Quick Review (azqr) Development Skill

Expert guidance for autonomous agents and developers contributing to the Azure Quick Review (azqr) project.

Project Overview

Azure Quick Review (azqr) is a CLI tool written in Go that analyzes Azure resources for compliance with Azure's best practices and recommendations. The tool scans Azure resources using:

• Azure Resource Graph (ARG) queries from the Azure Proactive Resiliency Library v2 (APRL)
• Azure Resource Manager (ARM) rules built with the Azure Golang SDK

Quick Start

Prerequisites

• Go 1.23.3 or higher
• Valid Azure authentication (Service Principal, Managed Identity, or Azure CLI)

Essential Commands

# Build the project
make build

# Run all tests (REQUIRED before submitting pull requests)
make test

# Clean build artifacts
make clean

# View all available targets
make help

Project Structure

azqr/
├── cmd/azqr/               # Main CLI application entry point
│   ├── main.go            # Application entry point
│   └── commands/          # CLI command implementations (one file per Azure service)
├── cmd/server/            # Server mode implementation
├── internal/              # Internal packages
│   ├── scanner.go         # Main scanning logic
│   ├── models/            # Data models and filters
│   ├── renderers/         # Output formatters (Excel, CSV, JSON)
│   ├── scanners/          # Service-specific scanners (one per Azure service)
│   ├── graph/             # Azure Resource Graph queries
│   └── aigov/             # AI Governance utilities
├── data/                  # Static data files
│   └── recommendations.json # Generated recommendations data
├── examples/              # Example configurations and CI/CD pipelines
├── docs/                  # Documentation website (Hugo-based)
└── Makefile              # Build automation

Code Style and Standards

Naming Conventions

• Variables: Use camelCase for all variable names
• Functions: Use MixedCaps for exported functions, mixedCaps for unexported
• Packages: Use lowercase, single-word package names (avoid underscores)
• Interfaces: Name with -er suffix when possible (e.g., Scanner, Renderer)

Documentation

• Always add code comments using godoc style for exported functions
• Document why, not what, unless the what is complex
• Start comments with the name of the thing being described
• Write comments in complete sentences

Authentication

All code must support multiple authentication methods:

• Service Principal (environment variables: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
• Azure Managed Identity
• Azure CLI authentication

Error Handling

• Follow Go idiomatic error handling patterns
• Check errors immediately after the function call
• Wrap errors with context using fmt.Errorf with %w verb
• Keep error messages lowercase and don't end with punctuation
• Name error variables err

Development Workflow

1. Adding Support for New Azure Services

When adding a new Azure service, follow this systematic approach:

• Create scanner in internal/scanners/<service>/
• Implement the scanner interface
• Support both ARM-based and ARG-based recommendations
• Include appropriate error handling and logging

• Add command in cmd/azqr/commands/<service>.go
• Follow the existing command pattern
• Use appropriate service abbreviation (see README.md)

• Update models in internal/models/
• Add service-specific models if needed
• Ensure models support JSON serialization

• Add comprehensive tests
• Include unit tests for scanner logic
• Test both success and error cases
• Use table-driven tests for multiple scenarios

• Update documentation
• Add service to supported services list in README.md
• Document any service-specific requirements

2. Testing Requirements

CRITICAL: Always run make test before submitting pull requests. This is non-negotiable.

The test command includes:

• Linting (golangci-lint) - Code quality checks
• Go vet checks - Static analysis
• Module tidiness verification - Dependency management
• Unit tests with race condition detection
• Coverage reporting

# Run the full test suite (ALWAYS run before PR)
make test

# Individual test components
make lint    # Run linter
make vet     # Run go vet
make tidy    # Check module tidiness

3. Building and Distribution

# Build for current platform
make build

# Build for specific OS/architecture
GOOS=linux GOARCH=amd64 make build
GOOS=windows GOARCH=amd64 make build

# Build Docker image
make build-image

# Build with version information
PRODUCT_VERSION=1.0.0 make build

# Update recommendations.json after adding rules
make json

Common Development Tasks

Adding a New Recommendation Rule

• Identify the target Azure service
• Locate the appropriate scanner in internal/scanners/<service>/
• Add the rule logic following existing patterns:
• Use consistent naming conventions
• Include clear comments explaining the rule
• Reference official Azure documentation
• Update tests to cover the new rule
• Run make json to update recommendations.json
• Verify with make test

Fixing Bugs

• Reproduce the issue with a minimal test case
• Add regression test if missing
• Implement fix following project patterns
• Verify fix with make test
• Update documentation if the bug revealed unclear behavior

Performance Optimization

• Use the throttling utilities in internal/throttling/ for rate limiting
• Implement concurrent scanning where appropriate (use goroutines wisely)
• Cache expensive operations when possible
• Profile using Go's built-in tools before optimizing
• Focus on algorithmic improvements first

Scanner Implementation Patterns

Scanner Interface

// internal/scanners/<service>/<service>.go
package <service>

import (
    "context"
    "github.com/Azure/azqr/internal/models"
)

// Scanner implements the service scanner interface
type Scanner struct {
    // Scanner fields (config, client, etc.)
}

// Scan performs the compliance scan for the service
func (s *Scanner) Scan(ctx context.Context) ([]models.Recommendation, error) {
    // Implementation
    // 1. Fetch resources
    // 2. Apply recommendation rules
    // 3. Return findings
}

Command Implementation

// cmd/azqr/commands/<service>.go
package commands

import (
    "github.com/spf13/cobra"
)

func init() {
    // Register command with root command
}

var <service>Cmd = &cobra.Command{
    Use:   "<service>",
    Short: "Scan <Service Name>",
    Long:  "Detailed description of what this scanner does",
    Run:   <service>Run,
}

func <service>Run(cmd *cobra.Command, args []string) {
    // Command implementation
    // 1. Parse flags
    // 2. Initialize scanner
    // 3. Run scan
    // 4. Output results
}

Testing Patterns

Table-Driven Tests

func TestScanner_Scan(t *testing.T) {
    tests := []struct {
        name    string
        setup   func() // setup test environment
        want    int    // expected number of recommendations
        wantErr bool
    }{
        {
            name:    "success case",
            setup:   func() { /* setup */ },
            want:    5,
            wantErr: false,
        },
        {
            name:    "error case",
            setup:   func() { /* setup */ },
            want:    0,
            wantErr: true,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            tt.setup()
            // test implementation
        })
    }
}

Runtime Debugging and Troubleshooting

Enable Debug Mode

# Set environment variable for detailed logging
export AZURE_SDK_GO_LOGGING=all

# Run with debug flag
./azqr scan --debug

Common Issues and Solutions

• Authentication Failures
• Verify Azure credentials are set correctly
• Check permissions (requires Reader on Subscription/Management Group)
• Test with az account show if using Azure CLI auth

• Rate Limiting
• Use appropriate throttling settings
• Implement exponential backoff for retries
• Consider batching requests when possible

• Memory Usage
• Monitor for large subscriptions with many resources
• Use streaming or pagination for large datasets
• Profile memory usage with pprof

• Network Connectivity
• Ensure access to Azure APIs
• Check firewall and proxy settings
• Verify DNS resolution

Environment Variables

Authentication

# Service Principal
AZURE_CLIENT_ID="<service-principal-id>"
AZURE_CLIENT_SECRET="<service-principal-secret>"  
AZURE_TENANT_ID="<tenant-id>"

# Credential Chain Configuration
AZURE_TOKEN_CREDENTIALS="dev"   # Use Azure CLI/Azure Developer CLI
AZURE_TOKEN_CREDENTIALS="prod"  # Use env vars/workload identity/managed identity

Debugging

AZURE_SDK_GO_LOGGING="all"      # Enable detailed SDK logging

Contributing Guidelines

Pull Request Requirements

• Testing: Run make test and ensure all tests pass (100% required)
• Code Quality: Follow the existing code style and patterns
• Documentation: Update relevant documentation (README, code comments)
• Commit Messages: Use clear, descriptive commit messages
• Dependencies: Minimize new dependencies; justify if necessary

Supported Azure Services

The project currently supports 50+ Azure services including:

• Compute: VMs, AKS, Azure Functions, App Service, etc.
• Storage: Storage Accounts, Disks, NetApp Files, etc.
• Networking: Virtual Networks, Load Balancers, Application Gateway, etc.
• Databases: SQL, Cosmos DB, PostgreSQL, MySQL, etc.
• And many more...

When adding new services:

• Use appropriate abbreviations (see README.md for existing conventions)
• Implement both ARM-based and ARG-based recommendations where applicable
• Follow the scanner interface pattern
• Include appropriate error handling and logging

Output Formats

azqr generates reports in multiple formats:

• Excel (default): Multi-sheet workbook with recommendations, impacted resources, inventory, etc.
• CSV: Same data as Excel but in CSV format (use --csv flag)
• JSON: Machine-readable format for automation

Key Resources and References

• Azure Proactive Resiliency Library v2 (APRL) - Source of ARG queries
• Azure Orphaned Resources - Orphan detection patterns
• Azure SDK for Go - Official Azure Go SDK
• Project Documentation - Full documentation site
• Effective Go - Go best practices
• Go Code Review Comments - Go code review guide

Support and Community

• Issues: Use GitHub Issues for bug reports and feature requests
• Discussions: Use GitHub Discussions for questions and support
• Security: Report security issues following the SECURITY.md guidelines
• Code of Conduct: Follow the Microsoft Open Source Code of Conduct

Critical Reminders

• Always run make test before submitting a pull request - This is the most important rule
• Use camelCase for variable names
• Add godoc-style comments to all exported functions
• Support all authentication methods (Service Principal, Managed Identity, Azure CLI)
• Follow Go idiomatic error handling
• Keep code simple and readable
• Update recommendations.json with make json after adding rules
• Reference APRL documentation when implementing ARG-based rules
• Test both success and error paths

10. Keep scanner implementations consistent with existing patterns