Orchestrator V2 Migration Guide

what's new? 🚀 we're excited to announce our completely rebuilt orchestration platform! after months of development and successful testing with our larger customers, v2 brings significant improvements to every aspect of our service performance & reliability performance tested with hundreds of session run requests per second, a major leap forward in throughput reliability improved reliability of session operations, more graceful handling of edge cases leading to a reduced number of errors scalability better horizontal scaling capabilities to handle your growing needs maintainability rebuilt from the ground up, making it easier for us to add features and respond to your needs new features enhanced session management new filtering options and detailed container states improved error handling detailed error responses with correlation ids for better debugging aws aligned regions standardized region names for better geographical understanding resolved port conflicts new dedicated port range for more reliable game server startup build verification new endpoint to check if your builds are ready in specific regions better logging elastic based solution for real time log access and analysis making the switch quick start contact our support team to receive your v2 credentials and endpoints update your integration with the new endpoints add a new webhook for your repositories in dockerhub pointing to the url we'll provide test your integration in the sandbox environment first 💡 good news v2 maintains backwards compatibility with v1's api contract, making migration straightforward you can migrate at your own pace, and your existing integrations will continue to work infrastructure changes v2 runs on a separate infrastructure from v1, allowing for a smooth transition period this separation ensures stability during migration and lets you test v2 thoroughly before fully switching over key changes region names we've simplified our infrastructure model to align with industry standards now using aws aligned region names (e g , eu west 1 , us east 1 ) the location field in post /session only accepts these standardized region names this change brings several benefits clearer geographic understanding of where your servers are deployed consistency with widely used cloud infrastructure naming simplified latency calculations and region selection the get /available location endpoint has been updated to reflect these changes now returns only region information each region includes a single pingable ip for latency testing example response { "locations" \[ { "id" "eu west 1", "ips" \["{{ipv4 address}}"] }, { "id" "eu central 1", "ips" \["{{ipv4 address}}"] } ] } port range update we've resolved a long standing issue with port conflicts previous range 32768 60999 caused conflicts with linux kernel's ephemeral port range led to occasional game server startup failures new range 20000 30000 eliminates port conflicts entirely provides dedicated range for game servers improves reliability of server startup session management updates deprecated features we've made changes to simplify the platform ❌ advantages field (removed) completely removed from the api replaced by our improved region based deployment model new session list features the enhanced get /session endpoint now provides more control and visibility new query parameters parameter description all include non running sessions in the results filternot ✨ new! exclude sessions matching specific criteria new response fields field description tag build tag of the container image status container state (see states table below) container states status description created initial container creation running actively running and healthy restarting currently restarting exited gracefully stopped dead terminated unexpectedly draining preparing for shutdown shuttingdown currently shutting down server unreachable host communication lost filtering capabilities include filter ( filter ) get /session?filter\[region]=eu west 1\&filter\[tag]=latest returns sessions matching all specified criteria new! exclude filter ( filternot ) get /session?filternot\[status]=exited\&filternot\[tag]=beta a powerful new way to exclude sessions that match specific criteria this complements the existing filter parameter by allowing you to define what you don't want to see in the results historical sessions ( all ) get /session?all=true include non running sessions (like exited ones) in the results you can combine these filters for precise querying get /session?all=true\&filter\[region]=eu west 1\&filternot\[status]=dead this would return all sessions (including exited ones) in eu west 1, excluding dead sessions session creation enhancements we've made improvements to the session creation process optional session id the id field in post /session is now optional you can provide your own uuid or let the system generate one system generated ids use google's rfc4122 compliant implementation provides flexibility while maintaining unique identification improved error handling we've completely revamped our error reporting to help you quickly identify and resolve issues { "statuscode" 404, "code" "resource not found", "message" "unable to start session ", "details" "please make sure the correct image is specified ", "identifier" "3bc545b7 4750 47e6 a918 c93debc58663", "path" "/session", "timestamp" "2025 01 16t07 51 49z" } 🔍 tip always include the identifier when contacting support about errors this helps us quickly trace the exact issue in our systems logging changes we've enhanced our logging system with robust new capabilities available logging options use our elastic based solution real time log access advanced search capabilities contact support for access session logs api endpoint standard access to container logs streaming capabilities build tag verification we've added a new endpoint to help you verify when your builds are ready to use in our fleet get /tag/{region}/{image}/{version} this endpoint lets you check if a specific version of your game server is available in a region before attempting to use it parameters region the aws region name (e g , eu west 1 ) image your game server image name version the docker tag of your build response returns {"exists" true} if the build is ready to use use cases verify builds are propagated before deployment validate ci/cd pipelines troubleshoot missing or failed builds example request curl h 'authorization bearer {{api token}}' \\ https //api {{domain}}/tag/eu west 1/my game server/1 0 0 example responses success build is available { "exists" true } build not found { "statuscode" 404, "code" "resource not found", "message" "image not found or you are not authorized to use this image ", "details" "please verify the image name and tag are correct ", "identifier" "3bc545b7 4750 47e6 a918 c93debc58663", "path" "/tag/eu west 1/my game server/1 0 0", "timestamp" "2025 01 16t07 51 49z" } coming soon we're actively working on exciting new features v2 api with improved naming conventions sidecar support for auxiliary services lifecycle webhooks for better integration container draining tracking for graceful shutdowns enhanced monitoring and metrics self service admin dashboard (planned for 2025) need help? our technical support team is ready to assist with your migration get help with migration planning troubleshoot integration issues access to our elastic logging solution best practices consultation contact us if you have any questions or need guidance we're committed to making your migration to v2 as smooth as possible