@metaplay/metaplay-auth 1.4.1 → 1.5.0

package/index.ts

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { Command } from 'commander'
 import Docker from 'dockerode'
-import { loginAndSaveTokens, machineLoginAndSaveTokens, extendCurrentSession, loadTokens, removeTokens } from './src/auth.js'
-import { StackAPI, type GameserverId } from './src/stackapi.js'
-import { checkGameServerDeployment } from './src/deployment.js'
+import { loginAndSaveTokens, machineLoginAndSaveTokens, extendCurrentSession, loadTokens, removeTokens, TokenSet } from './src/auth.js'
+import { StackAPI, defaultStackApiBaseUrl } from './src/stackapi.js'
+import { checkGameServerDeployment, debugGameServer } from './src/deployment.js'
 import { logger, setLogLevel } from './src/logging.js'
-import { isValidFQDN, executeCommand } from './src/utils.js'
+import { isValidFQDN, executeCommand, getGameserverAdminUrl } from './src/utils.js'
+import { TargetEnvironment } from './src/targetenvironment.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'
@@ -15,28 +15,66 @@ import { writeFile, unlink } from 'fs/promises'
 import { existsSync } from 'fs'
 import { KubeConfig } from '@kubernetes/client-node'
 import * as semver from 'semver'
+import { PACKAGE_VERSION } from './src/version.js'
+
+function resolveTargetEnvironmentFromFQDN (tokens: TokenSet, environmentDomain: string): TargetEnvironment {
+  const adminApiDomain = getGameserverAdminUrl(environmentDomain)
+  // \todo using the old <environment>/.infra path as v1 API needs organization, project, environment which we don't have with FQDN environments
+  const environmentApiBaseUrl = `https://${adminApiDomain}/.infra`
+
+  return new TargetEnvironment(
+    tokens.access_token,
+    environmentDomain,
+    defaultStackApiBaseUrl,
+    environmentApiBaseUrl)
+}
+
+async function resolveTargetEnvironmentFromTuple (tokens: TokenSet, organization: string, project: string, environment: string, stackApiUrl?: string): Promise<TargetEnvironment> {
+  // \todo Later on, fetch the environment information from the portal (not StackAPI), including the stack and its stackApiBaseUrl
+  const stackApiBaseUrl = stackApiUrl ?? defaultStackApiBaseUrl
+  const stackApi = new StackAPI(tokens.access_token, stackApiBaseUrl)
+  const environmentDomain = await stackApi.resolveManagedEnvironmentFQDN(organization, project, environment)
+  const environmentApiBaseUrl = `${stackApiBaseUrl}/v1/servers/${organization}/${project}/${environment}`
+
+  return new TargetEnvironment(
+    tokens.access_token,
+    environmentDomain,
+    stackApiBaseUrl,
+    environmentApiBaseUrl,
+    organization,
+    project,
+    environment)
+}
 
 /**
- * Helper for parsing the GameserverId type from the command line arguments. Accepts either the gameserver address
+ * Helper for parsing the TargetEnvironment 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: string | undefined, options: any): GameserverId {
+async function resolveTargetEnvironment (address: string | undefined, options: { organization?: string, project?: string, environment?: string, stackApi?: string }): Promise<TargetEnvironment> {
+  const tokens = await loadTokens()
+
   // If address is specified, use it, otherwise assume options has organization, project, and environment
   if (address) {
+    // Address is either FQDN or 'organization-project-environment' tuple
     if (isValidFQDN(address)) {
-      return { gameserver: address }
+      if (options.stackApi) {
+        throw new Error('--stack-api override only supported with organization-project-environment naming, not with FQDN')
+      }
+      return resolveTargetEnvironmentFromFQDN(tokens, 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] }
+      return await resolveTargetEnvironmentFromTuple(tokens, parts[0], parts[1], parts[2], options.stackApi)
     }
   } else if (options.organization && options.project && options.environment) {
-    return { organization: options.organization, project: options.project, environment: options.environment }
+    // Parse tuple from command-line options (output to stderr to avoid messing up '$(eval metaplay-auth ... --format env)' invocations
+    console.warn(`Warning: Specifying the target environment with -o (--organization), -p (--project), and -e (--environment) is deprecated! Use the '${options.organization}-${options.project}-${options.environment}' syntax instead.`)
+    return await resolveTargetEnvironmentFromTuple(tokens, options.organization, options.project, options.environment, options.stackApi)
   } 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.')
+    throw new Error('Could not determine target environment from arguments: You need to specify either an environment FQDN or an organization, project, and environment. Run this command with --help flag for more information.')
   }
 }
 
@@ -45,7 +83,7 @@ const program = new Command()
 program
   .name('metaplay-auth')
   .description('Authenticate with Metaplay and get AWS and Kubernetes credentials for game servers.')
-  .version('1.4.1')
+  .version(PACKAGE_VERSION)
   .option('-d, --debug', 'enable debug output')
   .hook('preAction', (thisCommand) => {
     // Handle debug flag for all commands.
@@ -68,11 +106,12 @@ program.command('machine-login')
   .option('--dev-credentials', 'machine user credentials to use, only for dev purposes, use METAPLAY_CREDENTIALS env variable for better safety!')
   .action(async (options) => {
     // Get credentials from command line or from METAPLAY_CREDENTIALS environment variable
-    let credentials
+    let credentials: string
     if (options.devCredentials) {
       credentials = options.devCredentials
     } else {
-      credentials = process.env.METAPLAY_CREDENTIALS
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      credentials = process.env.METAPLAY_CREDENTIALS!
       if (!credentials || credentials === '') {
         throw new Error('Unable to find the credentials, the environment variable METAPLAY_CREDENTIALS is not defined!')
       }
@@ -117,7 +156,7 @@ program.command('show-tokens')
     try {
       // TODO: Could detect if not logged in and fail more gracefully?
       const tokens = await loadTokens()
-      console.log(tokens)
+      console.log(JSON.stringify(tokens, undefined, 2))
     } catch (error) {
       if (error instanceof Error) {
         console.error(`Error showing tokens: ${error.message}`)
@@ -130,32 +169,31 @@ program.command('get-kubeconfig')
   .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('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] 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) => {
+  .action(async (gameserver: string | undefined, options: { stackApi?: string, organization?: string, project?: string, environment?: string, type?: string, output?: string }) => {
     try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
       // Default to credentialsType==dynamic for human users, and credentialsType==static for machine users
+      const tokens = await loadTokens()
       const isHumanUser = !!tokens.refresh_token
-      const credentialsType = options.credentialsType ?? (isHumanUser ? 'dynamic' : 'static')
+      const credentialsType = options.type ?? (isHumanUser ? 'dynamic' : 'static')
 
       // Generate kubeconfig
       let kubeconfigPayload
       if (credentialsType === 'dynamic') {
         logger.debug('Fetching kubeconfig with execcredential')
-        kubeconfigPayload = await stackApi.getKubeConfigExecCredential(gameserverId)
+        kubeconfigPayload = await targetEnv.getKubeConfigExecCredential()
       } else if (credentialsType === 'static') {
         logger.debug('Fetching kubeconfig with embedded secret')
-        kubeconfigPayload = await stackApi.getKubeConfig(gameserverId)
+        kubeconfigPayload = await targetEnv.getKubeConfig()
       } else {
         throw new Error('Invalid credentials type; must be either "static" or "dynamic"')
       }
@@ -188,19 +226,16 @@ 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)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
+  .action(async (gameserver: string | undefined, options: { stackApi?: string, organization?: string, project?: string, environment?: string }) => {
     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)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
+      const credentials = await targetEnv.getKubeExecCredential()
       console.log(credentials)
     } catch (error) {
       if (error instanceof Error) {
@@ -214,24 +249,23 @@ program.command('get-aws-credentials')
   .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)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .option('-f, --format <format>', 'output format (json or env)', 'json')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
+  .action(async (gameserver: string | undefined, options: { stackApi?: string, organization?: string, project?: string, environment?: string, format?: string }) => {
     try {
       if (options.format !== 'json' && options.format !== 'env') {
         throw new Error('Invalid format; must be one of json or env')
       }
 
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
-      const credentials = await stackApi.getAwsCredentials(gameserverId)
+      // Get the AWS credentials
+      const credentials = await targetEnv.getAwsCredentials()
 
       if (options.format === 'env') {
         console.log(`export AWS_ACCESS_KEY_ID=${credentials.AccessKeyId}`)
@@ -252,59 +286,35 @@ program.command('get-aws-credentials')
   })
 
 program.command('get-docker-login')
-  .description('get docker login credentials for pushing the server image to target environment')
+  .description('[deprecated] 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)')
+  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .option('-f, --format <format>', 'output format (json or env)', 'json')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
+  .action(async (gameserver: string | undefined, options: { stackApi?: string, organization?: string, project?: string, environment?: string, format?: string }) => {
     try {
       if (options.format !== 'json' && options.format !== 'env') {
         throw new Error('Invalid format; must be one of json or env')
       }
 
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+      console.warn('The get-docker-login command is deprecated! Use the push-docker-image command instead.')
 
-      // Fetch AWS credentials from Metaplay cloud
-      logger.debug('Get AWS credentials from Metaplay')
-      const credentials = await stackApi.getAwsCredentials(gameserverId)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
       // Get environment info (region is needed for ECR)
       logger.debug('Get environment info')
-      const environment = await stackApi.getEnvironmentDetails(gameserverId)
-      const awsRegion = environment.deployment.aws_region
+      const environment = await targetEnv.getEnvironmentDetails()
       const dockerRepo = environment.deployment.ecr_repo
 
-      // 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(':')
+      // Resolve docker credentials for remote registry
+      logger.debug('Get docker credentials')
+      const dockerCredentials = await targetEnv.getDockerCredentials()
+      const { username, password } = dockerCredentials
 
       // Output the docker repo & credentials
       if (options.format === 'env') {
@@ -330,20 +340,18 @@ program.command('get-environment')
   .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)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
+  .action(async (gameserver: string | undefined, options: { stackApi?: string, organization?: string, project?: string, environment?: string }) => {
     try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
-      const environment = await stackApi.getEnvironmentDetails(gameserverId)
-      console.log(JSON.stringify(environment))
+      const environment = await targetEnv.getEnvironmentDetails()
+      console.log(JSON.stringify(environment, undefined, 2))
     } catch (error) {
       if (error instanceof Error) {
         console.error(`Error getting environment details: ${error.message}`)
@@ -356,51 +364,23 @@ 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>)')
+  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, imageName, options) => {
+  .action(async (gameserver: string | undefined, imageName: string | undefined, options: { stackApi?: string, imageTag?: string }) => {
     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)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
       // 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')
-      }
+      const envInfo = await targetEnv.getEnvironmentDetails()
 
-      // 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 docker credentials for remote registry
+      logger.debug('Get docker credentials')
+      const dockerCredentials = await targetEnv.getDockerCredentials()
 
       // Resolve tag from src image
       if (!imageName) {
@@ -428,20 +408,21 @@ program.command('push-docker-image')
       // Push the image
       logger.debug(`Push image ${dstImageName}`)
       const dstDockerImage = dockerApi.getImage(dstImageName)
+      const authConfig = { username: dockerCredentials.username, password: dockerCredentials.password, serveraddress: dockerCredentials.registryUrl }
       const pushStream = await dstDockerImage.push({ authconfig: authConfig, tag: options.imageTag })
 
       // Follow push progress & wait until completed
-      logger.debug('Following push stream...')
+      logger.debug('Following image push stream...')
       await new Promise((resolve, reject) => {
         dockerApi.modem.followProgress(
           pushStream,
           (error: Error | null, result: any[]) => {
             if (error) {
-              logger.debug('Failed to push image:', error)
+              logger.debug('Failed to push docker image to target repository:', error)
               reject(error)
             } else {
               // result contains an array of all the progress objects
-              logger.debug('Succesfully finished pushing image')
+              logger.debug('Succesfully finished pushing docker image')
               resolve(result)
             }
           },
@@ -463,10 +444,10 @@ program.command('push-docker-image')
 
 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('gameserver', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
   .argument('image-tag', 'docker image tag to deploy (usually the SHA of the build)')
+  .requiredOption('-f, --values <path-to-values-file>', 'path to Helm values file to use for this deployment')
   .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)')
@@ -474,36 +455,91 @@ program.command('deploy-server')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, imageTag, options) => {
+  .action(async (gameserver: string | undefined, imageTag: string | undefined, options: { values: string, stackApi?: string, localChartPath?: string, helmChartRepo?: string, helmChartVersion?: string, deploymentName?: string }) => {
     try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
       console.log(`Deploying server to ${gameserver} with image tag ${imageTag}...`)
 
       // Fetch target environment details
-      const envInfo = await stackApi.getEnvironmentDetails(gameserverId)
+      const envInfo = await targetEnv.getEnvironmentDetails()
 
       if (!imageTag) {
         throw new Error('Must specify a valid docker image tag as the image-tag argument, usually the SHA of the build')
       }
+      // \todo validate that imageTag is just the version part (i.e, contains no ':')
 
       if (!options.deploymentName) {
-        throw new Error(`Invalid Helm deployment name '${options.deploymentName}'`)
+        throw new Error(`Invalid Helm deployment name '${options.deploymentName}'; specify one with --deployment-name or use the default`)
       }
 
+      // Fetch Docker credentials for target environment registry
+      const dockerCredentials = await targetEnv.getDockerCredentials()
+
       // Resolve information about docker image
+      // const dockerApi = new Docker({
+      //   host: dockerCredentials.registryUrl,
+      //   port: 443,
+      //   protocol: 'https',
+      //   username: dockerCredentials.username,
+      //   headers: {
+      //     Authorization: `Bearer ${dockerCredentials.password}`,
+      //     Host: dockerCredentials.registryUrl.replace('https://', ''),
+      //   }
+      // })
+      const dockerApi = new Docker()
       const dockerRepo = envInfo.deployment.ecr_repo
       const imageName = `${dockerRepo}:${imageTag}`
-      logger.debug(`Fetch docker image information for ${imageName}`)
+      logger.debug(`Fetch docker image labels for ${imageName}`)
       let imageLabels
       try {
-        const dockerApi = new Docker()
-        const dockerImage = dockerApi.getImage(imageName)
-        imageLabels = (await dockerImage.inspect()).Config.Labels || {}
+        const localDockerImage = dockerApi.getImage(imageName)
+        imageLabels = (await localDockerImage.inspect()).Config.Labels || {}
       } catch (err) {
-        throw new Error(`Unable to fetch metadata for docker image ${imageName}: ${err}`)
+        logger.debug(`Failed to resolve docker image metadata from local image ${imageName}: ${err}`)
+      }
+
+      // If wasn't able to resolve the images, pull image from the target environment registry & resolve labels
+      if (imageLabels === undefined) {
+        // Pull the image from remote registry
+        try {
+          console.log(`Image ${imageName} not found locally -- pulling docker image from target environment registry...`)
+          const authConfig = { username: dockerCredentials.username, password: dockerCredentials.password, serveraddress: dockerCredentials.registryUrl }
+          const pullStream = (await dockerApi.pull(imageName, { authconfig: authConfig }))
+
+          // Follow pull progress & wait until completed
+          logger.debug('Following image pull stream...')
+          await new Promise((resolve, reject) => {
+            dockerApi.modem.followProgress(
+              pullStream,
+              (error: Error | null, result: any[]) => {
+                if (error) {
+                  logger.debug('Failed to pull image:', error)
+                  reject(error)
+                } else {
+                  // result contains an array of all the progress objects
+                  logger.debug('Succesfully finished pulling image')
+                  resolve(result)
+                }
+              },
+              (obj: any) => {
+                // console.log('Progress:', obj)
+                // { status: 'Preparing', progressDetail: {}, id: '82730adcaeb0' }
+                // { status: 'Layer already exists', progressDetail: {}, id: '7cd701fff13a' }
+              })
+          })
+        } catch (err) {
+          throw new Error(`Failed to fetch docker image ${imageName} from target environment registry: ${err}`)
+        }
+
+        // Resolve the labels
+        try {
+          logger.debug('Get docker labels again (with pulled image)')
+          const localDockerImage = dockerApi.getImage(imageName)
+          imageLabels = (await localDockerImage.inspect()).Config.Labels || {}
+        } catch (err) {
+          throw new Error(`Failed to resolve docker image metadata from pulled image ${imageName}: ${err}`)
+        }
       }
 
       // Try to resolve SDK version and Helm repo and chart version from the docker labels
@@ -523,7 +559,7 @@ program.command('deploy-server')
       // - 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.')
+        throw new Error('No Helm chart version defined. With pre-R28 SDK versions, you must specify the Helm chart version explicitly with --helm-chart-version=<version>.')
       }
 
       // A values file is required (at least for now it makes no sense to deploy without one)
@@ -542,7 +578,7 @@ program.command('deploy-server')
 
       // Fetch kubeconfig and write it to a temporary file
       // \todo allow passing a custom kubeconfig file?
-      const kubeconfigPayload = await stackApi.getKubeConfig(gameserverId)
+      const kubeconfigPayload = await targetEnv.getKubeConfig()
       const kubeconfigPath = join(tmpdir(), randomBytes(20).toString('hex'))
       logger.debug(`Write temporary kubeconfig in ${kubeconfigPath}`)
       await writeFile(kubeconfigPath, kubeconfigPayload, { mode: 0o600 })
@@ -557,7 +593,7 @@ program.command('deploy-server')
             .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.localChartPath ? ['--repo', helmChartRepo, '--version', helmChartVersion] : [])
             .concat([options.deploymentName])
             .concat([chartNameOrPath])
         logger.info(`Execute: helm ${helmArgs.join(' ')}`)
@@ -565,18 +601,18 @@ program.command('deploy-server')
         // Execute Helm
         let helmResult
         try {
-          helmResult = await executeCommand('helm', helmArgs)
+          helmResult = await executeCommand('helm', helmArgs, false)
           // \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}`)
+        if (helmResult.exitCode !== 0) {
+          throw new Error(`Helm deploy failed with exit code ${helmResult.exitCode}: ${helmResult.stderr}`)
         }
 
-        const testingRepoSuffix = (!options.chartPath && helmChartRepo !== 'https://charts.metaplay.dev') ? ` from repo ${helmChartRepo}` : ''
+        const testingRepoSuffix = (!options.localChartPath && 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
@@ -589,7 +625,7 @@ program.command('deploy-server')
         kubeconfig.loadFromString(kubeconfigPayload)
 
         console.log('Validating game server deployment...')
-        const exitCode = await checkGameServerDeployment(envInfo.deployment.kubernetes_namespace, kubeconfig)
+        const exitCode = await checkGameServerDeployment(envInfo.deployment.kubernetes_namespace, kubeconfig, imageTag)
         exit(exitCode)
       } catch (error) {
         console.error(`Failed to resolve game server deployment status: ${error}`)
@@ -606,26 +642,25 @@ program.command('deploy-server')
 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)')
+  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver: string | undefined, options) => {
-    const tokens = await loadTokens()
-    const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-    const gameserverId = resolveGameserverId(gameserver, options)
+  .action(async (gameserver: string | undefined, options: { stackApi?: string }) => {
+    const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
     try {
       logger.debug('Get environment info')
-      const envInfo = await stackApi.getEnvironmentDetails(gameserverId)
+      const envInfo = await targetEnv.getEnvironmentDetails()
       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
+        // Initialize kubeconfig with the payload fetched from the cloud
         // \todo allow passing a custom kubeconfig file?
-        const kubeconfigPayload = await stackApi.getKubeConfig(gameserverId)
+        const kubeconfigPayload = await targetEnv.getKubeConfig()
         kubeconfig.loadFromString(kubeconfigPayload)
       } catch (error) {
         throw new Error(`Failed to load or validate kubeconfig. ${error}`)
@@ -633,7 +668,8 @@ program.command('check-server-status')
 
       // 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)
+      // \todo Get requiredImageTag from the Helm chart
+      const exitCode = await checkGameServerDeployment(kubernetesNamespace, kubeconfig, /* requiredImageTag: */ null)
       exit(exitCode)
     } catch (error: any) {
       console.error(`Failed to check deployment status: ${error.message}`)
@@ -674,7 +710,8 @@ program.command('check-deployment')
 
       // Run the checks and exit with success/failure exitCode depending on result
       console.log(`Validating game server deployment in namespace ${namespace}`)
-      const exitCode = await checkGameServerDeployment(namespace, kubeconfig)
+      // \todo Get requiredImageTag from the Helm chart
+      const exitCode = await checkGameServerDeployment(namespace, kubeconfig, /* requiredImageTag: */ null)
       exit(exitCode)
     } catch (error: any) {
       console.error(`Failed to check deployment status: ${error.message}`)
@@ -682,4 +719,19 @@ program.command('check-deployment')
     }
   })
 
+program.command('debug-server')
+  .description('run an ephemeral debug container against a game server pod running in the cloud')
+  .argument('gameserver', 'address of gameserver (e.g., metaplay-idler-develop or idler-develop.p1.metaplay.io)')
+  .argument('[pod-name]', 'name of the pod to debug (must be specified if deployment has multiple pods)')
+  .hook('preAction', async () => {
+    await extendCurrentSession()
+  })
+  .action(async (gameserver: string, podName: string | undefined, options: { stackApi?: string }) => {
+    // Resolve target environment
+    const targetEnv = await resolveTargetEnvironment(gameserver, options)
+
+    // Exec 'kubectl debug ...'
+    await debugGameServer(targetEnv, podName)
+  })
+
 void program.parseAsync()