diff --git a/docs/media/diagrams/perforce_complete_example.drawio b/docs/media/diagrams/perforce_complete_example.drawio new file mode 100644 index 00000000..5459899d --- /dev/null +++ b/docs/media/diagrams/perforce_complete_example.drawio @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/images/perforce-complete-example.png b/docs/media/images/perforce-complete-example.png new file mode 100644 index 00000000..65c03b01 Binary files /dev/null and b/docs/media/images/perforce-complete-example.png differ diff --git a/docs/modules/perforce/examples/complete.md b/docs/modules/perforce/examples/complete.md index 10190cd6..01520587 100644 --- a/docs/modules/perforce/examples/complete.md +++ b/docs/modules/perforce/examples/complete.md @@ -1,13 +1,69 @@ # Perforce Complete Example -This example provisions [Helix Core](https://www.perforce.com/products/helix-core), [Helix Swarm](https://www.perforce.com/products/helix-swarm), and the [Helix Authentication Service](https://www.perforce.com/downloads/helix-authentication-service). It also configures security groups for each of these modules to allow inter-service communication. This example takes a single input variable:`root_domain_name` is expected to correspond to an existing [AWS Route53 hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/route-53-concepts.html#route-53-concepts-hosted-zone). This hosted zone is used for provisioning DNS records used for external and internal routing, and enables this example to create validated SSL certificates on your behalf. +This complete example configuration deploys [**Perforce Helix Core**](https://www.perforce.com/products/helix-core), +[**Perforce Helix Swarm**](https://www.perforce.com/products/helix-swarm), and [**Perforce +Helix Authentication Service**](https://www.perforce.com/downloads/helix-authentication-service) into a new Virtual +Private Cloud. It is designed to be used as a starting point for +your Perforce Helix Core deployment. -If you do not have a domain yet you can [register one through Route53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html#domain-register-procedure-section). +## Architecture -If you already have a domain with a different domain registrar you can leverage Route53 for DNS services. [Please review the documentation for migrating to Route53 as your DNS provider.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/MigratingDNS.html) +![Perforce Example Architecture](../../../media/images/perforce-complete-example.png) -If you own the domain: "example.com" this example will deploy Helix Core to "core.helix.example.com" and Helix Swarm to "swarm.helix.example.com" - this can be modified from the `dns.tf` file. +## Deployment -## Deployment Architecture +This example configuration can be used out of the box and takes only a single variable: `root_domain_name` corresponds +to the fully qualified domain name of an existing public hosted zone in the AWS account where you are deploying this +reference architecture. The deployment steps below will get you up and running. -![Perforce Example Architecture](../../../media/images/perforce-complete-example.jpg) +1. You will need the Cloud Game Development Toolkit's Perforce Helix Core Amazon Machine Image. This Amazon Machine + Image (AMI) can be build using + our [provided Packer template](https://github.com/aws-games/cloud-game-development-toolkit/tree/main/assets/packer/perforce/helix-core). + This example uses the ARM64 version of this AMI, and + leverages Amazon Graviton for the Helix Core instance. Follow our documentation for provisioning this AMI in your AWS + account. +2. Next, you will need to ensure you have an [Amazon Route 53](https://aws.amazon.com/route53/) hosted zone created in + your account for a domain name + that you already own. This example configuration creates DNS records and a private hosted zone for you, but this + pre-requisite hosted zone is necessary for certificate creation. If you do not wish to use the provided DNS resources + you will need to customize this example. +3. Once you have completed these pre-requisites you are ready to deploy the infrastructure: + + ```shell + terraform apply -var "root_domain_name=" + ``` + +4. Review the plan provided by the above command. When you are ready to deploy you can confirm by typing "yes" on the + command line. Terraform will take a few minutes to provision everything. When it completes, you are ready to proceed + with testing. +5. By default, none of the deployed resources are available on the public internet. This is to prevent unintended + security violations. You can update the security group for the Perforce Network Load balancer through the console, or + add the following rules to the example configuration in [ + `security.tf`](https://github.com/aws-games/cloud-game-development-toolkit/blob/main/modules/perforce/examples/complete/security.tf): + + ```terraform + # Grants access on HTTPS port for Helix Swarm and Helix Authentication + resource "aws_vpc_security_group_ingress_rule" "private_perforce_https_ingress" { + security_group_id = aws_security_group.perforce_network_load_balancer.id + description = "Enables private access to Perforce web services." + from_port = 443 + to_port = 443 + ip_protocol = "TCP" + cidr_ipv4 = "/32" + } + + # Grants access on Helix Core port + resource "aws_vpc_security_group_ingress_rule" "private_perforce_https_ingress" { + security_group_id = aws_security_group.perforce_network_load_balancer.id + description = "Enables private access to Perforce Helix Core." + from_port = 1666 + to_port = 1666 + ip_protocol = "TCP" + cidr_ipv4 = "/32" + + } + ``` +6. You should now have access to your deployed resources. The URLs for Helix Swarm and Helix Authentication Service are + provided as Terraform outputs and should be visible in your console after a successful deployment. The connection + string for Helix Core is also provided as an output. Use the Helix Core CLI or the P4V application to connect to your + Helix Core server. diff --git a/modules/perforce/examples/complete/outputs.tf b/modules/perforce/examples/complete/outputs.tf new file mode 100644 index 00000000..c91a51f2 --- /dev/null +++ b/modules/perforce/examples/complete/outputs.tf @@ -0,0 +1,14 @@ +output "helix_core_connection_string" { + value = "ssl:perforce.${var.root_domain_name}:1666" + description = "The connection string for the Helix Core server. Set your P4PORT environment variable to this value." +} + +output "helix_swarm_url" { + value = "swarm.perforce.${var.root_domain_name}" + description = "The URL for the Helix Swarm server." +} + +output "helix_authentication_service_admin_url" { + value = "auth.perforce.${var.root_domain_name}/admin" + description = "The URL for the Helix Authentication Service admin page." +}