@metaplay/metaplay-auth 1.2.1 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.4.1] - 2024-04-24
+
+### Added
+
+* New command `deploy-server` which deploys a given docker image to the target environment, including support for auto-detecting default Helm chart repository and version from the built image's labels.
+* New command `push-docker-image` which pushes the built docker image into the target environment's image repository.
+* New command `check-server-status [gameserver]` which replaces the old `check-deployment [namespace]`
+* Allow writing the kubeconfig from `get-kubeconfig` command directly into a file with `metaplay-auth get-kubeconfig --output /path/to/kubeconfig`.
+
+### Changed
+
+* The `get-kubeconfig` command now defaults to generating a dynamic `kubeconfig` for human users. This means that the credentials are resolved on each time the `kubeconfig` is used. Thus, the `kubeconfig` stays valid as long as the `metaplay-auth` session is valid. Machine users still default to a static `kubeconfig` with the secret embedded.
+* The `check-deployment` command is now considered deprecated. Use the `check-server-status [gameserver]` instead.
+
+### Fixed
+
+* Many improvements to the game server status check logic: support multi-pod deployments, fix multiple bugs, make progress reporting less noisy and improve error messages.
+
+## [1.3.0] - 2024-04-18
+
+### Added
+
+* Introduce new option `-t dynamic` for `metaplay-auth get-kubeconfig` that generates a `kubeconfig` which invokes the `metaplay-auth` itself to get the credentials. This way, the `kubeconfig` is longer-lived and no longer contains the sensitive access token.
+* Support specifying target environment/gameserver address using the format '\<organization\>-\<project\>-\<environment\>', e.g., `metaplay-auth get-environment metaplay-idler-develop`.
+
+### Changed
+
+* The `kubeconfig` files generated default to the environment's namespace so it doesn't need to be specified manually. The cluster, user, and context names were changed to be more meaningful.
+
 ## [1.2.1] - 2024-04-05
 
 ### Changed

package/README.md

