flowchart LR
subgraph AccelByte Gaming Services
CL[gRPC Client]
end
subgraph Extend Override App
SV["gRPC Server\n(you are here)"]
end
CL --- SV
AccelByte Gaming Services
(AGS) features can be customized with
Extend Override
apps. An Extend Override
app is a gRPC server
which
contains one or more custom functions which can be called by AGS
instead of the default functions.
This repository serves as a template project for an Extend Override
app for cloudsave validator
written in Python
. You can clone this repository
and start implementing custom functions which can then be called by AGS.
By using this repository as a template project, you will get the recommended authentication and authorization implemented out-of-the-box. You will also get some instrumentation for observability so that metrics, traces, and logs will be available when the app is deployed.
As an example to get you started, this template project contains sample custom functions for validating cloudsave payloads.
-
Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed.
a. Bash
bash --version GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu) ...
b. Make
- To install from Ubuntu repository, run:
sudo apt update && sudo apt install make
make --version GNU Make 4.3 ...
c. Docker (Docker Engine v23.0+)
- To install from Ubuntu repository, run:
sudo apt update && sudo apt install docker.io
- Add your user to
docker
group:sudo usermod -aG docker $USER
- Log out and log back in so that the changes take effect
docker version ... Server: Docker Desktop Engine: Version: 24.0.5 ...
d. Python 3.10
- To install from Ubuntu repository, run:
sudo apt update && sudo apt install python3 python3-venv
python3 --version Python 3.10.12
e. Curl
- To install from Ubuntu repository, run:
sudo apt update && sudo apt install curl
curl --version curl 7.81.0 (x86_64-pc-linux-gnu) ...
f. Jq
- To install from Ubuntu repository, run:
sudo apt update && sudo apt install jq
jq --version jq-1.6 ...
g. Postman
- Use binary available here
h. ngrok
- Follow installation instruction for Linux here
- To install from Ubuntu repository, run:
-
Access to AGS environment.
a. Base URL
- For
Starter
tier e.g. https://spaceshooter.prod.gamingservices.accelbyte.io - For
Premium
tier e.g. https://dev.accelbyte.io
b. Create a Game Namespace if you don't have one yet. Keep the
Namespace ID
.c. Create an OAuth Client with confidential client type. Keep the
Client ID
andClient Secret
. - For
To be able to run the sample custom functions, you will need to follow these setup steps.
-
Create a docker compose
.env
file by copying the content of .env.template file.⚠️ The host OS environment variables have higher precedence compared to.env
file variables: If the variables in.env
file do not seem to take effect properly, check if there are host OS environment variables with the same name. See documentation about docker compose environment variables precedence for more details. -
Fill in the required environment variables in
.env
file as shown below.AB_BASE_URL=https://test.accelbyte.io # Base URL of AccelByte Gaming Services environment AB_CLIENT_ID='xxxxxxxxxx' # Client ID from the Prerequisites section AB_CLIENT_SECRET='xxxxxxxxxx' # Client Secret from the Prerequisites section AB_NAMESPACE='xxxxxxxxxx' # Namespace ID from the Prerequisites section PLUGIN_GRPC_SERVER_AUTH_ENABLED=true # Enable or disable access token validation
:info: In this sample app, PLUGIN_GRPC_SERVER_AUTH_ENABLED is
true
by default: If it is set tofalse
, thegRPC server
can be invoked without AGS access token. This option is provided for development purpose only. It is recommended to enablegRPC server
access token validation in production environment.
To build this sample app, use the following command.
make build
To (build and) run this sample app in a container, use the following command.
docker compose up --build
⚠️ To perform the following, make sure PLUGIN_GRPC_SERVER_AUTH_ENABLED is set tofalse
: Otherwise, the gRPC request will be rejected by thegRPC server
.
The custom functions in this sample app can be tested locally using postman.
-
Run this
gRPC server
sample app by using the command below.docker compose up --build
-
Open
postman
, create a newgRPC request
, and enterlocalhost:6565
as server URL (tutorial here).⚠️ If you are running grpc-plugin-dependencies stack alongside this sample app as mentioned in Test Observability: Enterlocalhost:10000
instead oflocalhost:6565
. This way, thegRPC server
will be called viaEnvoy
service withingrpc-plugin-dependencies
stack instead of directly. -
Continue by selecting
CloudsaveValidatorService/BeforeWritePlayerRecord
method and invoke it with the sample message below.a. With a VALID
payload
{ "createdAt": { "nanos": 10, "seconds": "1693468029" }, "isPublic": true, "key": "favourite_weapon", "namespace": "mynamespace", "payload": "eyJ1c2VySWQiOiAiMWUwNzZiY2VlNmQxNGM4NDlmZmIxMjFjMGUwMTM1YmUiLCAiZmF2b3VyaXRlV2VhcG9uVHlwZSI6ICJTV09SRCIsICJmYXZvdXJpdGVXZWFwb24iOiAiZXhjYWxpYnVyIn0=", // {"userId": "1e076bcee6d14c849ffb121c0e0135be", "favouriteWeaponType": "SWORD", "favouriteWeapon": "excalibur"} encoded in base64 "setBy": "SERVER", "updatedAt": { "nanos": 10, "seconds": "1693468275" }, "userId": "1e076bcee6d14c849ffb121c0e0135be" }
The response will contain
isSuccess: true
{ "isSuccess": true, "key": "favourite_weapon", "userId": "1e076bcee6d14c849ffb121c0e0135be" }
b. With an INVALID
payload
{ "createdAt": { "nanos": 10, "seconds": "1693468029" }, "isPublic": true, "key": "favourite_weapon", "namespace": "mynamespace", "payload": "eyJmb28iOiJiYXIifQ==", // {"foo":"bar"} encoded in base64 "setBy": "SERVER", "updatedAt": { "nanos": 10, "seconds": "1693468275" }, "userId": "1e076bcee6d14c849ffb121c0e0135be" }
The response will contain
isSuccess: false
{ "isSuccess": false, "key": "favourite_weapon", "userId": "1e076bcee6d14c849ffb121c0e0135be", "error": { "errorCode": 1, "errorMessage": "userId cannot be empty;favouriteWeaponType cannot be empty;invalid weapon type;favouriteWeapon cannot be empty" } }
For testing this sample app which is running locally with AGS,
the gRPC server
needs to be exposed to the internet. To do this without requiring
public IP, we can use something like ngrok.
-
Run this
gRPC server
sample app by using command below.docker compose up --build
-
Sign-in/sign-up to ngrok and get your auth token in
ngrok
dashboard. -
In this sample app root directory, run the following helper command to expose
gRPC server
port in local development environment to the internet. Take a note of thengrok
forwarding URL e.g.http://0.tcp.ap.ngrok.io:xxxxx
.make ngrok NGROK_AUTHTOKEN=xxxxxxxxxxx
⚠️ If you are running grpc-plugin-dependencies stack alongside this sample app as mentioned in Test Observability: Run the above command ingrpc-plugin-dependencies
directory instead of this sample app directory. This way, thegRPC server
will be called viaEnvoy
service withingrpc-plugin-dependencies
stack instead of directly. -
Create an OAuth Client with
confidential
client type with the following permissions. Keep theClient ID
andClient Secret
.- For AGS Premium customers:
ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:PLUGINS [CREATE,READ,UPDATE,DELETE]
ADMIN:NAMESPACE:{namespace}:USER:*:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
ADMIN:NAMESPACE:{namespace}:INFORMATION:USER:* [DELETE]
- For AGS Starter customers:
- Cloud Save -> Custom Configuration (Read, Create, Update, Delete)
- Cloud Save -> Game Records (Read, Create, Update, Delete)
- Cloud Save -> Player Records (Read, Create, Update, Delete)
- IAM -> Users (Delete)
⚠️ Oauth Client created in this step is different from the one from Prerequisites section: It is required by demo.sh script in the next step to register thegRPC Server
URL and also to create and delete test users. - For AGS Premium customers:
-
Run the demo.sh script to simulate cloudsave operation which calls this sample
gRPC server
using theClient ID
andClient Secret
created in the previous step. Pay attention to samplegRPC server
console log when the script is running.gRPC Server
methods should get called.export AB_BASE_URL='https://test.accelbyte.io' export AB_CLIENT_ID='xxxxxxxxxx' # Use Client ID from the previous step export AB_CLIENT_SECRET='xxxxxxxxxx' # Use Client Secret from the previous step export AB_NAMESPACE='accelbyte' # Use your Namespace ID export GRPC_SERVER_URL='0.tcp.ap.ngrok.io:xxxxx' # Use your ngrok forwarding URL bash demo.sh
⚠️ Make sure demo.sh has Unix line-endings (LF): If this repository was cloned in Windows for example, thedemo.sh
may have Windows line-endings (CRLF) instead. In this case, use tools likedos2unix
to change the line-endings to Unix (LF). Invalid line-endings may cause errors such asdemo.sh: line 2: $'\r': command not found
.
⚠️ Ngrok free plan has some limitations: You may want to use paid plan if the traffic is high.
To be able to see the how the observability works in this sample app locally, there are few things that need be setup before performing tests.
-
Uncomment loki logging driver in docker-compose.yaml
# logging: # driver: loki # options: # loki-url: http://host.docker.internal:3100/loki/api/v1/push # mode: non-blocking # max-buffer-size: 4m # loki-retries: "3"
⚠️ Make sure to install docker loki plugin beforehand: Otherwise, this sample app will not be able to run. This is required so that container logs can flow to theloki
service withingrpc-plugin-dependencies
stack. Use this command to install docker loki plugin:docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions
. -
Clone and run grpc-plugin-dependencies stack alongside this sample app. After this, Grafana will be accessible at http://localhost:3000.
git clone https://github.com/AccelByte/grpc-plugin-dependencies.git cd grpc-plugin-dependencies docker-compose up
❗ More information about grpc-plugin-dependencies is available here.
-
Perform testing. For example, by following Test in Local Development Environment or Test with AccelByte Gaming Services.
After done testing, you may want to deploy this app to AccelByte Gaming Services
.
-
Create a new Extend Override App on Admin Portal. Keep the
Repository URI
. -
Download and setup extend-helper-cli (only if it has not been done previously).
-
Perform docker login with
extend-helper-cli
using the following command.extend-helper-cli dockerlogin --namespace <my-game> --app <my-app> --login
❗ For your convenience, the above
extend-helper-cli
command can also be copied fromRepository Authentication Command
under the corresponding app detail page. -
Build and push sample app docker image to AccelByte ECR using the following command.
make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=xxxxxxxxxx.dkr.ecr.us-west-2.amazonaws.com/accelbyte/justice/development/extend/xxxxxxxxxx/xxxxxxxxxx
❗ The REPO_URL is obtained from step 1: It can be found under 'Repository URI' in the app detail.
-
Open Admin Portal, go to Extend -> Overridable Features. And then select the extend app.
-
To deploy selected image tag, click Image Version History and select desired image tag to be deployed.
-
Click Deploy Image, confirm the deployment and go back to App Detail by clicking Cancel.
-
Wait until app status is running.
Proceed to modify this template project and implement your own custom functions.