diff --git a/assets/contributors.csv b/assets/contributors.csv index 2427c7a3cf..e9455ae1a3 100644 --- a/assets/contributors.csv +++ b/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,,,,, diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/1-cdk-installation.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/1-cdk-installation.md new file mode 100644 index 0000000000..83d15c30a5 --- /dev/null +++ b/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. + diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/2-cdk-services.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/2-cdk-services.md new file mode 100644 index 0000000000..3d689cee57 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/3-flask-deployment.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/3-flask-deployment.md new file mode 100644 index 0000000000..6dfd1814b8 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/4-github-config.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/4-github-config.md new file mode 100644 index 0000000000..4adbe340f6 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/_index.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/_index.md new file mode 100644 index 0000000000..930373ef71 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/_index.md @@ -0,0 +1,52 @@ +--- +title: Graviton Infrastructure for GitHub Copilot Extensions + +minutes_to_complete: 30 + +who_is_this_for: This is an advanced topic for software developers who want to learn how to deploy all necessary infrastructure on AWS for a GitHub Copilot Extension. + +learning_objectives: + - Understand the AWS services needed to host a GitHub Copilot Extension + - Create an AWS CDK (Cloud Development Kit) deployment for the required AWS services + - Add your newly generated endpoints to the GitHub app you previously created + +prerequisites: + - The [Build a GitHub Copilot Extension in Python](../gh-copilot-simple/) Learning Path. + - Understanding of IoC (Infrastructure as Code) + - A GitHub account + - A linux-based computer with npm, Python, and the AWS CLI installed + +author: Joe Stech + +### Tags +skilllevels: Advanced +subjects: ML +armips: + - Neoverse +tools_software_languages: + - Python + - AWS CDK + - GitHub +operatingsystems: + - Linux + + + +further_reading: + - resource: + title: About building Copilot Extensions + link: https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions/ + type: documentation + - resource: + title: Copilot Extensions repository + link: https://github.com/copilot-extensions/ + type: documentation + + + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/_next-steps.md new file mode 100644 index 0000000000..c3db0de5a2 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/configure.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/configure.png new file mode 100644 index 0000000000..1ace61c923 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension-deployment/configure.png differ