Getting started with the service extension

Last updated on December 18, 2023
note

Extend is in Open Beta for AGS Premium Clients! This means that Extend is available for you to try on your development environment. You can submit your feedback here.

note

Extend is currently available for AGS Starter Closed Beta partners only.

Overview​

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

Prerequisites​

  1. Windows 10 WSL2 or Linux Ubuntu 20.04 with the following tools installed:

    • Make
    • Docker v23.x
    • docker-compose v2
    • Go v1.20

  1. Access to the AGS demo environment.

  2. The extend-helper-cli downloaded, installed, and set up. Download here.

important

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

  • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [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.

  • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]

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.

Important

This step is mandatory, since you will need to add additional permission to the Client ID you're using:

  • ADMIN:ROLE [READ]
  • ADMIN:ROLE [READ]
  • ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE,READ,UPDATE, DELETE]

Run and test Extend app locally​

To have faster iteration on developing the Extend app, you can test it locally. Ensure your client id for local testing already have all the required permission.

For more details, please refer to the README.md especially in the section Running and Testing the Service.

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 URL 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 are 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

After the permission is added, we need to adjust the base path in the custom service.

To change the base path you need to replace the values in 2 places. You get the base value from Service URL. For example, this Service URL, https://development.accelbyte.io/nngbox-guildservice, will have the base path /nngbox-guildservice.

  • in pkg/common/config.go, to be accurately this part

    BasePath    = "/guild"

  • in pkg/proto/guildService.proto

    // OpenAPI options for the entire API.
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
      // ...
      
      base_path: "/guild";
      
      // ...
    };

For more details, please refer to the Change API base path section in the README.md file in the custom service repository.

Important

Changing API base path is a mandatory step.

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, please refer to the full documentation in GitHub.


$ ./extend-helper-cli-linux_amd64 dockerlogin --namespace nngbox --app guildservice -p | docker login -u AWS --password-stdin 3342674635073.dkr.ecr.us-west-2.amazonaws.com/accelbyte/justice/development/extend/ext-nngbox-ewo48/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

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=342674635073.dkr.ecr.us-west-2.amazonaws.com/accelbyte/justice/development/extend/ext-nngbox-ewo48/guildservice
info

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

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​

To deploy the Extend app, simply click Deploy Latest Image.

Important

Ensure the environment variable PLUGIN_GRPC_SERVER_AUTH_ENABLED is set to true, otherwise the endpoint validation (permission.action and permission.resource) configured in the guildService.proto will be ignored

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.

For more details, please refer to the Running and Testing the Service section in the README.md file in the custom service sample app repository.

A note on 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/outgoing data or request, allowing 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