Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/schaeferka/k8s-dungeon-crawl
https://github.com/schaeferka/k8s-dungeon-crawl
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/schaeferka/k8s-dungeon-crawl
- Owner: schaeferka
- Created: 2024-11-05T00:56:59.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2024-11-29T13:15:17.000Z (about 1 month ago)
- Last Synced: 2024-11-29T13:24:37.994Z (about 1 month ago)
- Language: C
- Size: 3.07 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# K8s Dungeon Crawl
## Introduction
Welcome to **K8s Dungeon Crawl**, a unique project combining the excitement of rogue-like dungeon crawling with the power of cloud-native technologies. This project is designed as a playful experiment to bridge the worlds of gaming and Kubernetes, demonstrating how modern infrastructure can be adapted to novel use cases.
At its core, K8s Dungeon Crawl uses a Kubernetes cluster to simulate and manage game elements, such as monsters and players, while integrating with tools like Grafana and Prometheus for visualization and metrics. It showcases Kubernetes custom resources, controllers, and event-driven automation with integrations like RabbitMQ.
Key features of the project:
- **Game-Oriented Custom Resources**: Monsters and other in-game elements are represented as Kubernetes resources.
- **Dynamic Event Handling**: Game events, like monster creation and destruction, trigger automated infrastructure changes.
- **Observability**: Prometheus and Grafana provide insights into the game’s state, displaying metrics such as player health, dungeon level, and monster counts.
- **Cloud-Native Tools**: Integrations with RabbitMQ, NGINX, and Kubernetes controllers make this a fully cloud-native experience.
## Getting Started
### Prerequisites
To get started, ensure you have the following installed:
- **Kubernetes Cluster**: Tested with `k3d`.
- **Docker**: For building and running container images.
- **Kubebuilder**: To manage the custom controller.
- **RabbitMQ**: For event-driven communication.
- **Prometheus and Grafana**: For observability.
### Installation Steps
1. Clone the repository:
```bash
git clone https://github.com/schaeferka/k8s-dungeon-crawl.git
cd k8s-dungeon-crawl
```
2. Deploy the Kubernetes cluster and core components:
```bash
./run.sh build
```
This script:
- Sets up namespaces for the game, Prometheus, and Grafana.
- Deploys the core game logic, including the Portal and the Brogue game server.
- Configures RabbitMQ, Prometheus, and Grafana.
3. Deploy the Custom Resource Definition (CRD) and controller:
```bash
./deploy-controller.sh
```
4. Access key services:
- **noVNC Viewer**: http://localhost:8090
- **Grafana Dashboard**: http://localhost:3000
- **Prometheus UI**: http://localhost:9090
- **Portal Metrics**: http://localhost:5000/metrics
## Architecture Overview
### Core Components
#### **1. The Game Server**
The Brogue game server runs inside a container, and its visual output is accessible via noVNC. Player metrics (e.g., health, dungeon level, gold count) are sent to the Portal, which processes and exposes them as metrics.
#### **2. The Portal**
The Portal serves as the central API and event processor:
- **Metrics Exporter**: Exposes game metrics (e.g., player health, monster counts) for Prometheus to scrape.
- **Event Relay**: Sends game events (e.g., monster creation/destruction) to RabbitMQ.
#### **3. RabbitMQ**
RabbitMQ acts as the event broker, connecting the game logic (via the Portal) with the Kubernetes controller. Events like `monster created` or `monster killed` are routed to the appropriate queues.
#### **4. Custom Resources and Controller**
The `Monster` custom resource represents monsters in the game. A Kubebuilder-based controller listens to changes in these resources and manages corresponding Kubernetes resources, such as NGINX pods for each monster.
#### **5. Prometheus and Grafana**
- **Prometheus**: Scrapes metrics exposed by the Portal.
- **Grafana**: Visualizes game state metrics on a custom dashboard.
### Event Flow
1. **Monster Creation**:
- The game server generates a `monster created` event.
- The Portal sends this event to RabbitMQ.
- The Kubernetes controller processes the event, creating an NGINX pod with customized content for the monster.
2. **Monster Destruction**:
- A `monster killed` event triggers the controller to delete the corresponding NGINX pod.
### Key CRD: Monster
```yaml
apiVersion: kaschaefer.com/v1
kind: Monster
metadata:
name: goblin
spec:
type: melee
health: 100
```
This CRD defines the schema for monsters, including their type and health.
### Custom Controller Logic
The controller:
- Watches the `Monster` CRD for changes.
- Creates or deletes NGINX pods based on monster events.
- Generates ConfigMaps for NGINX `index.html` files, displaying monster-specific information.
## Observability
#### Grafana Dashboard
- Player health and gold are displayed as live metrics.
- Dungeon level and monster counts are updated in real-time.
- A noVNC panel allows direct interaction with the game.
#### Prometheus Metrics
The Portal exposes metrics in the following format:
```json
{
"gold": 50,
"health": 100,
"dungeon_level": 2,
"monster_count": 5
}
```
Prometheus scrapes this endpoint and makes the metrics available for Grafana.
## Contributions
Contributions are welcome! If you have ideas to expand the project or fix bugs, feel free to open an issue or submit a pull request.
## License
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
---
Let the dungeon crawl begin!