Getting started with the service extension

Last updated on May 3, 2024
info

Extend is in Open Beta for AGS Premium Clients! This means that the Extend add-on is available for you to try in your development environment. You can submit your feedback via our Extend Open Beta feedback form.

Overview​

This document provides a step-by-step guide on how to use Extend Service Extension.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:

    • Bash
    • Make
    • Docker v23.x
    • Go v1.20

  1. Access to the AGS demo environment.

    • Base URL: <your environment's domain URL>
      • Example for AGS Starter customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Premium customer: https://dev.customer.accelbyte.io
    • Create a game namespace if you don't have one yet. Keep the Namespace ID. Make sure your namespace is active.
    • Create an OAuth Client with confidential client type. Keep the Client ID and Client Secret. This is needed for testing the custom service locally.

  2. You have downloaded and set up the extend-helper-cli. Download here.

    • To use this tool, refer to its documentation on GitHub.
important

Create an OAuth Client with confidential client type with the following permission. Keep the Client ID and Client Secret.

  • For AGS Premium customers:
    • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
  • For AGS Starter customers:
    • Extend > Extend app image repository access (Read)

If you use extend-helper-cli v0.0.3 or lower, create a user if you don't have any with the following permission. Keep the Username and Password.

Go to the extend-helper-cli README for more details.

Download the sample app​

Clone the Service Extension sample app.

git clone https://github.com/AccelByte/extend-service-extension-go

Follow the instructions in theREADME.md file in the sample app repository. The documentation explains how we build the custom service by leveraging gRPC, gRPC-Gateway, and AGS's Cloud Save feature.

Run and test Extend app locally​

To have faster iteration on developing the Extend app, you can test it locally.

Prerequisites​

Before running the Extend app, ensure that the following conditions are met:

  • Ensure you have configured all required permissions for your OAuth client ID.

    • For AGS Premium customers:
      • ADMIN:ROLE [READ]
      • ADMIN:NAMESPACE:{namespace}:NAMESPACE [READ]
      • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE, DELETE]
    • For AGS Starter customers:
      • IAM > Roles (Read)
      • Basic > Namespace (Read)
      • Cloud Save > Game Records (Create, Read, Update, and Delete)

  • Create a Docker compose .env file by copying the content of the.env.template file.

  • Fill in the required environment variables in the .env file as shown below.

     AB_BASE_URL='http://test.accelbyte.io'     # Your environment's domain Base URL
     AB_CLIENT_ID='xxxxxxxxxx'                  # OAuth client id
     AB_CLIENT_SECRET='xxxxxxxxxx'              # OAuth client secret
     AB_NAMESPACE='xxxxxxxxxx'                  # Your game namespace
     PLUGIN_GRPC_SERVER_AUTH_ENABLED=true       # Enable or disable access token and permission verification
     BASE_PATH='/guild'                         # The base path used for the app
important

Set PLUGIN_GRPC_SERVER_AUTH_ENABLED=false to bypass validation specified for endpoint permission.action and permission.resource entry in protobuf file.

Building​

To build this sample app, use the following command.

$ make build

For more details about these commands, see the contents of the Makefile.

Running​

To run the service extension, use this command:

$ go build -o service
$ ./service
important

If you modified the contents of the protobuf files, make sure to run $ make proto before you build and run the app.

Alternatively, you can use this command to run the sample app inside a Docker.

$ docker compose up --build

Testing​

After starting the service, you can test it to make sure it's working correctly.

If PLUGIN_GRPC_SERVER_AUTH_ENABLED is true, you will need a user access token to access the REST API service. You can generate the user access token using the getusertoken.sh shell script, which is available in the repository's root directory. 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 setup section above
$ export AB_CLIENT_SECRET='xxxxxxxxxx'             # Client Secret from the setup section above

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>

To test the service, you can use a curl command. For example, to test the CreateOrUpdateGuildProgress endpoint, run:

$ curl -X 'POST' \
  'http://localhost:8000/guild/v1/admin/namespace/<your-namespace>/progress' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "guildProgress": {
    "guildId": "123456789",
    "namespace": "<your-namespace>",
    "objectives": {
      "target1": 0
    }
  }
}'
important

Make sure to fill in the accessToken and namespace accordingly and ensure that your accessToken has the admin permission as the endpoint requires admin permission ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD.

Then, to test the GetGuildProgress endpoint:

$ curl -X 'GET' \
  'http://localhost:8000/guild/v1/admin/namespace/<your-namespace>/progress/123456789' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <accessToken>'

You should see the updated guild progress in the response.

Alternatively. you can test using the service the Swagger UI.

Guild service swagger interface

If PLUGIN_GRPC_SERVER_AUTH_ENABLED is true, authorize the Swagger UI by clicking on the Authorize button.

Guild service swagger authorization

