Merge pull request #1 from astronomer/pre-release

Release orbis docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug Report
+about: Create a report to help us improve the documentation
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Orbis Version
+<!-- Please specify the version of Orbis you're using -->
+- Version: [e.g. 0.5.0]
+
+## What Happened
+<!-- A clear and concise description of what happened -->
+
+## What Should Have Happened
+<!-- A clear and concise description of what you expected to happen -->
+
+## Additional Context
+<!-- Add any other context about the problem here. This could include:
+- Screenshots
+- Error messages
+- Environment details (OS, Docker version, etc.)
+- Steps to reproduce the issue
+-->

.github/workflows/deploy.yml

@@ -0,0 +1,28 @@
+name: Deploy Documentation
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

LICENSE

@@ -0,0 +1,13 @@
+All Rights Reserved
+
+Copyright (c) 2021 Astronomer, LLC
+
+Created by Astronomer, LLC
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,2 +1,46 @@
-# orbis-docs
-Documentation for orbis
+# Orbis Documentation
+<div style="text-align:center">
+   <img src="docs/assets/orbis_logo.svg" width="50%" alt="Orbis Logo">
+</div>
+
+Orbis is a reporting tool designed for Astronomer Software that provides detailed insights into your Apache Airflow deployments. It collects and analyzes metrics to help you understand resource utilization, performance patterns, and system health.
+
+## Key Features
+
+- **Resource Metrics**: Track CPU usage, memory consumption, and resource allocation efficiency
+- **Performance Analysis**: Monitor task success/failure rates, processing trends, and execution latency
+- **System Health**: Get insights into scheduler health, worker status, and system availability
+- **Comprehensive Reports**: Generate detailed PDF reports with visualizations and statistics
+
+## Quick Start
+
+```bash
+# Pull the latest version
+docker pull quay.io/astronomer/orbis:0.5.0
+
+# Run with environment variables
+docker run --pull always --rm -it \
+  --env-file .env \
+  -v $(pwd)/output:/app/output \
+  quay.io/astronomer/orbis:0.5.0 orbis compute-software \
+  -s START_DATE \
+  -e END_DATE \
+  -o ORGANIZATION_ID
+```
+
+## Documentation
+
+The documentation covers:
+- Installation Guide
+- Usage Instructions
+- API Documentation
+
+## Support
+
+If you encounter any issues, please:
+1. Check the documentation in this repository
+2. Create a new issue using our issue templates
+
+## License
+
+Copyright (c) 2021 Astronomer, LLC

docs/index.md

@@ -0,0 +1,40 @@
+# Orbis - Astronomer Software Deployment Compute Report Generator
+
+Orbis is a deployment compute report generator tool that analyzes data from Astronomer Software to provide insights into deployment metrics and resource utilization.
+
+## Key Features
+
+- Comprehensive deployment metrics analysis
+- Resource utilization tracking
+- Custom resource allocation support
+- PDF report generation
+- Docker-based deployment for easy setup
+
+## Quick Start with Docker (Recommended)
+
+```bash
+# Pull the latest version
+docker pull quay.io/astronomer/orbis:0.5.0
+
+# Run with environment variables
+docker run --pull always --rm -it \
+  --env-file .env \
+  -v $(pwd)/output:/app/output \
+  quay.io/astronomer/orbis:0.5.0 orbis compute-software \
+  -s START_DATE \
+  -e END_DATE \
+  -o ORGANIZATION_ID
+```
+
+## Documentation Sections
+
+- [Installation](installation.md)
+- [Configuration](configuration.md)
+- [Usage Guide](usage/software_usage.md)
+- [CLI Reference](cli.md)
+- [Contributing](contributing.md)
+- [Changelog](changelog.md)
+
+## Support
+
+For support, please contact [[email protected]](mailto:[email protected])

docs/installation.md

