Extend Helper CLI

Last updated on December 12, 2024

Introduction

The Extend Helper CLI lets you create, deploy, and manage Extend app containers on the AccelByte Gaming Services (AGS) platform, streamlining your development workflow.

This article walks you through how to install and use the Extend Helper CLI to manage your Extend apps in your development environment.

Prerequisites

1. Docker (Docker Desktop 4.30+ / Docker Engine v23.0+)

   • For Linux:

     1. To install from the Ubuntu repository, run sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2.

     2. Add your user to the docker group: sudo usermod -aG docker $USER.

     3. Log out and log back in to allow the changes to take effect.

   • For Windows/macOS:

     Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.

     docker version
     
     ...
     Server: Docker Desktop
        Engine:
        Version:          24.0.5

2. Access to AGS environment. Take note of the Base URL.

   • Example for AGS Shared Cloud: https://spaceshooter.prod.gamingservices.accelbyte.io

   • Example for AGS Private Cloud: https://dev.customer.accelbyte.io

3. Create an OAuth Client with confidential client type with the following permission. Write down the Client ID and Client Secret.

Installation

1. Go to the Extend Helper CLI GitHub page to download the latest executable for your operating system.

2. Once downloaded, you can run the executable directly from your terminal.

3. You may have to add in the execution permission to the executable.

   • For Linux:

     chmod +x extend-helper-cli-<variant>

   • For macOS:

     chmod +x extend-helper-cli-<variant>

     You may still be blocked by the OS even after executing chmod +x and will be required to override security settings. For troubleshooting information, refer to Apple's Mac User Guide.

   • For Windows:

     icalcs extend-helper-cli-<variant> /grant <your-username>:F

Setup

To use extend-helper-cli, you will need to configure environment variables for your AGS environment. You can do this by either creating an .env file or exporting the variables directly.

Option 1: Use an .env file

1. In the same directory as the extend-helper-cli executable, create a file named .env.

2. Add the following lines to the .env file, replacing the placeholder values with your actual credentials:

   AB_BASE_URL=<your_base_url>
   AB_CLIENT_ID=<your_client_id>
   AB_CLIENT_SECRET=<your_client_secret>

Option 2: Export environment variables

Export the values directly from your terminal:

export AB_BASE_URL=<your_base_url>
export AB_CLIENT_ID=<your_client_id>
export AB_CLIENT_SECRET=<your_client_secret>

With the environment variables set, extend-helper-cli is now ready to use.

Usage

To view the available commands for the Extend Helper CLI, run this command:

extend-helper-cli help

Extend Helper CLI help information:

