Graviton Infrastructure for GitHub Copilot Extensions Learning Path

assets/contributors.csv

@@ -63,7 +63,7 @@ Albin Bernhardsson,,,,,
 Przemyslaw Wirkus,,,,,
 Zach Lasiuk,,,,,
 Daniel Nguyen,,,,,
-Joe Stech,Arm,,,,
+Joe Stech,Arm,JoeStech,joestech,,
 visualSilicon,,,,,
 Konstantinos Margaritis,VectorCamp,,,,
 Kieran Hejmadi,,,,,

content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/1-cdk-installation.md

@@ -0,0 +1,47 @@
+---
+title: CDK installation
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## What is AWS CDK?
+
+AWS CDK is an AWS-native Infrastructure as Code tool that allows cloud engineers to write IaC templates in many different languages. Regardless of the language used, all CDK code eventually transpiles to TypeScript, and the TypeScript generates CloudFormation templates, which then deploy the specified resources.
+
+This Learning Path will use the Python flavor of AWS CDK, because the Copilot Extension that will be deployed is also written in Python. Writing both IaC and application code in the same language is helpful for certain teams, especially those without dedicated platform engineers.
+
+## How do I install AWS CDK?
+
+To install the required packages, you will need npm and Python installed. Next, run
+
+```bash
+npm install -g aws-cdk
+```
+
+To verify that the installation was successful, run
+
+```bash
+cdk --version
+```
+
+You should see a version number returned, signifying success.
+
+After the CDK CLI is installed, you can use it to create a new Python CDK environment:
+
+```bash
+mkdir copilot-extension-deployment
+cd copilot-extension-deployment
+cdk init app --language python
+```
+
+This will set up convenient file stubs, as well as create a `requirements.txt` file with the Python CDK libraries required. The `init` command uses the name of the project folder to name various elements of the project. Hyphens in the folder name are converted to underscores. Install the packages in the `requirements.txt`:
+
+```bash
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Now you are ready to specify the AWS services needed for your GitHub Copilot Extension.
+

content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/2-cdk-services.md

@@ -0,0 +1,243 @@
+---
+title: Deploying AWS services
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+## What AWS services do I need?
+
+In [the first GitHub Copilot Extension Learning Path](learning-paths/servers-and-cloud-computing/gh-copilot-simple) you ran a GitHub Copilot Extension from a single Linux computer, with the public URL being provided by an ngrok tunnel to your localhost.
+
+In an actual production environment, you'll want:
+
+* A domain that you own with DNS settings that you control (you can get this through AWS Route 53)
+* A load balancer (AWS ALB)
+* An auto-scaling cluster (AWS ASG) in a private virtual cloud subnet (AWS VPC) that you can adjust the size of based on load
+
+In order to use your custom domain with your ALB, you'll also need a custom TLS certificate in order to allow the ALB to do TLS termination before the ALB forwards the packets to your ASG instances.
+
+The following sections will walk you through setting up all these required services in AWS CDK.
+
+## Imports
+
+You will have an auto-generated folder called `copilot_extension_deployment` within the `copilot-extension-deployment` that you previously created. It will contain a file called `copilot_extension_deployment_stack.py`. Open this file, and add the following import lines:
+
+```python
+from aws_cdk import (
+    Stack,
+    aws_ec2 as ec2,
+    aws_elasticloadbalancingv2 as elbv2,
+    aws_autoscaling as autoscaling,
+    aws_iam as iam,
+    CfnOutput,
+    aws_certificatemanager as acm,
+    aws_route53 as route53,
+    aws_route53_targets as targets
+)
+```
+
+Then, within the generated class (`class CopilotExtensionDeploymentStack(Stack):`) in the same file, add all the AWS services needed for your Extension deployment as described in the following sections.
+
+## Virtual Private Cloud (VPC)
+
+The code below will create a VPC with a public and private subnet. These subnets have a CIDR mask of 24, which means you'll get 256 total IPs in each subnet. If you need more than this, adjust accordingly.
+
+```python
+vpc = ec2.Vpc(self, "FlaskStackVPC",
+            max_azs=2,
+            subnet_configuration=[
+                ec2.SubnetConfiguration(
+                    name="Private",
+                    subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+                    cidr_mask=24
+                ),
+                ec2.SubnetConfiguration(
+                    name="Public",
+                    subnet_type=ec2.SubnetType.PUBLIC,
+                    cidr_mask=24
+                )
+            ]
+            )
+```
+
+You'll also need a security group for the EC2 instances:
+
+```python
+security_group = ec2.SecurityGroup(self, "EC2SecurityGroup",
+                                           vpc=vpc,
+                                           allow_all_outbound=True,
+                                           description="Security group for EC2 instances"
+                                           )
+```
+
+## EC2
+
+Once you have your VPC templates set up, you can use them in your EC2 templates.
+
+First, create a User Data script for all the EC2 templates that will launch in your auto-scaling group. This will install an SSM agent and the AWS CLI, for later convenience:
+
+```python
+user_data = ec2.UserData.for_linux()
+user_data.add_commands(
+    "apt-get update",
+    # Install SSM agent
+    "sudo snap install amazon-ssm-agent --classic",
+    "sudo systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service",
+    "sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service",
+    # Install AWS CLI v2
+    "apt install unzip",
+    'curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"',
+    "unzip awscliv2.zip",
+    "sudo ./aws/install",
+    # add any additional commands that you'd like to run on instance launch here
+)
+```
+
+After the launch template, you'll want to get the latest Ubuntu 24.04 Arm AMI:
+
+```python
+ubuntu_arm_ami = ec2.MachineImage.lookup(
+    name="ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-arm64-server-*",
+    owners=["099720109477"],  # Canonical's AWS account ID
+    filters={"architecture": ["arm64"]}
+)
+```
+
+Next create an IAM role that will allow your EC2 instances to use the SSM agent, write logs to CloudWatch, and access AWS S3:
+
+```Python
+ec2_role_name = "Proj-Flask-LLM-ALB-EC2-Role"
+ec2_role = iam.Role(self, "EC2Role",
+                    assumed_by=iam.ServicePrincipal("ec2.amazonaws.com"),
+                    managed_policies=[
+                        iam.ManagedPolicy.from_aws_managed_policy_name("AmazonSSMManagedInstanceCore"),
+                        iam.ManagedPolicy.from_aws_managed_policy_name("CloudWatchAgentServerPolicy"),
+                        iam.ManagedPolicy.from_aws_managed_policy_name("CloudWatchLogsFullAccess"),
+                        iam.ManagedPolicy.from_aws_managed_policy_name("AmazonS3FullAccess")
+                    ],
+                    role_name=ec2_role_name,
+                    )
+```
+
+Now pull all these elements together in the launch template that the ASG will use:
+
+```Python
+launch_template = ec2.LaunchTemplate(self, "LaunchTemplate",
+                                        instance_type=ec2.InstanceType("c8g.xlarge"),
+                                        machine_image=ubuntu_arm_ami,
+                                        user_data=user_data,
+                                        security_group=security_group,
+                                        role=ec2_role,
+                                        detailed_monitoring=True,
+                                        block_devices=[
+                                            ec2.BlockDevice(
+                                                device_name="/dev/sda1",
+                                                volume=ec2.BlockDeviceVolume.ebs(
+                                                    volume_size=50,
+                                                    volume_type=ec2.EbsDeviceVolumeType.GP3,
+                                                    delete_on_termination=True
+                                                )
+                                            )
+                                        ]
+                                        )
+```
+
+Finally, create the ASG, specifying the launch template you just created as the launch template for the EC2 instances within the ASG:
+
+```Python
+asg = autoscaling.AutoScalingGroup(self, "ASG",
+                                    vpc=vpc,
+                                    vpc_subnets=ec2.SubnetSelection(
+                                        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS),
+                                    launch_template=launch_template,
+                                    min_capacity=1,
+                                    max_capacity=1,
+                                    desired_capacity=1
+                                    )
+```
+
+As you can see, you'll want the instances inside your private subnet for security, and you only need one instance to begin with. You can scale manually later on, or create an autoscaling function, depending on your needs.
+
+## Application Load Balancer (ALB)
+
+First, create an ALB using the VPC resources you previously specified, within the PUBLIC subnet:
+
+```Python
+alb = elbv2.ApplicationLoadBalancer(self, "ALB",
+                                vpc=vpc,
+                                internet_facing=True,
+                                vpc_subnets=ec2.SubnetSelection(subnet_type=ec2.SubnetType.PUBLIC)
+                                )
+```
+
+Next add a custom certificate. You'll need to generate this certificate beforehand. If you want to do this from the AWS console, see [Getting Started with AWS Certificate Manager](https://aws.amazon.com/certificate-manager/getting-started/).
+
+Replace `ACM_CERTIFICATE_ARN` with the ARN of your newly created certificate:
+
+```Python
+certificate = acm.Certificate.from_certificate_arn(
+    self,
+    "Certificate",
+    os.environ["ACM_CERTIFICATE_ARN"]
+)
+```
+
+Next configure a listener for the ALB that uses the certificate and adds the ASG as a target, listening on port 8080 (this is where you'll serve your Flask app):
+
+```Python
+# Add a listener to the ALB with HTTPS
+listener = alb.add_listener("HttpsListener",
+                            port=443,
+                            certificates=[certificate],
+                            ssl_policy=elbv2.SslPolicy.RECOMMENDED)
+
+# Add the ASG as a target to the ALB listener
+listener.add_targets("ASGTarget",
+                        port=8080,
+                        targets=[asg],
+                        protocol=elbv2.ApplicationProtocol.HTTP,
+                        health_check=elbv2.HealthCheck(
+                            path="/health",
+                            healthy_http_codes="200-299"
+                        ))
+```
+
+## Custom domain setup in Route 53
+
+The final step in setting up your AWS services is to add an ALB-linked A record to the hosted zone for your domain. This makes sure that when GitHub invokes your API, the DNS is pointed to the IP of your ALB. You will need to replace `HOSTED_ZONE_DOMAIN_NAME` with your hosted zone domain, and replace `SUBDOMAIN_NAME` with the subdomain that maps to the ACM certificate that you generated and used in your ALB.
+
+```Python
+hosted_zone = route53.HostedZone.from_lookup(self, "HostedZone",
+                                                domain_name=os.environ["HOSTED_ZONE_DOMAIN_NAME"],
+                                                )
+
+# Create an A record for the subdomain
+route53.ARecord(self, "ALBDnsRecord",
+                zone=hosted_zone,
+                record_name=os.environ["SUBDOMAIN_NAME"],
+                target=route53.RecordTarget.from_alias(targets.LoadBalancerTarget(alb))
+                )
+```
+
+## How do I deploy?
+
+Once you have added all of the sections above to your `copilot_extension_deployment_stack.py` file, you can deploy your services to AWS. You must first ensure that your CDK environment in AWS is 'bootstrapped', which means that the AWS CDK has created all the resources it needs to use when deploying (IAM roles, an ECR repo for images, and buckets for artifacts). The bootstrap process is a one-time deal, and can generally be done by running:
+
+```bash
+cdk bootstrap aws://123456789012/us-east-1
+```
+
+Replace the AWS account and region with your account and region.
+
+{{% notice Note %}}
+if your organization has governance rules in place regarding naming conventions you'll need a custom bootstrap yaml. To learn more about custom bootstrapping, see the [AWS guide  on Bootstrapping your environment for use with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping-env.html).
+{{% /notice %}}
+
+Once your environment has been bootstrapped, you can run:
+
+```bash
+cdk deploy
+```
+
+from within the directory that includes your stack file. This deployment will take a few minutes, as CloudFormation deploys your resources.

content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/3-flask-deployment.md

@@ -0,0 +1,58 @@
+---
+title: Deploying Flask
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## How do I deploy my Copilot Extension Flask app to my newly created EC2 instance?
+
+In the first GitHub Copilot Extension Learning Path you created a Flask app in the section titled "[How can I create my own private GitHub Copilot Extension?](http://localhost:1313/learning-paths/servers-and-cloud-computing/gh-copilot-simple/run-python/)".
+
+You will deploy this Flask app on your newly created EC2 instance. First, get your EC2 instance ID:
+
+```bash
+aws ec2 describe-instances --filters "Name=tag:Name,Values=CopilotExtensionDeploymentStack/LaunchTemplate" --query "Reservations[*].Instances[*].InstanceId" --output text
+```
+
+Then use that ID to log in with AWS SSM. You must use AWS SSM because your instance is in a private subnet for security purposes, but because the SSM agent is running on the instance, it creates a tunnel that allows you to SSH into the machine with the following command:
+
+```bash
+aws ssm start-session --target [your instance ID]
+```
+
+You should now be able to go through the steps in "[How can I create my own private GitHub Copilot Extension?](http://localhost:1313/learning-paths/servers-and-cloud-computing/gh-copilot-simple/run-python/)" to create your Flask app, create a Python virtual environment, and install the appropriate packages.
+
+The only two changes you'll make are to add a health check endpoint (for the ALB health check), and to run your app on 0.0.0.0 port 8080, which the ALB is listening for.
+
+First, add the following endpoint to your main flask file:
+
+```Python
+@app.route('/health')
+def health():
+    return Response(status=200)
+```
+
+Next, add the `host` argument to the `app.run` call at the end of the file and update the port number. The final result should look like this:
+
+```Python
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=8080)
+```
+
+This will expose your app to the port that you set up your ALB listener to listen on.
+
+Run the simple extension:
+
+```Python
+python ./simple-extension.py
+```
+
+You should now be able to navigate to your API subdomain from any browser and see
+
+```text
+"Hello! Welcome to the example GitHub Copilot Extension in Python!"
+```
+
+Your API is now complete and ready to be configured in your GitHub Application.

content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/4-github-config.md

@@ -0,0 +1,25 @@
+---
+title: Configuring GitHub
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## How do I configure my GitHub Application to use my API?
+
+Open the GitHub App that you created in [the first GitHub Copilot Extension Learning Path](learning-paths/servers-and-cloud-computing/gh-copilot-simple).
+
+Navigate to the 'Copilot' tab, and add your URL to the field under the 'Agent Definition' section:
+
+ ![Configure URL](configure.png)
+
+You will also want to change the 'Callback URL' under the General tab. This is the full URL to redirect to after a user authorizes an installation.
+
+## Test your Extension
+
+You are now ready to test your productionized Extension. For guidance on testing, see [Test your Copilot Extension](http://localhost:1313/learning-paths/servers-and-cloud-computing/gh-copilot-simple/copilot-test/) in the previous Copilot Extension Learning Path.
+
+## Next Steps
+
+You are now ready to build a more advanced Copilot Extension that uses RAG techniques in [Create a RAG-based GitHub Copilot Extension in Python](../copilot-extension).