aws

README

Fleeting Plugin AWS

This is a fleeting plugin for AWS.

Building the plugin

To generate the binary, ensure $GOPATH/bin is on your PATH, then use go install:

cd cmd/fleeting-plugin-aws/
go install 

If you are managing go versions with asdf, run this after generating the binary:

asdf reshim

Plugin Configuration

The following parameters are supported:

Parameter	Type	Description
name	string	Name of the Auto Scaling Group
profile	string	Optional. AWS profile-name (Named profiles for the AWS CLI).
config_file	string	Optional. Path to the AWS config file (AWS Configuration and credential file settings).
credentials_file	string	Optional. Path to the AWS credential file (AWS Configuration and credential file settings).

The credentials don't need to be set if the plugin is running on an instance inside AWS with the IAM permission assigned. See Recommended IAM Policy

Default connector config

Parameter	Default
os	linux
protocol	ssh or winrm if Windows OS is detected
username	ec2-user or Administrator if Windows OS is detected
use_static_credentials	false
key_path	None. This is the path for the private key file used to connect to the runner manager machine. Required for Windows OS.

For Windows instances, if use_static_credentials is false, the password field is populated with a password that AWS provisions.

For other instances, if use_static_credentials is false, credentials will be set using SendSSHPublicKey, either using the specified key or dynamically creating one.

Autoscaling Group Setup

• Group size desired and minimal capacity should be zero.
• Maximum capacity should be equal or more than the configured fleeting Max Size option.
• Scaling policy should be set to None.
• Process AZRebalance should be suspended.
• Instance scale-in protection should be enabled.

Setting an IAM policy

Our recommendations

• Grant least privilege
• Create an IAM group with a policy like the example below and assign each AWS user to the group
• Use policy conditions for extra security. This will depend on your setup.
• Do not share AWS access keys to separate deployments.

Create an AWS Credential Type of Access key - Programmatic access, enabling the plugin to access your ASG via the AWS SDK.

Recommended IAM Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "autoscaling:SetDesiredCapacity",
                "autoscaling:TerminateInstanceInAutoScalingGroup"
            ],
            "Resource": "YOUR_AUTOSCALING_GROUP_ARN"
        },
        {
            "Effect": "Allow",
            "Action": [
                "autoscaling:DescribeAutoScalingGroups",
                "ec2:DescribeInstances"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:GetPasswordData",
                "ec2-instance-connect:SendSSHPublicKey"
            ],
            "Resource": "arn:aws:ec2:YOUR_AWS_REGION:YOUR_AWS_ACCOUNT_ID:instance/*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/aws:autoscaling:groupName": "YOUR_AUTOSCALING_GROUP_NAME"
                }
            }
        }
    ]
}

The IAM policy for ec2-instance-connect:SendSSHPublicKey is only necessary if the configuration use_static_credentials is set to false (default).

The IAM policy for ec2:GetPasswordData is only necessary if the EC2 instances runs on Windows.

WinRM

The fleeting connector can use Basic authentication via WinRM-HTTP (TCP/5985) to connect to the EC2 instance. The Windows AMIs provided by AWS don't allow WinRM access by default.

The following startup script can enable a WinRM connection:

netsh advfirewall firewall add rule name="WinRM-HTTP" dir=in localport=5985 protocol=TCP action=allow
winrm set winrm/config/service/auth '@{Basic="true"}'
winrm set winrm/config/service '@{AllowUnencrypted="true"}'

This adjusts the firewall, and allows Basic authentication via an unencrypted connection (WinRM-HTTP).

Examples

GitLab Runner

GitLab Runner has examples on using this plugin for the Instance executor and Docker Autoscaler executor.

Documentation

Index

• Variables
• type InstanceGroup
  • func (g *InstanceGroup) ConnectInfo(ctx context.Context, id string) (provider.ConnectInfo, error)
  • func (g *InstanceGroup) Decrease(ctx context.Context, instances []string) ([]string, error)
  • func (g *InstanceGroup) Increase(ctx context.Context, delta int) (int, error)
  • func (g *InstanceGroup) Init(ctx context.Context, log hclog.Logger, settings provider.Settings) (provider.ProviderInfo, error)
  • func (g *InstanceGroup) Shutdown(ctx context.Context) error
  • func (g *InstanceGroup) Update(ctx context.Context, update func(id string, state provider.State)) error
• type PrivPub

Variables

var (
	NAME      = "fleeting-plugin-aws"
	VERSION   = "dev"
	REVISION  = "HEAD"
	REFERENCE = "HEAD"
	BUILT     = "now"

	Version plugin.VersionInfo
)

Types

type InstanceGroup

type InstanceGroup struct {
	Profile         string `json:"profile"`
	ConfigFile      string `json:"config_file"`
	CredentialsFile string `json:"credentials_file"`
	Name            string `json:"name"`
	// contains filtered or unexported fields
}

func (*InstanceGroup) ConnectInfo

func (g *InstanceGroup) ConnectInfo(ctx context.Context, id string) (provider.ConnectInfo, error)

func (*InstanceGroup) Decrease

func (g *InstanceGroup) Decrease(ctx context.Context, instances []string) ([]string, error)

func (*InstanceGroup) Increase

func (g *InstanceGroup) Increase(ctx context.Context, delta int) (int, error)

func (*InstanceGroup) Init

func (g *InstanceGroup) Init(ctx context.Context, log hclog.Logger, settings provider.Settings) (provider.ProviderInfo, error)

func (*InstanceGroup) Shutdown

func (g *InstanceGroup) Shutdown(ctx context.Context) error

func (*InstanceGroup) Update

func (g *InstanceGroup) Update(ctx context.Context, update func(id string, state provider.State)) error

type PrivPub

type PrivPub interface {
	crypto.PrivateKey
	Public() crypto.PublicKey
}