NAME:
   extend-helper-cli - AccelByte Docker Image Upload Helper CLI Tool (Default Base URL: https://dev.customer.accelbyte.io)

USAGE:
   extend-helper-cli [global options] command [command options] [arguments...]

COMMANDS:
   dockerlogin    Generate docker login credentials.
   image-upload   Build and upload a docker image.
   get-app-info   Get app information.
   <more...>
   help, h        Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

Create an Extend app

Use the create-app command to create an Extend app.

extend-helper-cli create-app --namespace <my-game-namespace> --app <my-extend-app> --scenario service-extension --confirm

Sample response

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "",
  "appRepoUrl": "",
  "basePath": "xxx-xxxx-xxxx",
  "CPU": {
    "cpuLimit": 1550,
    "requestCPU": 1000
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "deletedAt": "",
  "deploymentCreatedAt": "",
  "deploymentId": "",
  "deploymentImageTag": "",
  "memory": {
    "memoryLimit": 3300,
    "requestMemory": 350
  },
  "message": "",
  "replica": {
    "maxReplica": 10,
    "minReplica": 1,
    "replicaLimit": 60
  },
  "scenario": "service-extension",
  "servicePublicURL": "https://xxxx.accelbyte.io/xxx-xxxx-xxxx",
  "serviceURL": "",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

You can use --wait with --wait-interval <seconds> (default: 10) and --wait-limit <seconds> (default: 300) to wait until the app is ready for image upload or deployment.

extend-helper-cli create-app --namespace <my-game-namespace> --app <my-extend-app> --scenario service-extension --confirm --wait

Get Extend app information

Use the get-app-info command to get a specific Extend app information:

extend-helper-cli get-app-info --namespace <my-game-namespace> --app <my-extend-app>

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "arn:aws:ecr:xxxxxxxxx:xxxxxxxxxxxx:xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appRepoUrl": "xxxx.xxxx.xxxx.xxxxxxxxx.xxxx.xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appStatus": "app-undeployed",
  "app_release_status": "U",
  "basePath": "xxx-xxxx-xxxx",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "scenario": "service-extension",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

If you only need to query a specific field, use --path and pass in a valid JSON pointer.

For example, to get the appName only:

extend-helper-cli get-app-info --namespace <my-game-namespace> --app <my-extend-app> --path /appName

Another example, to get appRepoUrl only:

extend-helper-cli get-app-info --namespace <my-game-namespace> --app <my-extend-app> --path /appRepoUrl

Getting credentials to push an Extend app container image

Use the dockerlogin command to get the required credentials to push an Extend app container image.

extend-helper-cli dockerlogin --namespace <my-game-namespace> --app <my-extend-app> --login

Sample response

INFO[0000] signing in to https://dev.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

danger

The credentials can be used only for a specific game namespace and Extend app. For different game namespace and Extend app, you will need to use this command again.

Push an Extend app container image

The image-upload command enables you to build your Extend app container image, tag it, and push it to the Extend app container registry.

extend-helper-cli image-upload --namespace <my-game-namespace> --app <my-extend-app>
    --image-tag v1.0.0
    --work-dir <path-to-directory-containing-service-dockerfile>

You can also use the --login flag to automatically execute dockerlogin beforehand so that you do not have to execute it separately.

extend-helper-cli image-upload --namespace <my-game-namespace> --app <my-extend-app>
    --image-tag v1.0.0
    --work-dir <path-to-directory-containing-service-dockerfile>
    --login

If the upload fails, you can use --retry-limit with --retry-interval <seconds> (default: 1.0) and --retry-rate <seconds> (default: 2.0) to retry.

extend-helper-cli image-upload --namespace <my-game-namespace> --app <my-extend-app>
    --image-tag v1.0.0
    --work-dir <path-to-directory-containing-service-dockerfile>
    --retry-limit 3

Create and update Extend app environment variables and secrets

Use the update-var command to create new or modify existing Extend app environment variables.

extend-helper-cli update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100

Use the update-secret command to create new or modify existing Extend app environment secrets.

extend-helper-cli update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key>

You can also add --force to force the command to create the variable or secret if it does not exist yet.

For environment variables:

extend-helper-cli update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100
    --wait

For environment secrets:

extend-helper-cli update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key>
    --wait

Deploy an Extend app

Use the deploy-app command to create a deployment for an Extend app.

extend-helper-cli deploy-app --namespace <my-game-namespace> --app <my-extend-app> --image-tag v1.0.0

Sample response

{
  "deploymentId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

You can also add --wait (and --wait-interval <duration-in-seconds:10>, --wait-limit <duration-in-seconds:300>) to wait for the app to finish deployment.

extend-helper-cli deploy-app --namespace <my-game-namespace> --app <my-extend-app> --image-tag v1.0.0 --wait

Start and stop an Extend app

Use the start-app or stop-app command to start or stop an Extend app.

extend-helper-cli start-app --namespace <my-game-namespace> --app <my-extend-app>

extend-helper-cli stop-app --namespace <my-game-namespace> --app <my-extend-app>

You can use --wait with --wait-interval <seconds> (default: 10) and --wait-limit <seconds> (default: 300) to wait until the app is ready to be started or stopped.

To start an Extend app with a wait time:

extend-helper-cli start-app --namespace <my-game-namespace> --app <my-extend-app>
    --wait

To stop an Extend app with a wait time:

extend-helper-cli stop-app --namespace <my-game-namespace> --app <my-extend-app>
    --wait

Delete an Extend app

Use the delete-app command to delete an Extend app.

extend-helper-cli delete-app --namespace <my-game-namespace> --app <my-extend-app> --confirm

You can use --wait with --wait-interval <seconds> (default: 10) and --wait-limit <seconds> (default: 300) to wait until the app is ready to be deleted.

extend-helper-cli delete-app --namespace <my-game-namespace> --app <my-extend-app> --confirm
    --wait

Troubleshooting

This section contains troubleshooting information for possible issues you may encounter when developing an Extend app.

Docker login fails

Pushing an Extend app container image to AGS using Extend Helper CLI, the extend-helper-cli dockerlogin ... command returns the following error:

Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

This issue may be due to the token size being larger than most credential managers can handle. For more information, see Docker's ticket for this issue.

The workaround for this issue depends on your operating system.

Linux

1. Remove "credsStore": "desktop.exe" from $HOME/.docker/config.json.

2. Try extend-helper-cli dockerlogin ... command again.

Windows (WSL2)

1. In Windows file system:

   • Remove "credsStore": "desktop.exe" from %USERPROFILE%\.docker\config.json.
   • Rename the following files in C:\Program Files\Docker\Docker\resources\bin.
     • docker-credential-desktop.exe to docker-credential-desktop.exe.old
     • docker-credential-wincred.exe to docker-credential-wincred.exe.old

2. In WSL2 file system:

   • Remove "credsStore": "desktop.exe" from $HOME/.docker/config.json.

3. Try extend-helper-cli dockerlogin ... command again.

note

You may have to periodically apply this workaround. As of this article's update date, Docker has a known issue of restoring "credsStore": "desktop" in the config.json file when it is restarted. For more information, see Docker's ticket for this issue.