graham/aprs.me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update CLAUDE.md with StatefulSet clustering documentation

Browse source 
- Document StatefulSet deployment structure
- Update kubectl commands for StatefulSet
- Add clustering architecture details
- Include cluster configuration environment variables

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Graham McIntire 2025-07-25 12:25:31 -05:00
parent 620144164f
commit dee204202a
No known key found for this signature in database
1 changed files with 19 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
CLAUDE.md
View file

@ -127,7 +127,8 @@ The application supports Kubernetes deployment with manifests in `k8s/` director
The app is deployed in a k3s cluster with the following structure: The app is deployed in a k3s cluster with the following structure:
- **App name**: `aprs` - **App name**: `aprs`
- **Namespace**: `aprs` - **Namespace**: `aprs`
- **K8s manifests location**: `~/dev/infra/clusters/aprs/` - **Deployment**: StatefulSet with 2 replicas
- **Manifests**: Located in `~/dev/infra/clusters/aprs/`
Common kubectl commands for debugging: Common kubectl commands for debugging:
```bash ```bash
@ -143,14 +144,14 @@ kubectl logs <pod-name> -n aprs
# Describe pod for events and details # Describe pod for events and details
kubectl describe pod <pod-name> -n aprs kubectl describe pod <pod-name> -n aprs
# Restart the deployment # Restart the statefulset
kubectl rollout restart deployment/aprs -n aprs kubectl rollout restart statefulset/aprs -n aprs
# Check deployment status # Check statefulset status
kubectl rollout status deployment/aprs -n aprs kubectl rollout status statefulset/aprs -n aprs
# Execute commands in the pod # Execute commands in the pod (StatefulSet)
kubectl exec -it deployment/aprs -n aprs -- /app/bin/aprsme remote kubectl exec -it aprs-0 -n aprs -- /app/bin/aprsme remote
# Check cluster membership # Check cluster membership
kubectl exec -it <pod-name> -n aprs -- /app/bin/aprsme eval "Node.list()" kubectl exec -it <pod-name> -n aprs -- /app/bin/aprsme eval "Node.list()"
@ -163,19 +164,25 @@ kubectl exec -it <pod-name> -n aprs -- /app/bin/aprsme eval "Aprsme.Cluster.Lead
The application uses distributed Erlang clustering to ensure only one APRS-IS connection across multiple replicas: The application uses distributed Erlang clustering to ensure only one APRS-IS connection across multiple replicas:
1. **Leader Election**: Uses `:global` registry for distributed leader election 1. **StatefulSet Deployment**:
- Uses Kubernetes StatefulSet for stable pod names (aprs-0, aprs-1, etc.)
- Headless service provides DNS entries for each pod
- Stable network identities enable Erlang distribution
2. **Leader Election**: Uses `:global` registry for distributed leader election
- Only the elected leader maintains the APRS-IS connection - Only the elected leader maintains the APRS-IS connection
- Automatic failover when leader goes down - Automatic failover when leader goes down
- Leader election managed by `Aprsme.Cluster.LeaderElection` - Leader election managed by `Aprsme.Cluster.LeaderElection`
2. **Connection Management**: 3. **Connection Management**:
- `Aprsme.Cluster.ConnectionManager` starts/stops APRS-IS based on leadership - `Aprsme.Cluster.ConnectionManager` starts/stops APRS-IS based on leadership
- Uses `DynamicSupervisor` to manage connection lifecycle - Uses `DynamicSupervisor` to manage connection lifecycle
- Prevents duplicate connections and packet processing - Prevents duplicate connections and packet processing
3. **Kubernetes Configuration**: 4. **Cluster Configuration**:
- Headless service (`aprs-headless`) for node discovery - Uses `libcluster` with Kubernetes.DNS strategy
- DNS-based clustering via libcluster - Automatic node discovery via headless service
- Erlang cookie configured via RELEASE_COOKIE environment variable
- Environment variables: - Environment variables:
- `CLUSTER_ENABLED=true` - Enables clustering - `CLUSTER_ENABLED=true` - Enables clustering
- `RELEASE_NODE` - Erlang node name - `RELEASE_NODE` - Erlang node name