Provision AWS resources with CloudFormation

Provision AWS resources for a BugSnag On-premise high availability cluster with CloudFormation.

Prerequisites

In order to provision AWS resources you’ll need the following:

AWS SSH key pair
IAM role for CloudFormation and a Lambda function to assume; the role will need a managed policy detailed in our IAM role reference
A Route 53 hosted zone (if you want the template to create DNS records with given names for load balancers)
SSL/TLS certificates in AWS ACM (for load balancers)

Provision AWS resources

Provisioning can be done either through the CloudFormation UI or through the AWS CLI.

Initial creation will take some time, usually around 20-25 minutes as this sets up a Kubernetes cluster, nodes, load balancers, ECR repositories, and an EC2 instance so everything is ready to install BugSnag.

Option 1: Provision using CloudFormation UI

Create a new CloudFormation stack using the following template URL:

https://s3.amazonaws.com/bugsnag-onprem-public/cloudformation/v1.6.1/bugsnag-onprem-eks.yaml
Enter a stack name and complete the parameters listed on the page.

Option 2: Provision using AWS CLI

Run the following to create the stack using the AWS CLI, updating the parameters as appropriate for your environment:

aws cloudformation create-stack \
  --stack-name bugsnag-onprem \
  --capabilities CAPABILITY_IAM \
  --template-url https://bugsnag-onprem-public.s3.amazonaws.com/cloudformation/v1.6.1/bugsnag-onprem-eks.yaml \
  --role-arn arn:aws:iam::90000:role/bugsnag-onprem-execution-role \
  --parameters \
    ParameterKey=ExecutionRole,ParameterValue=arn:aws:iam::90000:role/bugsnag-onprem-execution-role \
    ParameterKey=ClusterName,ParameterValue=bugsnag-onprem-1 \
    ParameterKey=NodeImageId,ParameterValue=ami-1234567890abcdef1 \
    ParameterKey=KeyName,ParameterValue=bugsnag-onprem-key \
    ParameterKey=HostedZoneId,ParameterValue=ABC123DEF456 \
    ParameterKey=EventServerHostname,ParameterValue=bugsnag-notify.example.com \
    ParameterKey=EventServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=GrafanaHostname,ParameterValue=bugsnag-grafana.example.com \
    ParameterKey=GrafanaCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=HooksServerHostname,ParameterValue=bugsnag-hooks.example.com \
    ParameterKey=HooksServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=DashboardHostname,ParameterValue=bugsnag-dashboard.example.com \
    ParameterKey=DashboardCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=ReleaseServerHostname,ParameterValue=bugsnag-build.example.com \
    ParameterKey=ReleaseServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=SessionServerHostname,ParameterValue=bugsnag-sessions.example.com \
    ParameterKey=SessionServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=UploadServerHostname,ParameterValue=bugsnag-upload.example.com \
    ParameterKey=UploadServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=ConfigServerSecurityGroup,ParameterValue=sg-12ab34cd \
    ParameterKey=ConfigServerSubnetID,ParameterValue=subnet-12ab34cd \
    ParameterKey=ConfigServerKeyName,ParameterValue=config-server-key \
    ParameterKey=ConfigServerImageId,ParameterValue=ami-1234567890abcdef1 \
    ParameterKey=ECRRepositoryNamespace,ParameterValue=namespace

If you are using BugSnag performance, include these additional parameters:

    ParameterKey=CreateClientPerformanceResources,ParameterValue=true \
    ParameterKey=TraceServerHostname,ParameterValue=bugsnag-otlp.example.com \
    ParameterKey=TraceServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd

Parameter	Description
`NodeImageId`	See https://docs.aws.amazon.com/eks/latest/userguide/retrieve-ami-id.html for more information about the AMI to use.
`ConfigServerImageId`	See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html for more information about the AMI to use.

Set up the config server

The stack creates a dedicated config server for managing installation and upgrades that has all the tools required for installing BugSnag.

Details of this server are included in the stack outputs and can be used to connect via SSH.

After connecting to the config server, there are some final manual steps that must be completed:

Configure the AWS CLI to access the ECR repository and EKS Kubernetes cluster:
```
aws configure
```

Configure kubectl to connect to the Kubernetes cluster:

aws eks update-kubeconfig --region <REGION> --name <CLUSTER_NAME> --role-arn <ROLE_ARN>

Parameter	Description
`<REGION>`	AWS region in which your stack/cluster is provisioned.
`<CLUSTER_NAME>`	`ClusterName` parameter set when creating the stack.
`<ROLE_ARN>`	`ExecutionRole` parameter set when creating the stack.

Fetch the credentials required to push images to your ECR docker registry:
```
aws ecr get-login-password
```

Push images to private registry

If you enabled the private deployment option you must make the kubernetes cluster-autoscaler and metrics-server images available in your private registry.

From the config server, log in to your private registry and run the following commands:

docker pull registry.k8s.io/autoscaling/cluster-autoscaler:v1.24.1
docker pull registry.k8s.io/metrics-server/metrics-server:v0.7.0

docker tag registry.k8s.io/autoscaling/cluster-autoscaler:v1.24.1 <REGISTRY>/cluster-autoscaler:v1.24.1
docker tag registry.k8s.io/metrics-server/metrics-server:v0.7.0 <REGISTRY>/metrics-server:v0.7.0

docker push <REGISTRY>/cluster-autoscaler:v1.24.1
docker push <REGISTRY>/metrics-server:v0.7.0

kubectl rollout restart deploy metrics-server cluster-autoscaler -n kube-system

Placeholder	Description
`<REGISTRY>`	Address of your private registry as output by the CloudFormation stack.

Install BugSnag

Now that your cluster is ready, follow the guide to complete a standard or airgapped installation.