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';