On the popup that appears, type in Bearer <user's access token> in the Value field for Bearer (apiKey). Then, click Authorize to save the user's access token.

important

If you have issues running grpc-gateway, you can test the service-extension gRPC server by accessing its gRPC port (localhost:6565) using either grpcui or Postman.

Register and integrate custom service to Extend Service Extension​

This step will create a Service Extension App that will manage your custom service.

  1. Go to the AGS Admin Portal. Hover over the left sidebar menu option Extend and click Service Extension.

    service extension configuration page in AGS Admin Portal

  2. Create the app through new app creation page. You can name the app as you prefer. In this guide, we named the app, guildservice.

    create service extension configuration in AGS Admin Portal

  3. You will see the details of your service extension app. Wait until App Repository URI is no longer blank.

    service extension created in AGS Admin Portal

Add required permission and build parameter for the custom service​

Before we build and deploy the custom service, we need to ensure that the Cloud Save permission needed by the custom service is configured.

Head to the Service Extension page, where we previously had created our Service Extension app. In this case, we named it guildservice.

service extension created in AGS Admin Portal

Now, let's note the AB_CLIENT_ID, and go to the Authorization menu to add the required permission. Use the noted client to search your auth client ID.

service extension client permission in AGS Admin Portal

Build and upload the Extend app​

After preparing our sample app and configuring all required parameters and permissions, let's build and deploy it.

First of all, we need to configure the extend-helper-cli stated in the prerequisites, since we will use it to deploy our sample app.

note

We only briefly cover how we use the extend-helper-cli in this guide. To learn more, refer to the full documentation in GitHub.


$ ./extend-helper-cli-linux_amd64 dockerlogin --namespace nngbox --app guildservice -p | docker login -u AWS --password-stdin xxxxxxxxxxxx.dkr.ecr.us-west-2.amazonaws.com/accelbyte/justice/development/extend/ext-nngbox-xxxxx/guildservice

INFO[0000] signing in to https://development.accelbyte.io 
INFO[0001] getting docker credentials...                
WARNING! Your password will be stored unencrypted in /home/xyz-abc/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

For your convenience, the above extend-helper-cli command can also be copied from Repository Authentication Command under the corresponding app detail page.

Image showing repository authentication command under admin portal

After you've successfully logged in using extend-helper-cli, let's upload the sample app.

We're using the makefile script in the sample app to upload the sample app.

make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=xxxxxxxxxxxx.dkr.ecr.us-west-2.amazonaws.com/accelbyte/justice/development/extend/ext-nngbox-xxxxx/guildservice
info

The REPO_URL can be copied from the app detail page, App Repository URI.

If your images are successfully uploaded, you will see an image with version v0.0.1 in the Image Version History.

Deploy the custom service to Extend Service Extension​

You can deploy the latest or a select image version of your custom service to the Extend Service Extension.

Image showing deploy latest image

Deploy latest image​

Click on the Deploy Latest Image button. Then, wait until the app status updates to RUNNING, which indicates that your Extend app is successfully deployed.

Image showing app is running

Deploy selected image​

  1. Click on the Image Version History button to go to the Image Version History page.

  2. Select the desired image tag, and then click Deploy Image. A confirmation pop-up appears.

    Image showing image selection and deploy

  3. To confirm, type in the version name of your selected image tag, and then click Deploy.

    Image shows the image deploy confirmation

  4. Go back to the app details page by clicking on the Cancel buton. On the app details pge, wait until the app status updates to RUNNING, which indicates that your Extend app is successfully deployed.

    Image shows the app running

Your Extend app is deployed.

important

If your Extend Service Extension app is based on sample apps before release v2024.02.13, make sure to set PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable to true. Otherwise, the access token validation in the Extend app is disabled and your Extend app may be accessed without a valid access token.

Since release v2024.02.13, the PLUGIN_GRPC_SERVER_AUTH_ENABLED in Extend Service Extension sample apps is set to true by default. The access token validation can only be disabled when PLUGIN_GRPC_SERVER_AUTH_ENABLED is explicitly set to false. To align with this, all new Extend apps created through the Admin Portal will not have PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable set by default. Previously, PLUGIN_GRPC_SERVER_AUTH_ENABLED=false is added on all new Extend apps created through admin portal.

Test the deployed Extend app​

To test the app, we can simply go to its apidocs page: <Service URL>/apidocs. Use the the Service URL shown in details page or open api documentation by clicking Open API Documentation

Image shows the Service Extension URL

Important

To avoid getting network transport error in apidocs page for deployed Extend Service Extension app, makes sure that HTTPS is selected for Schemes option.

Extend App behavior​

important

In the deployment setup, there's a timeout mechanism for the gRPC Extend app managed by Envoy. This timeout occurs when there's no incoming or outgoing data or request, which allows the system to free up resources. By default, the timeout duration is 300s for streamIdleTimeout and 30s for routeTimeout.

Last updated on

On this page