Perforce on AWS Terraform Module¶
For a video walkthrough demonstrating how to use this module, see this YouTube Video:
Features¶
- Dynamic creation and configuration of P4 Server (formerly Helix Core)
- Dynamic creation and configuration of P4 Code Review (formerly Helix Swarm)
- Dynamic creation and configuration of P4Auth (formerly Helix Authentication Service)
Architecture¶
Full example using AWS Route53 Public Hosted Zone¶
Prerequisites¶
- Existing DNS Configured
- To use this module, you must have an existing domain and related DNS configuration. The example at
/examples/create-resources-complete
demonstrates how to provision resources while using Amazon Route53 ( recommended) as the DNS provider. This will make deployment and management easier. - You may optionally use a 3rd party DNS provider, however you must create records in your DNS provider to route to
the endpoints that you will create for each component when using the module (e.g.
perforce.example.com
,review.perforce.example.com
,auth.perforce.example.com
). The module has variables that you can use to customize the subdomains for the services (P4 Server, P4 Code Review, P4Auth), however if not set, the defaults mentioned above will be used. Ensure you create these records to allow users to connect to the services once provisioned in AWS. - Note: When using either of the two options mentioned above, by default the module will create a Route53 Private Hosted Zone. This is used for internal communication and routing of traffic between P4 Server, P4 Code Review, and P4Auth.
- To use this module, you must have an existing domain and related DNS configuration. The example at
-
SSL TLS Certificate
- You must have an existing SSL/TLS certificate, or create one during deployment alongside the other resources the
module will create. This is used to provide secure connectivity to the Perforce resources that will be running in
AWS. The certificate will be used by the Application Load Balancer (ALB) that the module will deploy for you. If
using Amazon Route53, see the example at
/examples/create-resources-complete
to see how to create the related certificate in Amazon Certificate Manager (ACM). Using a Route53 as the DNS provider makes this process a bit easier, as ACM can automatically create the required CNAME records needed for DNS validation (a process required to verify DNS ownership) if you are also using Amazon Route53. - If using an 3rd party DNS provider, you must add these CNAME records manually (in addition to the other records mentioned above for general DNS purposes). If you would prefer to use a 3rd party to create the SSL/TLS certificate, the module allows you to import this into ACM to be used for the other components that will be deployed (such as the internal ALB). You may also use Email validation to validate DNS ownership.
- You must have an existing SSL/TLS certificate, or create one during deployment alongside the other resources the
module will create. This is used to provide secure connectivity to the Perforce resources that will be running in
AWS. The certificate will be used by the Application Load Balancer (ALB) that the module will deploy for you. If
using Amazon Route53, see the example at
-
Existing Perforce Amazon Machine Image (AMI)
- As mentioned in the architecture, an Amazon EC2 instance is used for the P4 Server, and this instance must be be
provisioned using an AMI that is configured for Perforce. To expedite this process, we have
sample HashiCorp Packer templates provided in
the AWS Cloud Game Development Toolkit repository
that you can use to create a Perforce AMI in your AWS Account. Note: You must also reference the
p4_configure.sh
andp4_setup.sh
files that are in this directory, as these are used to configure the P4 Commit Server. These are already referenced in theperforce_arm64.pkr.hcl
andperforce_x86.pkr.hcl
packer templates that are available for use.
- As mentioned in the architecture, an Amazon EC2 instance is used for the P4 Server, and this instance must be be
provisioned using an AMI that is configured for Perforce. To expedite this process, we have
sample HashiCorp Packer templates provided in
the AWS Cloud Game Development Toolkit repository
that you can use to create a Perforce AMI in your AWS Account. Note: You must also reference the
Examples¶
For example configurations, please see the examples.
Deployment Instructions¶
- Create the Perforce AMI in your AWS account using one of the supplied Packer templates. Ensure you use the Packer
template that aligns with the architecture type (e.g. arm64) of the EC2 instance you wish to create. On the Terraform
side, you may also set this using the
instance_architecture
variable. Ensure yourinstance_type
is supported for your desiredinstance_architecture
. For a full list of this mapping, see the AWS Docs for EC2 Naming Conventions. You can also use the interactive chart on Instances by Vantage.
IMPORTANT: By default, the module will create compute resources with x86_64
architecture. Ensure you use this
corresponding Packer template unless you set the instance_architecture
variable to arm64
or the deployment will
fail. Also, unless explicitly set, the Packer templates are configured to build the AMI in whichever AWS region your
current credentials are set to (e.g. us-east-1
) which will also be the same AWS region your Terraform resources are
deployed to unless you explicitly set this. Ensure the AMI is available in the AWS Region you will use the module to
deploy resources into.
To deploy the template (x86_64
) with Packer, do the following (while in the /assets/perforce/p4-server directory
)
packer init perforce_x86.pkr.hcl
packer validate perforce_x86.pkr.hcl
packer build perforce_x86.pkr.hcl
-
Reference your existing fully qualified domain name within each related Perforce service you would like to provision (e.g.
p4_server_config
,p4_auth_config
,p4_code_review_config
) using thefully_qualified_domain_name
variable. We recommend abstracting this t a local value such aslocal.fully_qualified_domain_name
to ensure this value is consistent across the modules. The module will automatically configure Perforce using default subdomains ofperforce.<your-domain-name>
for P4 Server,auth.perforce.<your-domain-name
for P4 Auth, andreview.perforce.<your-domain-name
for P4 Code Review. You will also need to create DNS records that will route traffic destined for these domains in the following manner:- Traffic destined for P4 Server will need to route to the Elastic IP (EIP) that is associated with the P4
Server EC2 Instance. By default, this will be using a subdomain named
perforce
. In your DNS provider, create an A record namedperforce.<your-domain-name>
and have it route traffic to the EIP. This value is available as a Terraform output for your convenience. - Traffic destined for
*.perforce.<your-domain-name>
will need to route to the DNS name of the Network Load Balancer (NLB) that the module creates. In your DNS provider, create a CNAME record that routes traffic to NLB. This value is available as a Terraform output for your convenience. - Note: If using Amazon Route53 as your DNS provider, the example at
/examples/create-resources-complete
shows you have to leverage Terraform to automatically create these records in an existing Route53 Public Hosted Zone, as well as how to create the certificate in Amazon Certificate Manager (ACM).
- Traffic destined for P4 Server will need to route to the Elastic IP (EIP) that is associated with the P4
Server EC2 Instance. By default, this will be using a subdomain named
-
Make any other modifications as desired (such as referencing existing VPC resources) and run
terraform init
to initialize Terraform in the current working directory,terraform plan
to create and validate the execution plan of the resources that will be created, and finallyterraform apply
to create the resources in your AWS Account. - Once the resources have finished provisioning successfully, you will need to modify your inbound Security Group Rules
on the P4 Commit Server Instance to allow TCP traffic from your public IP on port 1666 (the perforce default port).
This is necessary to allow your local machine(s) to connect to the P4 Commit Server. Optionally, you can pass in an entire security group to also add to the resource. The complete example demonstrates how to use the
existing_security_groups
variable to accomplish this.- Note: You may use other means to allow traffic to reach this EC2 Instance (Customer-managed prefix list, VPN to the VPC that the instance is running in, etc.) but regardless, it is essential that you have the security group rules set configured correctly to allow access.
- Next, modify your inbound Security Group rules for the Perforce Network Load Balancer (NLB) to allow traffic from
HTTPS (port 443) from your public IP address/ This is to provide access to the P4 Code Review and P4Auth services
that are running behind the Application Load Balancer (ALB). Optionally, you can pass in an entire security group to also add to the resource. The complete example demonstrates how to use the
existing_security_groups
variable to accomplish this.- Note: You may use other means to allow traffic to reach this the Network Load Balancer (Customer-managed prefix list, VPN to the VPC that the instance is running in, etc.) but regardless, it is essential that you have the security group rules set configured correctly to allow access.
- IMPORTANT: Ensure your networking configuration is correct, especially in terms of any public or private subnets that you reference. This is very important for the internal routing between the P4 resources, as well as the related Security Groups. Failure to set these correctly may cause a variety of connectivity issues such as web pages not loading, NLB health checks failing, etc.
- Use the provided Terraform outputs to quickly find the URL for P4Auth, P4 Code Review. If you haven't modified the default values, relevant values for the P4 Server default username/password, and the P4 Code Review default username/password were created for you and are stored in AWS Secrets Manager.
- In P4V, use the url of
ssl:<your-supplied-root-domain>:1666
and the username and password stored in AWS Secrets Manager to gain access to the commit server. - At this point, you should be able to access your P4 Commit Server (P4), and visit the URLs for P4 Code Review (P4 Code Review) and P4Auth (P4Auth).
Requirements¶
Name | Version |
---|---|
terraform | >= 1.0 |
aws | 5.97.0 |
awscc | 1.34.0 |
local | 2.5.2 |
null | 3.2.4 |
random | 3.7.1 |
Providers¶
Name | Version |
---|---|
aws | 5.97.0 |
null | 3.2.4 |
random | 3.7.1 |
Modules¶
Name | Source | Version |
---|---|---|
p4_auth | ./modules/p4-auth | n/a |
p4_code_review | ./modules/p4-code-review | n/a |
p4_server | ./modules/p4-server | n/a |
Resources¶
Inputs¶
Name | Description | Type | Default | Required |
---|---|---|---|---|
certificate_arn | The ARN of the ACM certificate to be used with the HTTPS listener for the NLB. | string |
null |
no |
create_default_sgs | Whether to create default security groups for the Perforce resources. | bool |
true |
no |
create_route53_private_hosted_zone | Whether to create a private Route53 Hosted Zone for the Perforce resources. This private hosted zone is used for internal communication between the P4 Server, P4 Auth Service, and P4 Code Review Service. | bool |
true |
no |
create_shared_application_load_balancer | Whether to create a shared Application Load Balancer for the Perforce resources. | bool |
true |
no |
create_shared_network_load_balancer | Whether to create a shared Network Load Balancer for the Perforce resources. | bool |
true |
no |
enable_shared_alb_deletion_protection | Enables deletion protection for the shared Application Load Balancer for the Perforce resources. | bool |
false |
no |
enable_shared_lb_access_logs | Enables access logging for both the shared NLB and shared ALB. Defaults to false. | bool |
false |
no |
existing_ecs_cluster_name | The name of an existing ECS cluster to use for the Perforce server. If omitted a new cluster will be created. | string |
null |
no |
existing_security_groups | A list of existing security group IDs to attach to the shared network load balancer. | list(string) |
[] |
no |
p4_auth_config | # General name: "The string including in the naming of resources related to P4Auth. Default is 'p4-auth'." project_prefix : "The project prefix for the P4Auth service. Default is 'cgd'." environment : "The environment where the P4Auth service will be deployed. Default is 'dev'." enable_web_based_administration: "Whether to de enable web based administration. Default is 'true'." debug : "Whether to enable debug mode for the P4Auth service. Default is 'false'." fully_qualified_domain_name : "The FQDN for the P4Auth Service. This is used for the P4Auth's Perforce configuration." # Compute cluster_name : "The name of the ECS cluster where the P4Auth service will be deployed. Cluster is not created if this variable is null." container_name : "The name of the P4Auth service container. Default is 'p4-auth-container'." container_port : "The port on which the P4Auth service will be listening. Default is '3000'." container_cpu : "The number of CPU units to reserve for the P4Auth service container. Default is '1024'." container_memory : "The number of CPU units to reserve for the P4Auth service container. Default is '4096'." # Storage & Logging cloudwatch_log_retention_in_days : "The number of days to retain the P4Auth service logs in CloudWatch. Default is 365 days." # Networking create_defaults_sgs : "Whether to create default security groups for the P4Auth service." internal : "Set this flag to true if you do not want the P4Auth service to have a public IP." create_default_role : "Whether to create the P4Auth default IAM Role. Default is set to true." custom_role : "ARN of a custom IAM Role you wish to use with P4Auth." admin_username_secret_arn : "Optionally provide the ARN of an AWS Secret for the P4Auth Administrator username." admin_password_secret_arn : "Optionally provide the ARN of an AWS Secret for the P4Auth Administrator password." |
object({ |
null |
no |
p4_code_review_config | # General name: "The string including in the naming of resources related to P4 Code Review. Default is 'p4-code-review'." project_prefix : "The project prefix for the P4 Code Review service. Default is 'cgd'." environment : "The environment where the P4 Code Review service will be deployed. Default is 'dev'." debug : "Whether to enable debug mode for the P4 Code Review service. Default is 'false'." fully_qualified_domain_name : "The FQDN for the P4 Code Review Service. This is used for the P4 Code Review's Perforce configuration." # Compute container_name : "The name of the P4 Code Review service container. Default is 'p4-code-review-container'." container_port : "The port on which the P4 Code Review service will be listening. Default is '3000'." container_cpu : "The number of CPU units to reserve for the P4 Code Review service container. Default is '1024'." container_memory : "The number of CPU units to reserve for the P4 Code Review service container. Default is '4096'." pd4_port : "The full URL you will use to access the P4 Depot in clients such P4V and P4Admin. Note, this typically starts with 'ssl:' and ends with the default port of ':1666'." existing_redis_connection : "The existing Redis connection for the P4 Code Review service." # Storage & Logging cloudwatch_log_retention_in_days : "The number of days to retain the P4 Code Review service logs in CloudWatch. Default is 365 days." # Networking & Security create_default_sgs : "Whether to create default security groups for the P4 Code Review service." internal : "Set this flag to true if you do not want the P4 Code Review service to have a public IP." create_default_role : "Whether to create the P4 Code Review default IAM Role. Default is set to true." custom_role : "ARN of a custom IAM Role you wish to use with P4 Code Review." super_user_password_secret_arn : "Optionally provide the ARN of an AWS Secret for the P4 Code Review Administrator username." super_user_username_secret_arn : "Optionally provide the ARN of an AWS Secret for the P4 Code Review Administrator password." p4d_p4_code_review_user_secret_arn : "Optionally provide the ARN of an AWS Secret for the P4 Code Review user's username." p4d_p4_code_review_password_secret_arn : "Optionally provide the ARN of an AWS Secret for the P4 Code Review user's password." p4d_p4_code_review_user_password_arn : "Optionally provide the ARN of an AWS Secret for the P4 Code Review user's password." enable_sso : "Whether to enable SSO for the P4 Code Review service. Default is set to false." # Caching elasticache_node_count : "The number of Elasticache nodes to create for the P4 Code Review service. Default is '1'." elasticache_node_type : "The type of Elasticache node to create for the P4 Code Review service. Default is 'cache.t4g.micro'." |
object({ |
null |
no |
p4_server_config | # - General - name: "The string including in the naming of resources related to P4 Server. Default is 'p4-server'" project_prefix: "The project prefix for this workload. This is appended to the beginning of most resource names." environment: "The current environment (e.g. dev, prod, etc.)" auth_service_url: "The URL for the P4Auth Service." fully_qualified_domain_name = "The FQDN for the P4Auth Service. This is used for the P4 Server's Perforce configuration." # - Compute - lookup_existing_ami : "Whether to lookup the existing Perforce P4 Server AMI." ami_prefix: "The AMI prefix to use for the AMI that will be created for P4 Server." instance_type: "The instance type for Perforce P4 Server. Defaults to c6g.large." instance_architecture: "The architecture of the P4 Server instance. Allowed values are 'arm64' or 'x86_64'." IMPORTANT: "Ensure the instance family of the instance type you select supports the instance_architecture you select. For example, 'c6in' instance family only works for 'x86_64' architecture, not 'arm64'. For a full list of this mapping, see the AWS Docs for EC2 Naming Conventions: https://docs.aws.amazon.com/ec2/latest/instancetypes/instance-type-names.html" p4_server_type: "The Perforce P4 Server server type. Valid values are 'p4d_commit' or 'p4d_replica'." unicode: "Whether to enable Unicode configuration for P4 Server the -xi flag for p4d. Set to true to enable Unicode support." selinux: "Whether to apply SELinux label updates for P4 Server. Don't enable this if SELinux is disabled on your target operating system." case_sensitive: "Whether or not the server should be case insensitive (Server will run '-C1' mode), or if the server will run with case sensitivity default of the underlying platform. False enables '-C1' mode. Default is set to true." plaintext: "Whether to enable plaintext authentication for P4 Server. This is not recommended for production environments unless you are using a load balancer for TLS termination. Default is set to false." # - Storage - storage_type: "The type of backing store. Valid values are either 'EBS' or 'FSxN'" depot_volume_size: "The size of the depot volume in GiB. Defaults to 128 GiB." metadata_volume_size: "The size of the metadata volume in GiB. Defaults to 32 GiB." logs_volume_size: "The size of the logs volume in GiB. Defaults to 32 GiB." # - Networking & Security - instance_subnet_id: "The subnet where the P4 Server instance will be deployed." create_default_sg : "Whether to create a default security group for the P4 Server instance." existing_security_groups: "A list of existing security group IDs to attach to the P4 Server load balancer." internal: "Set this flag to true if you do not want the P4 Server instance to have a public IP." super_user_password_secret_arn: "If you would like to manage your own super user credentials through AWS Secrets Manager provide the ARN for the super user's username here. Otherwise, the default of 'perforce' will be used." super_user_username_secret_arn: "If you would like to manage your own super user credentials through AWS Secrets Manager provide the ARN for the super user's password here." create_default_role: "Optional creation of P4 Server default IAM Role with SSM managed instance core policy attached. Default is set to true." custom_role: "ARN of a custom IAM Role you wish to use with P4 Server." |
object({ |
null |
no |
project_prefix | The project prefix for this workload. This is appended to the beginning of most resource names. | string |
"cgd" |
no |
route53_private_hosted_zone_name | The name of the private Route53 Hosted Zone for the Perforce resources. | string |
null |
no |
s3_enable_force_destroy | Enables force destroy for the S3 bucket for both the shared NLB and shared ALB access log storage. Defaults to true. | bool |
true |
no |
shared_alb_access_logs_prefix | Log prefix for shared ALB access logs. | string |
"perforce-alb-" |
no |
shared_alb_subnets | A list of subnets to attach to the shared application load balancer. | list(string) |
null |
no |
shared_application_load_balancer_name | The name of the shared Application Load Balancer for the Perforce resources. | string |
"p4alb" |
no |
shared_ecs_cluster_name | The name of the ECS cluster to use for the shared ECS Cluster. | string |
"perforce-cluster" |
no |
shared_lb_access_logs_bucket | ID of the S3 bucket for both the shared NLB and shared ALB access log storage. If access logging is enabled and this is null the module creates a bucket. | string |
null |
no |
shared_network_load_balancer_name | The name of the shared Network Load Balancer for the Perforce resources. | string |
"p4nlb" |
no |
shared_nlb_access_logs_prefix | Log prefix for shared NLB access logs. | string |
"perforce-nlb-" |
no |
shared_nlb_subnets | A list of subnets to attach to the shared network load balancer. | list(string) |
null |
no |
tags | Tags to apply to resources. | map(any) |
{ |
no |
vpc_id | The VPC ID where the Perforce resources will be deployed. | string |
n/a | yes |
Outputs¶
Name | Description |
---|---|
p4_auth_alb_dns_name | The DNS name of the P4Auth ALB. |
p4_auth_alb_security_group_id | Security group associated with the P4Auth load balancer. |
p4_auth_alb_zone_id | The hosted zone ID of the P4Auth ALB. |
p4_auth_perforce_cluster_name | Name of the ECS cluster hosting P4Auth. |
p4_auth_service_security_group_id | Security group associated with the ECS service running P4Auth. |
p4_auth_target_group_arn | The service target group for the P4Auth. |
p4_code_review_alb_dns_name | The DNS name of the P4 Code Review ALB. |
p4_code_review_alb_security_group_id | Security group associated with the P4 Code Review load balancer. |
p4_code_review_alb_zone_id | The hosted zone ID of the P4 Code Review ALB. |
p4_code_review_perforce_cluster_name | Name of the ECS cluster hosting P4 Code Review. |
p4_code_review_service_security_group_id | Security group associated with the ECS service running P4 Code Review. |
p4_code_review_target_group_arn | The service target group for the P4 Code Review. |
p4_server_eip_id | The ID of the Elastic IP associated with your P4 Server instance. |
p4_server_eip_public_ip | The public IP of your P4 Server instance. |
p4_server_instance_id | Instance ID for the P4 Server instance |
p4_server_lambda_link_name | The name of the Lambda link for the P4 Server instance to use with FSxN. |
p4_server_private_ip | Private IP for the P4 Server instance |
p4_server_security_group_id | The default security group of your P4 Server instance. |
p4_server_super_user_password_secret_arn | The ARN of the AWS Secrets Manager secret holding your P4 Server super user's username. |
p4_server_super_user_username_secret_arn | The ARN of the AWS Secrets Manager secret holding your P4 Server super user's password. |
shared_application_load_balancer_arn | The ARN of the shared application load balancer. |
shared_network_load_balancer_arn | The ARN of the shared network load balancer. |
END_TF_DOCS |