AWS EC2 Instances

Gloo Gateway allows you to create Upstreams from groups of EC2 instances.

Before jumping into the guide, let’s become familiar with the EC2 Upstream specification.


Sample EC2 Upstream Config

The Upstream config below creates an Upstream that load balances to all EC2 instances that both match the filter criteria and are available to a user with the credentials provided by the secret.

apiVersion: gloo.solo.io/v1
kind: Upstream
metadata:
  annotations:
  name: my-ec2-upstream
  namespace: gloo-system
spec:
  awsEc2:
    filters:
    - key: some-key
    - kvPair:
        key: some-other-key
        value: some-value
    region: us-east-1
    publicIp: true
    secretRef:
      name: my-aws-secret
      namespace: default
    roleArn: arn:aws:iam::123456789012:role/describe-ec2-demo

Key points


Setup

The steps below will take you through the process of using the EC2 plugin to create routes to EC2 instances. You will need to have the follow prerequisites complete:


Prepare sample resources in AWS

To route to an AWS EC2 instance, you must create an EC2 instance with a sample app and provide Gloo Gateway with the appropriate AWS credentials to access the EC2 instance.

If you already have an EC2 instance you would like to route to and the necessary credentials configured, you can skip to the next section, Create an EC2 Upstream.

Configure an EC2 instance

Create an EC2 instance with a demo app.

  1. Provision an EC2 instance

    • Use an amazon linux image
    • Configure the security group to allow http traffic on port 80.
  2. Tag your instance with the following tags

    • gloo-id: abcde123
    • gloo-tag: group1
    • version: v1.2.3
  3. Set up your EC2 instance

    • Download a demo app: an http response code echo app.
    • This app responds to requests with the corresponding response code. For example, http://[my-instance-ip]/?code=404 produces a 404 response.
    • Make the app executable.
    • Run the app in the background.
    wget https://mitch-solo-public.s3.amazonaws.com/echoapp2
    chmod +x echoapp2
    sudo ./echoapp2 --port 80 &
    
  4. Verify that you can reach the app. For example, if you send a curl request to the app, you get back a help menu for the app.

    curl http://<ec2-instance-public-ip>/
    
  5. Create AWS credentials for the EC2 instance that you provide to Gloo Gateway. You can choose from the following options:

Create a secret with AWS credentials

Gloo Gateway needs AWS credentials to be able to find EC2 resources. As such, you can create a set of credentials that only have access to the relevant resources.

In this example, the secret you create only has access to resources with the gloo-tag:group1 tag.

glooctl create secret aws \
  --name gloo-tag-group1 \
  --namespace default \
  --access-key [aws_secret_key_id] \
  --secret-key [aws_secret_access_key]

Create a role for Gloo Gateway to assume on behalf of your Upstreams

For more fine-grained control over Gloo Gateway’s access to your resources and as an additional filter on your EC2 Upstream’s list of available instances, create an AWS role for Gloo Gateway. This way, the credentials that Gloo Gateway uses for your Upstreams are associated with a low-access user account that assumes the specific role with only the specific permissions that Gloo Gateway needs.

When you provide a secret reference or an AWS Role ARN to your Upstream, Gloo Gateway calls the AWS API with the credentials composed from the user account associated with the secret or the provided role (via the AssumeRole feature).

To configure your AWS account with the relevant ARN Role:

  1. Create an AWS role. In the AWS console:

    1. Navigate to IAM > Roles, choose Create Role.
    2. Follow the interactive guide to create a role.
    3. Choose AWS account as the type of trusted entity.
    4. Enter the 12-digit account ID of the account that has the EC2 instances that you want to route to.
  2. Choose or create a policy for the role. Example of a Policy that allows the role to describe EC2 instances:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": "ec2:DescribeInstances",
                "Resource": "*"
            }
        ]
    }
    
  3. Grant the Upstream’s account access to the role. In the AWS console:

    1. From IAM > Roles, select the role that you just created.
    2. Click the Trust relationships tab.
    3. Note the entries under the Trusted entities table.
    4. Click Edit trust relationship.
    5. Add your user/service account’s ARN to the Principal.AWS list, as shown in the following example. Add the ARNs of each of the user accounts that you want to allow to assume this role.
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": [
              "arn:aws:iam::[account_id]:user/[user_id]"
            ]
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }
    

Create an EC2 Upstream

Finally, make an Upstream that points to the resources that you want to route to:

apiVersion: gloo.solo.io/v1
kind: Upstream
metadata:
  annotations:
  name: ec2-demo-upstream
  namespace: gloo-system
spec:
  awsEc2:
    filters:
    - key: gloo-id
    - kvPair:
        key: gloo-tag
        value: group1
    - kvPair:
        key: version
        value: v1.2.3
    region: us-east-1
    publicIp: true
    secretRef:
      name: gloo-tag-group1
      namespace: default
    roleArn: "<arn-for-the-role-you-created>"

Save the spec to ``ec2-demo-upstream.yamland usekubectl` to create the upstream in Kubernetes.

kubectl apply -f ec2-demo-upstream.yaml

Create a route to your Upstream

Now that you have created an Upstream, you can route to it as you would with any other Upstream.

glooctl add route  \
  --path-exact /echoapp  \
  --dest-name ec2-demo-upstream \
  --prefix-rewrite /

Verify that the route works:

export URL=`glooctl proxy url`
curl $URL/echoapp

You should see the same output as when you queried the EC2 instance directly.


Summary

In this tutorial, we created an Upstream that allows us to route traffic from our gateway to a set of EC2 instances. We created a single Upstream and associated it with a single instance. You can of course create an arbitrary number of Upstreams and associate them with an arbitrary number of instances. We reviewed how to prepare your AWS account with a sample instance, role, and policy so as to demonstrate the information Gloo Gateway needs to implement a routable EC2 Upstream.

Next Steps

Gloo Gateway can also use AWS Lambda as an Upstream target. You can learn more in the AWS Lambda guide.