> **Experimental** > > `@aws-cdk/aws-gamelift-alpha` is an [**experimental**](/stability) (alpha) package: its API may change in any release, without a major version bump. # BuildFleet A fleet contains Amazon Elastic Compute Cloud (Amazon EC2) instances that GameLift hosts. A fleet uses the configuration and scaling logic that you define to run your game server build. You can use a fleet directly without a queue. You can also associate multiple fleets with a GameLift queue. For example, you can use Spot Instance fleets configured with your preferred locations, along with a backup On-Demand Instance fleet with the same locations. Using multiple Spot Instance fleets of different instance types reduces the chance of needing On-Demand Instance placement. Extends: Construct › Resource › FleetBase › BuildFleet Implements: IBuildFleet, IFleet, IGameSessionQueueDestination, IResource, IGrantable, IEnvironmentAware, IConstruct, IDependable - Stability: [Experimental](/cdk/api/stability.html) - CloudFormation: [`AWS::GameLift::Fleet`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-gamelift-fleet.html) - L1 type: [`CfnFleet`](/cdk/api/v2/docs/aws-cdk-lib.aws_gamelift.CfnFleet.html) - Source: [`lib/build-fleet.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0-alpha.0/packages/@aws-cdk/aws-gamelift-alpha/lib/build-fleet.ts#L50) ## Example ```ts declare const build: gamelift.Build; // Server processes can be delcared in a declarative way through the constructor const fleet = new gamelift.BuildFleet(this, 'Game server fleet', { fleetName: 'test-fleet', content: build, instanceType: ec2.InstanceType.of(ec2.InstanceClass.C4, ec2.InstanceSize.LARGE), runtimeConfiguration: { serverProcesses: [{ launchPath: '/local/game/GameLiftExampleServer.x86_64', parameters: '-logFile /local/game/logs/myserver1935.log -port 1935', concurrentExecutions: 100, }] } }); ``` ## Initializer ```ts new BuildFleet(scope: Construct, id: string, props: BuildFleetProps) ``` ## Construct Props - `content`: [IBuild](/cdk/api/v2/docs/@aws-cdk_aws-gamelift-alpha.IBuild.html) (required) — A build to be deployed on the fleet. The build must have been successfully uploaded to Amazon GameLift and be in a `READY` status. This fleet setting cannot be changed once the fleet is created. - `description`: string — A human-readable description of the fleet. **Default:** no description is provided - `desiredCapacity`: number — The number of EC2 instances that you want this fleet to host. **Default:** Default capacity is 0 When creating a new fleet, GameLift automatically sets this value to "1" and initiates a single instance. Once the fleet is active, update this value to trigger GameLift to add or remove instances from the fleet. - `fleetName`: string (required) — A descriptive label that is associated with a fleet. Fleet names do not need to be unique. - `ingressRules`: [IngressRule](/cdk/api/v2/docs/@aws-cdk_aws-gamelift-alpha.IngressRule.html)[] — The allowed IP address ranges and port settings that allow inbound traffic to access game sessions on this fleet. **Default:** no inbound traffic allowed This property must be set before players can connect to game sessions. - `instanceType`: [InstanceType](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.InstanceType.html) (required) — The GameLift-supported Amazon EC2 instance type to use for all fleet instances. Instance type determines the computing resources that will be used to host your game servers, including CPU, memory, storage, and networking capacity. - `locations`: [Location](/cdk/api/v2/docs/@aws-cdk_aws-gamelift-alpha.Location.html)[] — A set of remote locations to deploy additional instances to and manage as part of the fleet. **Default:** Create a fleet with instances in the home region only This parameter can only be used when creating fleets in AWS Regions that support multiple locations. You can add any GameLift-supported AWS Region as a remote location, in the form of an AWS Region code such as `us-west-2`. To create a fleet with instances in the home region only, omit this parameter. - `maxSize`: number = 1 — The maximum number of instances that are allowed in the specified fleet location. - `metricGroup`: string — The name of an AWS CloudWatch metric group to add this fleet to. **Default:** Fleet metrics are aggregated with other fleets in the default metric group A metric group is used to aggregate the metrics for multiple fleets. You can specify an existing metric group name or set a new name to create a new metric group. A fleet can be included in only one metric group at a time. - `minSize`: number = 0 — The minimum number of instances that are allowed in the specified fleet location. - `peerVpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) — A VPC peering connection between your GameLift-hosted game servers and your other non-GameLift resources. **Default:** no vpc peering Use Amazon Virtual Private Cloud (VPC) peering connections to enable your game servers to communicate directly and privately with your other AWS resources, such as a web service or a repository. You can establish VPC peering with any resources that run on AWS and are managed by an AWS account that you have access to. The VPC must be in the same Region as your fleet. Warning: Be sure to create a VPC Peering authorization through Gamelift Service API. - `protectNewGameSession`: boolean — The status of termination protection for active game sessions on the fleet. **Default:** true - Game sessions in `ACTIVE` status cannot be terminated during a scale-down event. By default, new game sessions are protected and cannot be terminated during a scale-down event. - `resourceCreationLimitPolicy`: [ResourceCreationLimitPolicy](/cdk/api/v2/docs/@aws-cdk_aws-gamelift-alpha.ResourceCreationLimitPolicy.html) — A policy that limits the number of game sessions that an individual player can create on instances in this fleet within a specified span of time. **Default:** No resource creation limit policy - `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — The IAM role assumed by GameLift fleet instances to access AWS ressources. **Default:** a role will be created with default trust to Gamelift service principal. With a role set, any application that runs on an instance in this fleet can assume the role, including install scripts, server processes, and daemons (background processes). If providing a custom role, it needs to trust the GameLift service principal (gamelift.amazonaws.com). No permission is required by default. This property cannot be changed after the fleet is created. - `runtimeConfiguration`: [RuntimeConfiguration](/cdk/api/v2/docs/@aws-cdk_aws-gamelift-alpha.RuntimeConfiguration.html) (required) — A collection of server process configurations that describe the set of processes to run on each instance in a fleet. Server processes run either an executable in a custom game build or a Realtime Servers script. GameLift launches the configured processes, manages their life cycle, and replaces them as needed. Each instance checks regularly for an updated runtime configuration. A GameLift instance is limited to 50 processes running concurrently. To calculate the total number of processes in a runtime configuration, add the values of the ConcurrentExecutions parameter for each ServerProcess. - `useCertificate`: boolean — Prompts GameLift to generate a TLS/SSL certificate for the fleet. **Default:** TLS/SSL certificate are generated for the fleet GameLift uses the certificates to encrypt traffic between game clients and the game servers running on GameLift. You can't change this property after you create the fleet. Additionnal info: AWS Certificate Manager (ACM) certificates expire after 13 months. Certificate expiration can cause fleets to fail, preventing players from connecting to instances in the fleet. We recommend you replace fleets before 13 months, consider using fleet aliases for a smooth transition. - `useSpot`: boolean — Indicates whether to use On-Demand or Spot instances for this fleet. By default, fleet use on demand capacity. **Default:** Gamelift fleet use on demand capacity This property cannot be changed after the fleet is created. ## Properties - `content`: [IBuild](/cdk/api/v2/docs/@aws-cdk_aws-gamelift-alpha.IBuild.html) — The build content of the fleet. - `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — The environment this resource belongs to. For resources that are created and managed in a Stack (those created by creating new class instances like `new Role()`, `new Bucket()`, etc.), this is always the same as the environment of the stack they belong to. For referenced resources (those obtained from referencing methods like `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be different than the stack they were imported into. - `fleetArn`: string — The ARN of the fleet. - `fleetId`: string — The Identifier of the fleet. - `grantPrincipal`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) — The principal this GameLift fleet is using. - `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node. - `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class. - `resourceArnForDestination`: string — The ARN to put into the destination field of a game session queue. - `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — The IAM role GameLift assumes by fleet instances to access AWS ressources. - `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this resource is defined. ## Methods - `addAlias(aliasName: string, options?: AliasOptions): Alias` — 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, }); ``` **Parameters** - `aliasName` — The name of the alias. - `options` — Alias options. - `addIngressRule(source: IPeer, port: Port): void` — Adds an ingress rule to allow inbound traffic to access game sessions on this fleet. **Parameters** - `source` — A range of allowed IP addresses. - `port` — The port range used for ingress traffic. - `addInternalLocation(location: Location): void` — Adds a remote locations to deploy additional instances to and manage as part of the fleet. **Parameters** - `location` — The location to add. - `addLocation(region: string, desiredCapacity?: number, minSize?: number, maxSize?: number): void` — Adds a remote locations to deploy additional instances to and manage as part of the fleet. **Parameters** - `region` — The AWS region to add. - `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource. When set, any cross-stack reference to this resource will use the specified mechanism instead of the global default determined by the `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for selectively weakening specific references to avoid the "deadly embrace" problem without changing the app-wide default. **Parameters** - `strength` — - The reference strength to use for this resource. - `applyRemovalPolicy(policy: RemovalPolicy): void` — Apply the given removal policy to this resource. The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced. The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS account for data recovery and cleanup later (`RemovalPolicy.RETAIN`). - `fromBuildFleetArn(scope: Construct, id: string, buildFleetArn: string): IBuildFleet` (static) — Import an existing fleet from its ARN. - `fromBuildFleetId(scope: Construct, id: string, buildFleetId: string): IBuildFleet` (static) — Import an existing fleet from its identifier. - `fromFleetAttributes(scope: Construct, id: string, attrs: FleetAttributes): IFleet` (static) — Import an existing fleet from its attributes. - `grant(grantee: IGrantable, ...actions: string[]): Grant` — [disable-awslint:no-grants]. - `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct. Use this method instead of `instanceof` to properly detect `Construct` instances, even when the construct library is symlinked. Explanation: in JavaScript, multiple copies of the `constructs` library on disk are seen as independent, completely different libraries. As a consequence, the class `Construct` in each copy of the `constructs` library is seen as a different class, and an instance of one class will not test as `instanceof` the other class. `npm install` will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the `constructs` library can be accidentally installed, and `instanceof` will behave unpredictably. It is safest to avoid using `instanceof`, and using this type-testing method instead. **Parameters** - `x` — Any object. **Returns:** true if `x` is an object created from a class which extends `Construct`. - `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise. - `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource. - `metric(metricName: string, props?: MetricOptions): Metric` — Return the given named metric for this fleet. - `metricActiveInstances(props?: MetricOptions): Metric` — Instances with `ACTIVE` status, which means they are running active server processes. The count includes idle instances and those that are hosting one or more game sessions. This metric measures current total instance capacity. This metric can be used with automatic scaling. - `metricDesiredInstances(props?: MetricOptions): Metric` — Target number of active instances that GameLift is working to maintain in the fleet. With automatic scaling, this value is determined based on the scaling policies currently in force. Without automatic scaling, this value is set manually. This metric is not available when viewing data for fleet metric groups. - `metricIdleInstances(props?: MetricOptions): Metric` — Active instances that are currently hosting zero (0) game sessions. This metric measures capacity that is available but unused. This metric can be used with automatic scaling. - `metricInstanceInterruptions(props?: MetricOptions): Metric` — Number of spot instances that have been interrupted. - `metricMaxInstances(props?: MetricOptions): Metric` — Maximum number of instances that are allowed for the fleet. A fleet's instance maximum determines the capacity ceiling during manual or automatic scaling up. This metric is not available when viewing data for fleet metric groups. - `metricMinInstances(props?: MetricOptions): Metric` — Minimum number of instances allowed for the fleet. A fleet's instance minimum determines the capacity floor during manual or automatic scaling down. This metric is not available when viewing data for fleet metric groups. - `metricPercentIdleInstances(props?: MetricOptions): Metric` — Percentage of all active instances that are idle (calculated as IdleInstances / ActiveInstances). This metric can be used for automatic scaling. - `toString(): string` — Returns a string representation of this construct. - `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct. Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple `with()` calls if subsequent mixins should apply to added constructs.