Skip to content

🛠️ HOWTO Guides

Welcome to the Unibeam Platform HOWTO Guides! This section contains step-by-step instructions for common operational tasks, deployments, and troubleshooting procedures.

📚 Table of Contents

🚀 Deployment & CI/CD

  • How to Deploy Applications - Complete guide for deploying applications using GitHub Actions on AWS EKS
  • GitHub Actions workflow configuration
  • Docker image build and push to ECR
  • ArgoCD manifest updates
  • Deployment monitoring and verification

📊 Monitoring & Observability

  • Grafana Backup & Restore - Backup and restore Grafana dashboards and datasources
  • Using containerized backup tool
  • Environment-specific configurations
  • Restore procedures and best practices
  • Permission management

📦 Infrastructure Operations

  • Helm Chart Upgrades - Manage Helm chart installations and upgrades
  • Standalone Helm operations (outside ArgoCD)
  • Chart upgrades and rollbacks
  • Templating and dry-run operations

  • Context management and troubleshooting

  • S3 Pod Mounts - Mount S3 buckets as volumes in Kubernetes pods

  • S3 CSI driver configuration
  • Storage class setup
  • Pod volume mount examples
  • Access modes and permissions

🎯 Quick Navigation

Common Tasks

Task Guide Use Case
Deploy a service How to Deploy New service deployment or updates
Backup Grafana Grafana Backup Regular backups or before upgrades
Upgrade Helm chart Helm Upgrades Infrastructure component updates
Mount S3 in pods S3 Pod Mount Access S3 data from applications

By Environment

Production Operations: - Deployment procedures: How to Deploy - Monitoring backups: Grafana Backup - Infrastructure upgrades: Helm Upgrades

Development & Testing: - Quick deployments: How to Deploy - Testing configurations: Helm Upgrades - Storage testing: S3 Pod Mount

📋 Guide Format

Each HOWTO guide follows this structure:

  1. Overview - What the guide covers
  2. Prerequisites - Required tools and access
  3. Step-by-Step Instructions - Detailed procedures
  4. Examples - Real-world examples
  5. Troubleshooting - Common issues and solutions
  6. Best Practices - Recommended approaches

Infrastructure

Monitoring

CI/CD

💡 Tips & Best Practices

General Guidelines

Before You Start

  • Always have proper AWS credentials configured
  • Ensure kubectl context is set to the correct cluster
  • Review related documentation for context
  • Test in development before production

Production Changes

  • Always use GitOps (ArgoCD) for production deployments
  • Avoid manual kubectl operations in production
  • Document all manual interventions
  • Have a rollback plan ready

Getting Help

If you encounter issues: 1. Check the troubleshooting section in the relevant guide 2. Review logs in Loki and Grafana dashboards 3. Consult with the DevOps team 4. Open an issue in the relevant repository

🆕 Contributing New Guides

Have a procedure that should be documented? Follow these steps:

  1. Create the Guide 

    cd /Users/alexm/Github/troubleshooting-docs/docs/DevOps/HOWTO
touch new-guide.md

  2. Use the Template Structure

  3. Title and overview
  4. Prerequisites
  5. Step-by-step instructions
  6. Examples
  7. Troubleshooting

  8. Best practices

  9. Update This README

  10. Add entry to Table of Contents
  11. Add to Quick Navigation table

  12. Include in Related Documentation

  13. Submit for Review 

    git add .
git commit -m "Add HOWTO guide for [topic]"
git push origin main

📞 Support

For questions or assistance:

  • DevOps Team: Reach out via Slack
  • Documentation Issues: Open an issue in troubleshooting-docs repository
  • Infrastructure Issues: Check Troubleshooting Section

🔄 Recently Updated

Guide Last Updated Changes
How to Deploy January 2025 Added ArgoCD App-of-Apps pattern
Grafana Backup January 2025 Updated backup tool version
Helm Upgrades January 2025 Added rollback procedures
S3 Pod Mount January 2025 Added CSI driver examples

Documentation Quality

All HOWTO guides are regularly reviewed and updated to reflect current practices and infrastructure changes.

For the complete DevOps documentation, see the DevOps Overview.