@@ -20,48 +20,6 @@ npx @metaplay/metaplay-auth@latest show-tokens
 npx @metaplay/metaplay-auth@latest logout
 ```
 
-## Running locally
-
-When making changes to the `metaplay-auth`, it's easiest to test by running it locally:
-
-```bash
-AuthCLI$ pnpm dev login
-AuthCLI$ pnpm dev show-tokens
-```
-
-## Building from sources
-
-The tool is also provided as part of the Metaplay SDK package (available via the [Metaplay Portal](https://portal.metaplay.dev/) under `AuthCLI/` and utilizes the same TypeScript toolchains as other components in the Metaplay SDK.
-
-You can build the tool using [Moon](https://www.npmjs.com/package/@moonrepo/cli):
-
-```bash
-AuthCLI$ moon run build
-```
-
-Now, you can run the application with node:
-
-```bash
-AuthCLI$ node dist/index.js
-Usage: metaplay-auth [options] [command]
-
-Authenticate with Metaplay and get AWS and Kubernetes credentials for game servers.
-
-Options:
-  -V, --version                               output the version number
-  -d, --debug                                 enable debug output
-  -h, --help                                  display help for command
-
-Commands:
-  login                                       login to your Metaplay account
-  logout                                      log out of your Metaplay account
-  show-tokens                                 show loaded tokens
-  get-kubeconfig [options] [gameserver]       get kubeconfig for deployment
-  get-aws-credentials [options] [gameserver]  get AWS credentials for deployment
-  get-environment [options] [gameserver]      get environment details for deployment
-  help [command]                              display help for command
-```
-
 ## License
 
 See the LICENSE file.

package/dist/index.js

@@ -1,16 +1,51 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import Docker from 'dockerode';
 import { loginAndSaveTokens, machineLoginAndSaveTokens, extendCurrentSession, loadTokens, removeTokens } from './src/auth.js';
 import { StackAPI } from './src/stackapi.js';
 import { checkGameServerDeployment } from './src/deployment.js';
 import { logger, setLogLevel } from './src/logging.js';
+import { isValidFQDN, executeCommand } from './src/utils.js';
 import { exit } from 'process';
 import { ECRClient, GetAuthorizationTokenCommand } from '@aws-sdk/client-ecr';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+import { writeFile, unlink } from 'fs/promises';
+import { existsSync } from 'fs';
+import { KubeConfig } from '@kubernetes/client-node';
+import * as semver from 'semver';
+/**
+ * Helper for parsing the GameserverId type from the command line arguments. Accepts either the gameserver address
+ * (idler-test.p1.metaplay.io), a shorthand address (metaplay-idler-test) or the (organization, project, environment)
+ * tuple from options.
+ */
+function resolveGameserverId(address, options) {
+    // If address is specified, use it, otherwise assume options has organization, project, and environment
+    if (address) {
+        if (isValidFQDN(address)) {
+            return { gameserver: address };
+        }
+        else {
+            const parts = address.split('-');
+            if (parts.length !== 3) {
+                throw new Error('Invalid gameserver address syntax: specify either <organization>-<project>-<environment> or a fully-qualified domain name (eg, idler-develop.p1.metaplay.io)');
+            }
+            return { organization: parts[0], project: parts[1], environment: parts[2] };
+        }
+    }
+    else if (options.organization && options.project && options.environment) {
+        return { organization: options.organization, project: options.project, environment: options.environment };
+    }
+    else {
+        throw new Error('Could not determine target environment from arguments: You need to specify either a gameserver address or an organization, project, and environment. Run this command with --help flag for more information.');
+    }
+}
 const program = new Command();
 program
     .name('metaplay-auth')
     .description('Authenticate with Metaplay and get AWS and Kubernetes credentials for game servers.')
-    .version('1.2.1')
+    .version('1.4.1')
     .option('-d, --debug', 'enable debug output')
     .hook('preAction', (thisCommand) => {
     // Handle debug flag for all commands.
@@ -88,39 +123,91 @@ program.command('show-tokens')
     }
 });
 program.command('get-kubeconfig')
-    .description('get kubeconfig for deployment')
-    .argument('[gameserver]', 'address of gameserver (e.g. idler-develop.p1.metaplay.io)')
+    .description('get kubeconfig for target environment')
+    .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
     .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
     .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
     .option('-p, --project <project>', 'project name (e.g. idler)')
     .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+    .option('-t, --type <credentials-type>', 'type of credentials handling in kubeconfig (static or dynamic)')
+    .option('--output <kubeconfig-path>', 'path of the output file where to write kubeconfig (written to stdout if not specified)')
     .hook('preAction', async () => {
     await extendCurrentSession();
 })
     .action(async (gameserver, options) => {
     try {
         const tokens = await loadTokens();
-        if (!gameserver && !(options.organization && options.project && options.environment)) {
-            throw new Error('Could not determine a deployment to fetch the KubeConfigs from. You need to specify either a gameserver or an organization, project, and environment. Run this command with --help flag for more information.');
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
+        // Default to credentialsType==dynamic for human users, and credentialsType==static for machine users
+        const isHumanUser = !!tokens.refresh_token;
+        const credentialsType = options.credentialsType ?? (isHumanUser ? 'dynamic' : 'static');
+        // Generate kubeconfig
+        let kubeconfigPayload;
+        if (credentialsType === 'dynamic') {
+            logger.debug('Fetching kubeconfig with execcredential');
+            kubeconfigPayload = await stackApi.getKubeConfigExecCredential(gameserverId);
+        }
+        else if (credentialsType === 'static') {
+            logger.debug('Fetching kubeconfig with embedded secret');
+            kubeconfigPayload = await stackApi.getKubeConfig(gameserverId);
         }
-        const stackApi = new StackAPI(tokens.access_token);
-        if (options.stackApi) {
-            stackApi.stack_api_base_uri = options.stackApi;
+        else {
+            throw new Error('Invalid credentials type; must be either "static" or "dynamic"');
+        }
+        // Write kubeconfig to output (file or stdout)
+        if (options.output) {
+            logger.debug(`Writing kubeconfig to file ${options.output}`);
+            await writeFile(options.output, kubeconfigPayload, { mode: 0o600 });
+            console.log(`Wrote kubeconfig to ${options.output}`);
+        }
+        else {
+            console.log(kubeconfigPayload);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error('Error getting KubeConfig:', error);
         }
-        const payload = gameserver ? { gameserver } : { organization: options.organization, project: options.project, environment: options.environment };
-        const credentials = await stackApi.getKubeConfig(payload);
+        exit(1);
+    }
+});
+/**
+ * Get the Kubernetes credentials in the execcredential format which can be used within the `kubeconfig` file:
+ * The kubeconfig can invoke this command to fetch the Kubernetes credentials just-in-time which allows us to
+ * generate kubeconfig files that don't contain access tokens and are longer-lived (the authentication is the
+ * same as that of metaplay-auth itself). Use `metaplay-auth get-kubeconfig -t dynamic ...` to create a
+ * kubeconfig that uses this command.
+ */
+// todo: maybe this should be a hidden command as it's not very useful for end users and clutters help?
+program.command('get-kubernetes-execcredential')
+    .description('[internal] get kubernetes credentials in execcredential format (used from the generated kubeconfigs)')
+    .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
+    .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
+    .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
+    .option('-p, --project <project>', 'project name (e.g. idler)')
+    .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+    .hook('preAction', async () => {
+    await extendCurrentSession();
+})
+    .action(async (gameserver, options) => {
+    try {
+        const tokens = await loadTokens();
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
+        const credentials = await stackApi.getKubeExecCredential(gameserverId);
         console.log(credentials);
     }
     catch (error) {
         if (error instanceof Error) {
-            console.error(`Error getting KubeConfig: ${error.message}`);
+            console.error(`Error getting Kubernetes ExecCredential: ${error.message}`);
         }
         exit(1);
     }
 });
 program.command('get-aws-credentials')
-    .description('get AWS credentials for deployment')
-    .argument('[gameserver]', 'address of gameserver (e.g. idler-develop.p1.metaplay.io)')
+    .description('get AWS credentials for target environment')
+    .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
     .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
     .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
     .option('-p, --project <project>', 'project name (e.g. idler)')
@@ -135,15 +222,9 @@ program.command('get-aws-credentials')
             throw new Error('Invalid format; must be one of json or env');
         }
         const tokens = await loadTokens();
-        if (!gameserver && !(options.organization && options.project && options.environment)) {
-            throw new Error('Could not determine a deployment to fetch the AWS credentials from. You need to specify either a gameserver or an organization, project, and environment');
-        }
-        const stackApi = new StackAPI(tokens.access_token);
-        if (options.stackApi) {
-            stackApi.stack_api_base_uri = options.stackApi;
-        }
-        const payload = gameserver ? { gameserver } : { organization: options.organization, project: options.project, environment: options.environment };
-        const credentials = await stackApi.getAwsCredentials(payload);
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
+        const credentials = await stackApi.getAwsCredentials(gameserverId);
         if (options.format === 'env') {
             console.log(`export AWS_ACCESS_KEY_ID=${credentials.AccessKeyId}`);
             console.log(`export AWS_SECRET_ACCESS_KEY=${credentials.SecretAccessKey}`);
@@ -164,8 +245,8 @@ program.command('get-aws-credentials')
     }
 });
 program.command('get-docker-login')
-    .description('get docker login credentials for pushing the server image')
-    .argument('[gameserver]', 'address of gameserver (e.g. idler-develop.p1.metaplay.io)')
+    .description('get docker login credentials for pushing the server image to target environment')
+    .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
     .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
     .option('-p, --project <project>', 'project name (e.g. idler)')
     .option('-e, --environment <environment>', 'environment name (e.g. develop)')
@@ -179,20 +260,14 @@ program.command('get-docker-login')
             throw new Error('Invalid format; must be one of json or env');
         }
         const tokens = await loadTokens();
-        if (!gameserver && !(options.organization && options.project && options.environment)) {
-            throw new Error('Could not determine a game server deployment. You need to specify either a gameserver or an organization, project, and environment');
-        }
-        const stackApi = new StackAPI(tokens.access_token);
-        if (options.stackApi) {
-            stackApi.stack_api_base_uri = options.stackApi;
-        }
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
         // Fetch AWS credentials from Metaplay cloud
         logger.debug('Get AWS credentials from Metaplay');
-        const payload = gameserver ? { gameserver } : { organization: options.organization, project: options.project, environment: options.environment };
-        const credentials = await stackApi.getAwsCredentials(payload);
+        const credentials = await stackApi.getAwsCredentials(gameserverId);
         // Get environment info (region is needed for ECR)
         logger.debug('Get environment info');
-        const environment = await stackApi.getEnvironmentDetails(payload);
+        const environment = await stackApi.getEnvironmentDetails(gameserverId);
         const awsRegion = environment.deployment.aws_region;
         const dockerRepo = environment.deployment.ecr_repo;
         // Create ECR client with credentials
@@ -239,8 +314,8 @@ program.command('get-docker-login')
     }
 });
 program.command('get-environment')
-    .description('get environment details for deployment')
-    .argument('[gameserver]', 'address of gameserver (e.g. idler-develop.p1.metaplay.io)')
+    .description('get details of an environment')
+    .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
     .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
     .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
     .option('-p, --project <project>', 'project name (e.g. idler)')
@@ -251,15 +326,9 @@ program.command('get-environment')
     .action(async (gameserver, options) => {
     try {
         const tokens = await loadTokens();
-        if (!gameserver && !(options.organization && options.project && options.environment)) {
-            throw new Error('Could not determine a deployment to fetch environment details from. You need to specify either a gameserver or an organization, project, and environment');
-        }
-        const stackApi = new StackAPI(tokens.access_token);
-        if (options.stackApi) {
-            stackApi.stack_api_base_uri = options.stackApi;
-        }
-        const payload = gameserver ? { gameserver } : { organization: options.organization, project: options.project, environment: options.environment };
-        const environment = await stackApi.getEnvironmentDetails(payload);
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
+        const environment = await stackApi.getEnvironmentDetails(gameserverId);
         console.log(JSON.stringify(environment));
     }
     catch (error) {
@@ -269,17 +338,295 @@ program.command('get-environment')
         exit(1);
     }
 });
+program.command('push-docker-image')
+    .description('push docker image into the target environment image registry')
+    .argument('gameserver', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
+    .argument('image-name', 'full name of the docker image to push (eg, the gameserver:<sha>)')
+    .hook('preAction', async () => {
+    await extendCurrentSession();
+})
+    .action(async (gameserver, imageName, options) => {
+    try {
+        console.log(`Pushing docker image ${imageName} to target environment ${gameserver}...`);
+        const tokens = await loadTokens();
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
+        // Fetch AWS credentials from Metaplay cloud
+        logger.debug('Get AWS credentials from Metaplay');
+        const credentials = await stackApi.getAwsCredentials(gameserverId);
+        // Get environment info (region is needed for ECR)
+        logger.debug('Get environment info');
+        const envInfo = await stackApi.getEnvironmentDetails(gameserverId);
+        const awsRegion = envInfo.deployment.aws_region;
+        // Create ECR client with credentials
+        logger.debug('Create ECR client');
+        const client = new ECRClient({
+            credentials: {
+                accessKeyId: credentials.AccessKeyId,
+                secretAccessKey: credentials.SecretAccessKey,
+                sessionToken: credentials.SessionToken
+            },
+            region: awsRegion
+        });
+        // Fetch the ECR docker authentication token
+        logger.debug('Fetch ECR login credentials from AWS');
+        const command = new GetAuthorizationTokenCommand({});
+        const response = await client.send(command);
+        if (!response.authorizationData || response.authorizationData.length === 0 || !response.authorizationData[0].authorizationToken) {
+            throw new Error('Received an empty authorization token response for ECR repository');
+        }
+        // Parse username and password from the response (separated by a ':')
+        logger.debug('Parse ECR response');
+        const authorization64 = response.authorizationData[0].authorizationToken;
+        const authorization = Buffer.from(authorization64, 'base64').toString();
+        const [username, password] = authorization.split(':');
+        const authConfig = { username, password, serveraddress: '' }; // \todo serveraddress value? https://stackoverflow.com/questions/54252777/how-to-push-image-with-dockerode-image-not-pushed-but-no-error
+        // Resolve tag from src image
+        if (!imageName) {
+            throw new Error('Must specify a valid docker image name as the image-name argument');
+        }
+        const srcImageParts = imageName.split(':');
+        if (srcImageParts.length !== 2 || srcImageParts[0].length === 0 || srcImageParts[1].length === 0) {
+            throw new Error(`Invalid docker image name '${imageName}', expecting the name in format 'name:tag'`);
+        }
+        const imageTag = srcImageParts[1];
+        // Resolve source image
+        const srcImageName = imageName;
+        const dstRepoName = envInfo.deployment.ecr_repo;
+        const dstImageName = `${dstRepoName}:${imageTag}`;
+        const dockerApi = new Docker();
+        const srcDockerImage = dockerApi.getImage(srcImageName);
+        // If names don't match, tag the src image as dst
+        if (srcImageName !== dstImageName) {
+            logger.debug(`Tagging image ${srcImageName} as ${dstImageName}`);
+            await srcDockerImage.tag({ repo: dstRepoName, tag: imageTag });
+        }
+        // Push the image
+        logger.debug(`Push image ${dstImageName}`);
+        const dstDockerImage = dockerApi.getImage(dstImageName);
+        const pushStream = await dstDockerImage.push({ authconfig: authConfig, tag: options.imageTag });
+        // Follow push progress & wait until completed
+        logger.debug('Following push stream...');
+        await new Promise((resolve, reject) => {
+            dockerApi.modem.followProgress(pushStream, (error, result) => {
+                if (error) {
+                    logger.debug('Failed to push image:', error);
+                    reject(error);
+                }
+                else {
+                    // result contains an array of all the progress objects
+                    logger.debug('Succesfully finished pushing image');
+                    resolve(result);
+                }
+            }, (obj) => {
+                // console.log('Progress:', obj)
+                // { status: 'Preparing', progressDetail: {}, id: '82730adcaeb0' }
+                // { status: 'Layer already exists', progressDetail: {}, id: '7cd701fff13a' }
+            });
+        });
+        console.log(`Successfully pushed docker image to ${dstImageName}!`);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`Failed to push docker image: ${error.message}`);
+        }
+        exit(1);
+    }
+});
+program.command('deploy-server')
+    .description('deploy a game server image to target environment')
+    .argument('gameserver', 'address of gameserver (e.g. idler-develop.p1.metaplay.io)')
+    .argument('image-tag', 'docker image tag to deploy (usually the SHA of the build)')
+    .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
+    .option('-f, --values <path-to-values-file>', 'path to Helm values file to use for this deployment')
+    .option('--local-chart-path <path-to-chart-directory>', 'path to local Helm chart directory (to use a chart from local disk)')
+    .option('--helm-chart-repo <url>', 'override the URL of the Helm chart repository (eg, https://charts.metaplay.dev/testing)')
+    .option('--helm-chart-version <version>', 'override the Helm chart version (eg, 0.6.0)')
+    .option('--deployment-name', 'Helm deployment name to use', 'gameserver')
+    .hook('preAction', async () => {
+    await extendCurrentSession();
+})
+    .action(async (gameserver, imageTag, options) => {
+    try {
+        const tokens = await loadTokens();
+        const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+        const gameserverId = resolveGameserverId(gameserver, options);
+        console.log(`Deploying server to ${gameserver} with image tag ${imageTag}...`);
+        // Fetch target environment details
+        const envInfo = await stackApi.getEnvironmentDetails(gameserverId);
+        if (!imageTag) {
+            throw new Error('Must specify a valid docker image tag as the image-tag argument, usually the SHA of the build');
+        }
+        if (!options.deploymentName) {
+            throw new Error(`Invalid Helm deployment name '${options.deploymentName}'`);
+        }
+        // Resolve information about docker image
+        const dockerRepo = envInfo.deployment.ecr_repo;
+        const imageName = `${dockerRepo}:${imageTag}`;
+        logger.debug(`Fetch docker image information for ${imageName}`);
+        let imageLabels;
+        try {
+            const dockerApi = new Docker();
+            const dockerImage = dockerApi.getImage(imageName);
+            imageLabels = (await dockerImage.inspect()).Config.Labels || {};
+        }
+        catch (err) {
+            throw new Error(`Unable to fetch metadata for docker image ${imageName}: ${err}`);
+        }
+        // Try to resolve SDK version and Helm repo and chart version from the docker labels
+        // \note These only exist for SDK R28 and newer images
+        logger.debug('Docker image labels: ', JSON.stringify(imageLabels));
+        const sdkVersion = imageLabels['io.metaplay.sdk_version'];
+        // Resolve helmChartRepo, in order of precedence:
+        // - Specified in the cli options
+        // - Specified in the docker image label
+        // - Fall back to 'https://charts.metaplay.dev'
+        const helmChartRepo = options.helmChartRepo ?? imageLabels['io.metaplay.default_helm_repo'] ?? 'https://charts.metaplay.dev';
+        // Resolve helmChartVersion, in order of precedence:
+        // - Specified in the cli options
+        // - Specified in the docker image label
+        // - Unknown, error out!
+        const helmChartVersion = options.helmChartVersion ?? imageLabels['io.metaplay.default_server_chart_version'];
+        if (!helmChartVersion) {
+            throw new Error('No Helm chart version defined. With pre-R28 SDK versions, you must specify the Helm chart repository explicitly with --helm-chart-version.');
+        }
+        // A values file is required (at least for now it makes no sense to deploy without one)
+        if (!options.values) {
+            throw new Error('Path to a Helm values file must be specified with --values');
+        }
+        // \If Helm chart >= 0.7.0, check that sdkVersion is defined in docker image labels (the labels were added in R28)
+        const helmChartSemver = semver.parse(helmChartVersion);
+        if (!helmChartSemver) {
+            throw new Error(`Resolve Helm chart version '${helmChartVersion}' is not a valid SemVer!`);
+        }
+        if (semver.gte(helmChartSemver, new semver.SemVer('0.7.0'), true) && !sdkVersion) {
+            throw new Error('Helm chart versions >=0.7.0 are only compatible with SDK versions 28.0.0 and above.');
+        }
+        // Fetch kubeconfig and write it to a temporary file
+        // \todo allow passing a custom kubeconfig file?
+        const kubeconfigPayload = await stackApi.getKubeConfig(gameserverId);
+        const kubeconfigPath = join(tmpdir(), randomBytes(20).toString('hex'));
+        logger.debug(`Write temporary kubeconfig in ${kubeconfigPath}`);
+        await writeFile(kubeconfigPath, kubeconfigPayload, { mode: 0o600 });
+        try {
+            // Construct Helm invocation
+            const chartNameOrPath = options.localChartPath ?? 'metaplay-gameserver';
+            const helmArgs = ['upgrade', '--install', '--wait'] // \note wait for the pods to stabilize -- otherwise status check can read state before any changes to pods are applied
+                .concat(['--kubeconfig', kubeconfigPath])
+                .concat(['-n', envInfo.deployment.kubernetes_namespace])
+                .concat(['--values', options.values])
+                .concat(['--set-string', `image.tag=${imageTag}`])
+                .concat(sdkVersion ? ['--set-string', `sdk.version=${sdkVersion}`] : [])
+                .concat(!options.chartPath ? ['--repo', helmChartRepo, '--version', helmChartVersion] : [])
+                .concat([options.deploymentName])
+                .concat([chartNameOrPath]);
+            logger.info(`Execute: helm ${helmArgs.join(' ')}`);
+            // Execute Helm
+            let helmResult;
+            try {
+                helmResult = await executeCommand('helm', helmArgs);
+                // \todo output something from Helm result?
+            }
+            catch (err) {
+                throw new Error(`Failed to execute 'helm': ${err}. You need to have Helm v3 installed to deploy a game server with metaplay-auth.`);
+            }
+            // Throw on Helm non-success exit code
+            if (helmResult.code !== 0) {
+                throw new Error(`Helm deploy failed with exit code ${helmResult.code}: ${helmResult.stderr}`);
+            }
+            const testingRepoSuffix = (!options.chartPath && helmChartRepo !== 'https://charts.metaplay.dev') ? ` from repo ${helmChartRepo}` : '';
+            console.log(`Game server deployed to ${gameserver} with tag ${imageTag} using chart version ${helmChartVersion}${testingRepoSuffix}!`);
+        }
+        finally {
+            // Remove temporary kubeconfig file
+            await unlink(kubeconfigPath);
+        }
+        // Check the status of the game server deployment
+        try {
+            const kubeconfig = new KubeConfig();
+            kubeconfig.loadFromString(kubeconfigPayload);
+            console.log('Validating game server deployment...');
+            const exitCode = await checkGameServerDeployment(envInfo.deployment.kubernetes_namespace, kubeconfig);
+            exit(exitCode);
+        }
+        catch (error) {
+            console.error(`Failed to resolve game server deployment status: ${error}`);
+            exit(2);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error deploying game server into target environment: ${error.message}`);
+        }
+        exit(1);
+    }
+});
+program.command('check-server-status')
+    .description('check the status of a deployed server and print out information that is helpful in debugging failed deployments')
+    .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
+    .hook('preAction', async () => {
+    await extendCurrentSession();
+})
+    .action(async (gameserver, options) => {
+    const tokens = await loadTokens();
+    const stackApi = new StackAPI(tokens.access_token, options.stackApi);
+    const gameserverId = resolveGameserverId(gameserver, options);
+    try {
+        logger.debug('Get environment info');
+        const envInfo = await stackApi.getEnvironmentDetails(gameserverId);
+        const kubernetesNamespace = envInfo.deployment.kubernetes_namespace;
+        // Load kubeconfig from file and throw error if validation fails.
+        logger.debug('Get kubeconfig');
+        const kubeconfig = new KubeConfig();
+        try {
+            // Fetch kubeconfig and write it to a temporary file
+            // \todo allow passing a custom kubeconfig file?
+            const kubeconfigPayload = await stackApi.getKubeConfig(gameserverId);
+            kubeconfig.loadFromString(kubeconfigPayload);
+        }
+        catch (error) {
+            throw new Error(`Failed to load or validate kubeconfig. ${error}`);
+        }
+        // Run the checks and exit with success/failure exitCode depending on result
+        console.log(`Validating game server deployment in namespace ${kubernetesNamespace}`);
+        const exitCode = await checkGameServerDeployment(kubernetesNamespace, kubeconfig);
+        exit(exitCode);
+    }
+    catch (error) {
+        console.error(`Failed to check deployment status: ${error.message}`);
+        exit(1);
+    }
+});
 program.command('check-deployment')
