flowchart LR
CL[Game Client]
subgraph "Extend Service Extension App (you are here)"
GW["gRPC Gateway"]
SV["gRPC Server"]
end
CL --- GW
GW --- SV
AccelByte Gaming Services
(AGS) capabilities can be extended with
Extend Service Extension
apps. An Extend Service Extension
app is
essentially a custom REST API service built using a combination of
gRPC Gateway and gRPC Server.
This repository serves as a template project for an Extend Service Extension
app written in Java
. You can clone this repository and start creating
endpoints by editing the gRPC proto file and implementing your own logic.
By using this repository as a template project, you will get basic 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. Since the source code is included, you can customize them according to your needs.
As an example to get you started, this template project contains a sample custom guild service which has two endpoints to create and get guild progress data.
-
Windows 11 WSL2 or Linux Ubuntu 22.04 with the following 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. JDK 17
- To install from Ubuntu repository, run:
sudo apt update && sudo apt install openjdk-17-jdk
java --version openjdk 17.0.10 2024-01-16 ...
- 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 with the following permissions. Keep the
Client ID
andClient Secret
.- For AGS Premium customers:
ADMIN:ROLE [READ]
to validate access token and permissionsADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
to create, read, update, and delete cloudsave records
- For AGS Starter customers:
- IAM -> Roles (Read)
- Cloud Save -> Game Records (Create, Read, Update, Delete)
- For
To be able to run the sample custom guild service, 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 demo 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 and permission validation BASE_PATH='/guild' # The base path used for the app
:info: In this sample app, PLUGIN_GRPC_SERVER_AUTH_ENABLED is
true
by default: If it is set tofalse
, the endpointpermission.action
andpermission.resource
validation will be disabled and the endpoint can be accessed without a valid access token. This option is provided for development purpose only. For more information, see creating-new-endpoint.
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
The sample custom guild service included in this template project can be tested locally using Swagger UI.
-
Run this
Extend Service Extension
sample app by using the command below.docker compose up --build
-
If PLUGIN_GRPC_SERVER_AUTH_ENABLED is
true
, you will need the a user access token to access the REST API service. You can generate the user access token using getusertoken.sh shell script. To run it, you will need to set the following environment variables.export AB_BASE_URL='http://test.accelbyte.io' # Your environment's domain Base URL export AB_CLIENT_ID='xxxxxxxxxx' # Client ID from the Prerequisites section export AB_CLIENT_SECRET='xxxxxxxxxx' # Client Secret from the Prerequisites section
Then use the following command to run the script to get the user access token.
# The <username> and <password> are the user's credential to access AGS. bash getusertoken.sh <username> <password>
:info: Make sure the user has a role which contains this permission:
ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE,DELETE]
. -
The REST API service can then be tested by opening Swagger UI at
http://localhost:8000/guild/apidocs/
. Use this to create an API request to try the endpoints.:info: Depending on the envar you set for
BASE_PATH
, the service will have different service URL. This how it's the formattedhttp://localhost:8000/<base_path>
To authorize Swagger UI, click on "Authorize" button on right side.
Popup will show, input "Bearer <user's access token>" in
Value
field forBearer (apiKey)
. Then click "Authorize" to save the user's access token.
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.
To deploy this app to AGS, follow the steps below.
-
Create a new Extend Service Extension 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 -> Service Extension. 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.
For more information on how to deploy an Extend Service Extension
app, see
here.
Proceed to modify this template project and create your own endpoints. See here for more details.