AWS EC2 Plugin

AWS integration is achieved via a simple but powerful tagging system on EC2 instances. Tags are paired with AWS role/policy allowing connector instances to discover resources we want to expose via sockets.

For this example we will assume our AWS datacenter is us-west-2(Oregon)

The YAML configuration:

AWS settings

we expand the “connector” section to include the region and/or profile

connector:
   name: "my-awesome-connector"
   aws-region: "us-west-2"
   aws-profile: "prod"

Using the region and/or profile settings, the connector will use the well known places to find the AWS credentials. I will use these credentials to do the discovery and to connect.

Groups

Create plugin specific “aws_groups” section containing our discovery group name with access definitions

aws_groups:
    - group: infra_team
      policies: [my-connector-policy]

Tags

Add tags to EC2 instances with following format:

Key

Key: border0_someName

The Key must start with “border0” and can be followed by any alphanumeric set of characters, eg: border0_http, border0_server01, border01

Value

Value: port=1234,type=http,group=infra_team

The tag value represents CSV encoded parameters for a given socket.

  • group : the name of aws group defined in the YAML
  • port : the TCP port we wish to expose via the socket
  • type : one of the supported types of sockets: ssh, http, database, tls
  • upstream_type: for aws-ssm you can specify aws-ssm, for databases this could be mysql or postgres
Complete tag with value will look like this:

Key: border0_webserver
Value: port=80,type=http,group=infra_team

Once created it should appear like this in the AWS EC2 console:

Aws permissions

We need to give the connector instance access to read from AWS API.

This can be achieved in multiple ways and will be dependent on your deployment and type of infrastructure you run. One of the methods is an AMI role attached to a connector instance.

Sample AWS policy allowing EC2 describe to the connector code:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ec2:Describe*",
            "Resource": "*"
        }
    ]
}

AWS EC2 Instance Connect

The connector can use the AWS EC2 Instance Connect feature in combination with the Border0 SSH sockets. To enable this feature, the group configuration should include the aws_ec2_instance_connect flag:

aws_groups:
    - group: infra_team
      aws_ec2_instance_connect: true
      policies: [my-connector-policy]

All instances that are discovered in this group that has the type=ssh tag will be connected using AWS session manager.

AWS Session Manager

The connector can use AWS session manager in combination with the Border0 SSH sockets. Using session manager, a SSH socket will connect to AWS session manager to access an instance.

To enable this feature, the group configuration should include the aws_ssm_enable flag:

aws_groups:
    - group: infra_team
      aws_ssm_enabled: true
      policies: [my-connector-policy]

All instances that are discovered in this group that has the type=ssh tag will be connected using AWS session manager. You can also add the following parameter as a tagupstream_type=aws-ssm.

SSH Credentials

By default an SSH socket will use Border0 certificates to connect to the discovered instance with ssh. You can also specify static credentials in the group, using static credentials you don't need to configure the instance with certificate authentication.

Example using static username/password credentials:

aws_groups:
    - group: infra_team
      upstream_username: user
      upstream_password: password
      policies: [my-connector-policy]

Example using a private key:

aws_groups:
    - group: infra_team
      upstream_username: user
      upstream_identity_file: /path/to/key/id_rsa
      policies: [my-connector-policy]