-    .description('[experimental] check that a game server was successfully deployed, or print out useful error messages in case of failure')
+    .description('[deprecated] check that a game server was successfully deployed, or print out useful error messages in case of failure')
     .argument('[namespace]', 'kubernetes namespace of the deployment')
     .action(async (namespace) => {
-    setLogLevel(0);
+    console.error('DEPRECATED! Use the "metaplay-auth check-server-status [gameserver]" command instead! This command will be removed soon.');
     try {
         if (!namespace) {
             throw new Error('Must specify value for argument "namespace"');
         }
+        // Check that the KUBECONFIG environment variable exists
+        const kubeconfigPath = process.env.KUBECONFIG;
+        if (!kubeconfigPath) {
+            throw new Error('The KUBECONFIG environment variable must be specified');
+        }
+        // Check that the kubeconfig file exists
+        if (!existsSync(kubeconfigPath)) {
+            throw new Error(`The environment variable KUBECONFIG points to a file '${kubeconfigPath}' that doesn't exist`);
+        }
+        // Create Kubernetes API instance (with default kubeconfig)
+        const kubeconfig = new KubeConfig();
+        // Load kubeconfig from file and throw error if validation fails.
+        try {
+            kubeconfig.loadFromFile(kubeconfigPath);
+        }
+        catch (error) {
+            throw new Error(`Failed to load or validate kubeconfig. ${error}`);
+        }
         // Run the checks and exit with success/failure exitCode depending on result
-        const exitCode = await checkGameServerDeployment(namespace);
+        console.log(`Validating game server deployment in namespace ${namespace}`);
+        const exitCode = await checkGameServerDeployment(namespace, kubeconfig);
         exit(exitCode);
     }
     catch (error) {