@@ -0,0 +1,59 @@
+# Installation Guide
+
+## 1. Docker (Recommended)
+
+!!! note
+
+    Docker images are currently in beta.
+
+
+The recommended way to run Orbis is using Docker. This ensures consistent behavior across different environments and simplifies the setup process.
+
+### Prerequisites
+
+1. Install [Docker](https://docs.docker.com/get-docker/)
+2. Ensure you have a valid Houston API token (with `SYSTEM_ADMIN` role) for authentication
+
+### Docker Setup
+
+```bash
+# Pull the latest version
+docker pull quay.io/astronomer/orbis:0.5.0
+```
+
+Create a `.env` file with your configuration:
+
+```
+HOUSTON_API_TOKEN=your_token_here
+ORG_ID=your_org_id
+```
+
+
+## 2. Orbis CLI Binary
+
+!!! warning
+
+    Binaries are currently experimental.
+
+If you prefer to run Orbis directly on your system, you can request the binary package from Astronomer. We provide pre-built binaries for:
+
+- Linux (x86_64)
+- macOS (x86_64, arm64)
+- Windows (x86_64)
+
+Please contact your Astronomer representative to obtain the appropriate binary for your platform. They will provide you with:
+
+1. The binary package for your operating system
+2. Instructions for setting up environment variables
+3. Any additional configuration requirements
+
+## Configuration
+
+After installation, you'll need to configure Orbis with your credentials. You will need:
+
+1. A valid Houston API token (with `SYSTEM_ADMIN` role)
+2. Your Organization ID
+3. The reporting period (start and end dates)
+
+See the [Usage Guide](usage/software_usage.md) for detailed setup instructions.
+

docs/modules/api/houston.md

@@ -0,0 +1,66 @@
+# Houston API Integration
+
+The `houston.py` module is a crucial component of Orbis, leveraging the [Houston API](https://www.astronomer.io/docs/software/houston-api) to retrieve essential deployment information. This module provides a comprehensive interface to gather metadata about an organization, its workspaces and deployments, which is fundamental for targeted metric collection.
+
+## Key Components
+
+### API Class
+
+This class encapsulates all interactions with the [Houston API](https://www.astronomer.io/docs/software/houston-api):
+
+- Handles authentication and request headers
+- Provides methods for various API endpoints (deployments, organization, workspaces)
+- Implements error handling and response validation
+
+### Utility Functions
+
+Several utility functions build upon the CoreAPI class to provide higher-level functionality:
+
+- `get_organization_metadata`: Retrieves organization name and associated namespaces
+- `get_cluster_wise_deployments`: Groups deployments by clusters
+- `get_deployment_wise_queues`: Fetches detailed information about worker queues for each deployment
+
+## Leveraging Astro API for Deployment Data
+
+The module efficiently utilizes the Astro API to gather comprehensive deployment information:
+
+1. **Organization-Level Data**:
+    - Retrieves all deployments associated with an organization
+    - Fetches organization metadata
+    - Retrieves a list of all namespaces within the organization
+    - Obtains workspace details for an organization
+    - Groups deployments by their associated worksapces
+    - Gathers detailed metadata for each deployment
+    - Extracts information about executor type, scheduler configuration, and worker queues
+    - Includes information like queue names, worker types, concurrency, and scaling limits
+
+## Why resource conversion is needed in Software
+
+> As software does not have fixed size machines and has custom resource allocator (which can be either completely custom resources or Astronomer units), orbis fetches them to provide an idea of the component sizes as compared to resource utilization. Some deployments may have ample resources allocated but utilizing only a fraction of it.
+
+## Computing resources for Software
+
+- Maximum Worker count: replicas
+- Minimum Worker count: 1 (Defaulted)
+- Worker Concurrency: From Environment Variable, if not set, default to 16
+> `Note:` If environment variable is set with Dockerfile, this will not be considered.
+- Worker Type: Allocated worker limit resources
+
+## Formulas to convert custom resources to AUs:
+
+- Memory: resources["memory"] / 384
+- CPU: resources["cpu"] / 100
+
+- If AU conversion possible, then AUs = any(Memory in AUs, CPU in AUs)
+- If AU conversion not possible, then AUs = [Memory in GB, CPU in vCPU]
+> `Note:` AU conversion possible if the memory is in multiples of 384 and CPU is in multiples of 100 and both are same values.
+
+## Integration with Orbis Workflow
+
+This module plays a vital role in Orbis's operation:
+
+1. It provides the necessary context for metric collection, ensuring that Orbis targets the correct deployments and namespaces.
+2. The deployment configurations retrieved are used to populate the `DeploymentConfig` and `WorkerQueueStats` models.
+3. This information guides the metric collection process in `prometheus.py` and the report generation in `generator.py`.
+
+By leveraging the [Houston API](https://www.astronomer.io/docs/software/houston-api), Orbis can dynamically adapt to the current state of an organization's Software deployments, ensuring accurate and relevant metric collection and reporting.