Working as a Collaborator
Once you have been set up as a collaborator you can -
- Create infrastructure in the modernisation-platform-environments repository
- Deploy infrastructure via GitHub Actions workflows
- View your accounts via the AWS console
- Use AWS credentials
- Run Terraform plans locally
- Access EC2s and databases
Logging in to the AWS Console
Click on the AWS Console url - https://eu-west-2.console.aws.amazon.com/
You will see the sign on screen, choose IAM user and enter the Modernisation Platform landing zone account number (this will be provided to you on set up).
Enter your user details (your MFA and console password must be set up first)
Once you are logged in, switch role to the relevant account.
You will need to know the account number of the AWS account you want to switch to and the role you have been assigned, these will be told to you on initial user set up, the valid roles are:
Role | Description | Typical User |
---|---|---|
read-only | Read only console access | Used by read only users such as security testers |
security-audit | AWS security-audit policy | Used by security testers |
developer | Read only console plus other permissions such as the ability to set secrets,restart EC2s, raise support tickets. | Used by engineers working on the application infrastructure |
sandbox | Admin role to perform most AWS actions via the console | Used by engineers to make development easier in some situations, only allowed in the development account |
migration | Role with developer and AWS migration services permissions | Used by engineers to migrate applications, will be removed before application goes into production |
instance-management | Role for use by instance management with permissions for EC2 and RDS instances | Used by database or EC2 administrators to migrate services and perform tasks. |
security-audit | Role with AWS managed SecurityAudit policy | Used by members of security and audit teams. |
You can see the accounts and roles assigned to you here
Getting access credentials
AWS provides credentials which can give you programmatic access to your AWS account. This enables you to run AWS CLI commands or Terraform plans locally.
Running a Terraform plan locally as a collaborator
Set credentials
To run a Terraform locally as a collaborator, you will need to get your AWS credentials. See above for creating and obtaining these, you will need use a tool such as aws-vault to handle MFA, or you can generate a session token using the AWS CLI. (Terraform does not support the use of MFA well when assuming roles.)
Set the role you assume
There are different access levels that map to different roles that you can assume when running Terraform.
By default if you do nothing the role you assume will be the developer
role.
If you wish to assume another role, eg migration
or sandbox
you will need to set an environment variable:
export TF_VAR_collaborator_access=migration
Install Terraform
Follow the instructions here to install the latest version of Terraform according to your platform.
Run Terraform plan
- Navigate to your application infrastructure code -
cd modernisation-platform-environments/terraform/environments/my-application
- Run a Terraform init -
terraform init
- View the workspaces (you have different workspaces for your different environment accounts) -
terraform workspace list
- Select the required workspace -
terraform workspace select my-application-development
- Run a Terraform plan -
terraform plan
Running a plan locally has read only permissions, you will not be able to run an apply, destroy or import.
Accessing EC2s as a Collaborator
You will need to have the developer
access role in order to use SSM/Bastion.
- Download the AWS CLI
- Ensure you have your AWS credentials
- In your terminal enter
aws configure
to set up credentials and enter the key and access key created in the previous step. - Open
~/.aws/config
in a text editor and enter the following to create your AWS profile:
[profile <my-application-account-name>]
source_profile = default
role_arn:arn:aws:iam::<your application account number>:role/developer
mfa_serial = arn:aws:iam::<landing zone account number>:mfa/<your user name>
role_session_name=<my-application-account-name>
Accessing EC2s with SSM Agent installed
Most modern AMIs will already have the SSM Agent installed. You can connect to these instances directly with Session Manager.
- Start a basic Session Manager session
aws ssm start-session --target i-12345bc --profile <my aws profile>
Accessing EC2s via a bastion
- Create a bastion EC2 using the bastion module
- Create or share your public key and preferred username as detailed in the bastion readme
- Open
~/.ssh/config
in a text editor and enter the following:
Host bastion
IdentityFile ~/.ssh/id_rsa #local path to the public key provided in earlier
User <your user name>
ProxyCommand sh -c "aws ssm start-session --target $(aws ec2 describe-instances --no-cli-pager --filters "Name=tag:Name,Values=bastion_linux" --query 'Reservations[0].Instances[0].InstanceId' --profile <my aws profile>) --document-name AWS-StartSSHSession --parameters 'portNumber=%p' --profile <my aws profile> --region eu-west-2"
- To SSH or other port tunneling (eg to connect to a database) through the bastion to your EC2 instance, using the relevant ports:
ssh -L 33389:<IP address of destination instance>:3389 bastion
Useful Tips
AWS Vault is a useful tool, and can be found here. Mac users can install it using Homebrew.