feat(gamelift): add Alias L2 Construct for GameLift

packages/@aws-cdk/aws-gamelift/README.md

@@ -315,6 +315,30 @@ const fleet = new gamelift.BuildFleet(this, 'Game server fleet', {
 fleet.grant(role, 'gamelift:ListFleets');
 ```
 
+### Alias
+
+A GameLift alias is used to abstract a fleet designation. Fleet designations
+tell Amazon GameLift where to search for available resources when creating new
+game sessions for players. By using aliases instead of specific fleet IDs, you
+can more easily and seamlessly switch player traffic from one fleet to another
+by changing the alias's target location.
+
+```ts
+declare const fleet: gamelift.BuildFleet;
+
+// Add an alias to an existing fleet using a dedicated fleet method
+const liveAlias = fleet.addAlias('live');
+
+// You can also create a standalone alias
+new gamelift.Alias(this, 'TerminalAlias', {
+  aliasName: 'terminal-alias',
+  terminalMessage: 'A terminal message',
+});
+```
+
+See [Add an alias to a GameLift fleet](https://docs.aws.amazon.com/gamelift/latest/developerguide/aliases-creating.html)
+in the *Amazon GameLift Developer Guide*.
+
 ### Monitoring your Fleet
 
 GameLift is integrated with CloudWatch, so you can monitor the performance of

packages/@aws-cdk/aws-gamelift/lib/alias.ts

@@ -0,0 +1,244 @@
+import * as cdk from '@aws-cdk/core';
+import { Construct } from 'constructs';
+import { IFleet } from './fleet-base';
+import { CfnAlias } from './gamelift.generated';
+
+/**
+ * Represents a Gamelift Alias for a Gamelift fleet destination.
+ */
+export interface IAlias extends cdk.IResource {
+
+  /**
+     * The Identifier of the alias.
+     *
+     * @attribute
+     */
+  readonly aliasId: string;
+
+  /**
+   * The ARN of the alias.
+   *
+   * @attribute
+   */
+  readonly aliasArn: string;
+}
+
+/**
+ * Options for `gamelift.Alias`.
+ */
+export interface AliasOptions {
+  /**
+     * Description for the alias
+     *
+     * @default No description
+     */
+  readonly description?: string;
+}
+
+/**
+ * A full specification of an alias that can be used to import it fluently into the CDK application.
+ */
+export interface AliasAttributes {
+  /**
+       * The ARN of the alias
+       *
+       * At least one of `aliasArn` and `aliasId` must be provided.
+       *
+       * @default derived from `aliasId`.
+       */
+  readonly aliasArn?: string;
+
+  /**
+     * The identifier of the alias
+     *
+     * At least one of `aliasId` and `aliasArn`  must be provided.
+     *
+     * @default derived from `aliasArn`.
+     */
+  readonly aliasId?: string;
+}
+
+/**
+ * Properties for a new Fleet alias
+ */
+export interface AliasProps {
+  /**
+     * Name of this alias
+     */
+  readonly aliasName: string;
+
+  /**
+     * A human-readable description of the alias
+     *
+     * @default no description
+     */
+  readonly description?: string;
+
+  /**
+   * A fleet that the alias points to.
+   * If specified, the alias resolves to one specific fleet.
+   *
+   * At least one of `fleet` and `terminalMessage` must be provided.
+   *
+   * @default no fleet that the alias points to.
+   */
+  readonly fleet?: IFleet;
+
+  /**
+   * The message text to be used with a terminal routing strategy.
+   *
+   * At least one of `fleet` and `terminalMessage` must be provided.
+   *
+   * @default no terminal message
+   */
+  readonly terminalMessage?: string;
+}
+
+/**
+ * Base class for new and imported GameLift Alias.
+ */
+export abstract class AliasBase extends cdk.Resource implements IAlias {
+  /**
+ * The Identifier of the alias.
+ */
+  public abstract readonly aliasId: string;
+  /**
+   * The ARN of the alias
+   */
+  public abstract readonly aliasArn: string;
+}
+
+/**
+ * A Amazon GameLift alias is used to abstract a fleet designation.
+ * Fleet designations tell GameLift where to search for available resources when creating new game sessions for players.
+ * Use aliases instead of specific fleet IDs to seamlessly switch player traffic from one fleet to another by changing the alias's target location.
+ *
+ * Aliases are useful in games that don't use queues.
+ * Switching fleets in a queue is a simple matter of creating a new fleet, adding it to the queue, and removing the old fleet, none of which is visible to players.
+ * In contrast, game clients that don't use queues must specify which fleet to use when communicating with the GameLift service.
+ * Without aliases, a fleet switch requires updates to your game code and possibly distribution of an updated game clients to players.
+ *
+ * When updating the fleet-id an alias points to, there is a transition period of up to 2 minutes where game sessions on the alias may end up on the old fleet.
+ *
+ * @see https://docs.aws.amazon.com/gamelift/latest/developerguide/aliases-creating.html
+ *
+ * @resource AWS::GameLift::Alias
+ */
+export class Alias extends AliasBase {
+
+  /**
+   * Import an existing alias from its identifier.
+   */
+  static fromAliasId(scope: Construct, id: string, aliasId: string): IAlias {
+    return this.fromAliasAttributes(scope, id, { aliasId: aliasId });
+  }
+
+  /**
+   * Import an existing alias from its ARN.
+   */
+  static fromAliasArn(scope: Construct, id: string, aliasArn: string): IAlias {
+    return this.fromAliasAttributes(scope, id, { aliasArn: aliasArn });
+  }
+
+  /**
+   * Import an existing alias from its attributes.
+   */
+  static fromAliasAttributes(scope: Construct, id: string, attrs: AliasAttributes): IAlias {
+    if (!attrs.aliasId && !attrs.aliasArn) {
+      throw new Error('Either aliasId or aliasArn must be provided in AliasAttributes');
+    }
+    const aliasId = attrs.aliasId ??
+      cdk.Stack.of(scope).splitArn(attrs.aliasArn!, cdk.ArnFormat.SLASH_RESOURCE_NAME).resourceName;
+
+    if (!aliasId) {
+      throw new Error(`No alias identifier found in ARN: '${attrs.aliasArn}'`);
+    }
+
+    const aliasArn = attrs.aliasArn ?? cdk.Stack.of(scope).formatArn({
+      service: 'gamelift',
+      resource: 'alias',
+      resourceName: attrs.aliasId,
+      arnFormat: cdk.ArnFormat.SLASH_RESOURCE_NAME,
+    });
+    class Import extends AliasBase {
+      public readonly aliasId = aliasId!;
+      public readonly aliasArn = aliasArn;
+
+      constructor(s: Construct, i: string) {
+        super(s, i, {
+          environmentFromArn: aliasArn,
+        });
+      }
+    }
+    return new Import(scope, id);
+  }
+
+  /**
+   * The Identifier of the alias.
+   */
+  public readonly aliasId: string;
+
+  /**
+    * The ARN of the alias.
+    */
+  public readonly aliasArn: string;
+
+  /**
+   * A fleet that the alias points to.
+   */
+  public readonly fleet?: IFleet;
+
+  constructor(scope: Construct, id: string, props: AliasProps) {
+    super(scope, id, {
+      physicalName: props.aliasName,
+    });
+
+    if (!cdk.Token.isUnresolved(props.aliasName)) {
+      if (props.aliasName.length > 1024) {
+        throw new Error(`Alias name can not be longer than 1024 characters but has ${props.aliasName.length} characters.`);
+      }
+    }
+
+    if (props.description && !cdk.Token.isUnresolved(props.description)) {
+      if (props.description.length > 1024) {
+        throw new Error(`Alias description can not be longer than 1024 characters but has ${props.description.length} characters.`);
+      }
+    }
+
+    if (!props.terminalMessage && !props.fleet) {
+      throw new Error('Either a terminal message or a fleet must be binded to this Alias.');
+    }
+
+    if (props.terminalMessage && props.fleet) {
+      throw new Error('Either a terminal message or a fleet must be binded to this Alias, not both.');
+    }
+
+    const resource = new CfnAlias(this, 'Resource', {
+      name: props.aliasName,
+      description: props.description,
+      routingStrategy: this.parseRoutingStrategy(props),
+    });
+
+    this.aliasId = this.getResourceNameAttribute(resource.ref);
+    this.aliasArn = cdk.Stack.of(scope).formatArn({
+      service: 'gamelift',
+      resource: 'alias',
+      resourceName: this.aliasId,
+      arnFormat: cdk.ArnFormat.SLASH_RESOURCE_NAME,
+    });
+  }
+
+  private parseRoutingStrategy(props: AliasProps): CfnAlias.RoutingStrategyProperty {
+    if (props.fleet ) {
+      return {
+        fleetId: props.fleet.fleetId,
+        type: 'SIMPLE',
+      };
+    }
+    return {
+      message: props.terminalMessage,
+      type: 'TERMINAL',
+    };
+  }
+}
+

packages/@aws-cdk/aws-gamelift/lib/fleet-base.ts

@@ -3,6 +3,7 @@ import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as cdk from '@aws-cdk/core';
 import { Construct } from 'constructs';
+import { Alias, AliasOptions } from './alias';
 import { GameLiftMetrics } from './gamelift-canned-metrics.generated';
 import { CfnFleet } from './gamelift.generated';
 
@@ -453,6 +454,33 @@ export abstract class FleetBase extends cdk.Resource implements IFleet {
 
   private readonly locations: Location[] = [];
 
+  /**
+   * Defines an alias for this fleet.
+   *
+   * ```ts
+   * declare const fleet: gamelift.FleetBase;
+   *
+   * fleet.addAlias('Live');
+   *
+   * // Is equivalent to
+   *
+   * new gamelift.Alias(this, 'AliasLive', {
+   *   aliasName: 'Live',
+   *   fleet: fleet,
+   * });
+   * ```
+   *
+   * @param aliasName The name of the alias
+   * @param options Alias options
+   */
+  public addAlias(aliasName: string, options: AliasOptions = {}) {
+    return new Alias(this, `Alias${aliasName}`, {
+      aliasName,
+      fleet: this,
+      ...options,
+    });
+  }
+
   public grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant {
     return iam.Grant.addToPrincipal({
       resourceArns: [this.fleetArn],

packages/@aws-cdk/aws-gamelift/lib/index.ts

@@ -1,3 +1,4 @@
+export * from './alias';
 export * from './content';
 export * from './build';
 export * from './script';