AWS: Installation requirements

What you need

• Access Key and Secret or alternatively a temporary Access Key, Secret, and Session Token
• Region and Availability Zone to use
• Tectonic License and Pull Secret
• SSH Key pair in that region
• KMS Key in that region or access rights for Tectonic to generate one
• A Public Route53 Hosted Zone identifier. Public Route53 DNS resolution is a requirement for controller-worker TLS communication. Choose a domain or subdomain and configure it for name service at Route53. Tectonic will create 2 subdomains in this Hosted Zone during provisioning.
• A current version of the Google Chrome or Mozilla Firefox web browser to run Tectonic Installer.
• Two (1 Controller, 1 Worker) t2.medium nodes (minimum).
• Each node should have access to a minimum of 30GB of storage.

Privileges

The AWS credentials you provide require access to the following AWS services:

• CloudFormation
• ELB
• EC2
• KMS
• Route53
• S3
• Security Groups
• VPC

An importable AWS policy containing the minimum privileges needed to run the Tectonic installer can be found here.

Temporary credentials

The following steps demonstrate how to generate and use temporary AWS credentials in conjunction with the Tectonic Installer:

1. Ensure the AWS CLI tool is installed by following the instructions on the AWS CLI documentation. On Fedora, this can be done with dnf install:

    $ sudo dnf install awscli
   

2. Ensure the AWS CLI is configured to use your access key ID and secret access key:

    $ aws configure
   

3. Create a tectonic-installer role in AWS with the trust policy detailed here. The trust relationship policy grants an entity permission to assume the role. Note: The file:// prefix is required before the filepath.

    $ aws iam create-role --role-name tectonic-installer --assume-role-policy-document file://Documentation/files/aws-sts-trust-policy.json
   

4. Add an inline AWS policy document to the tectonic-installer role containing the minimum privileges needed to run the Tectonic installer. The policy is available here.

    $ aws iam put-role-policy --role-name tectonic-installer --policy-name TectonicInstallerPolicy --policy-document file://Documentation/files/aws-policy.json
   

5. Add your user's ARN, found on the IAM user detail page, to the trusted entities for the tectonic-installer role. To do so, click on the Trust Relationships tab and then on the Edit Trust Relationship button to bring up the trusted entities JSON editor. You'll then need to add a new section for your user's ARN.

   The example Trust Relationship below has been edited to add a user's (named tectonic) ARN:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Service": "ec2.amazonaws.com",
            "AWS": "arn:aws:iam::477645798577:user/tectonic"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }
   

6. Assume the tectonic-installer role with your AWS user using the AWS CLI tool as follows:

    $ aws sts assume-role --role-arn=<TECTONIC_INSTALLER_ROLE_ARN> --role-session-name=tectonic-installer --role-session-name=<DESIRED_USER_NAME>
   

   The returned response will look like:

    {
        "Credentials": {
            "SecretAccessKey": "<SECRET_ACCESS_KEY>",
            "AccessKeyId": "<ACCESS_KEY_ID>",
            "Expiration": "2016-12-14T02:21:37Z",
            "SessionToken": "<SESSION_TOKEN>"
        },...
    }
   

   Use the SECRET_ACCESS_KEY, ACCESS_KEY_ID, and SESSION_TOKEN to authenticate in the installer.

SSH key

The final step of the Tectonic install requires an SSH key and access to standard utilities like ssh and scp. Setting up a new key on AWS should take less than 5 minutes.

First, create a key.

1. Open a new terminal. Check if you already have a key by running ls ~/.ssh/. If you've previously created a key, you may see a file like id_rsa.pub. If you'd like to use this key, you may skip to the "upload the key to AWS" steps.

2. Type ssh-keygen --help to validate you have the openssh utilities installed. If you cannot find the binaries on your system, please consult your distro's documentation.

3. Type ssh-keygen -t rsa -b 4096 -C "aws tectonic for alice@example.com". The content after -C is a comment. Replace alice@example.com with an appropriate AWS email or IAM account.

4. Follow the prompts on screen to finish creating your keypair. If you chose the default file name and location, your key should be in $HOME/.ssh/id_rsa.pub. Otherwise, the key-pair is in your current directory.

Next, upload the key to AWS.

1. Sign in using your IAM user or temporary credentials.

2. Once signed in, navigate to EC2 and select the same region as that selected for Tectonic installation. Regions may be selected by using the drop down on the top right of the nav.

3. On the left navigation under Network & Security, select Key Pairs.

4. Click the button Import Key Pair. Follow the displayed instructions to import your public key file, whose name should end in .pub.

For additional information about AWS and SSH keys consult the official AWS guide.

Access

In order to access the cluster two ELB backed services are exposed. Both are accessible over the standard TLS port (443).

Install Tectonic

With temporary credentials and an SSH key, you'll be ready to install Tectonic. Head over to the install doc to get started.

Subnet/VPC requirements

The following table includes the high level networking features required to install Tectonic into new or existing VPCs, with or without public access to cluster services.

Configuring a 'public' cluster

• Subnets for Controllers must have an attached and routed Internet Gateway
• Subnets for Workers must be able to route requests to the Controller subnets and must have an associated route table that specifies a default gateway
• The route tables should be explicitly attached to their subnets

Configuring an 'internal' cluster

• Subnets for Controllers and Workers must be able to route requests to each other and must have an associated route table that specifies a default gateway
• The route tables should be explicitly attached to their subnets
• You must have VPN access to the subnet as it is does not offer an inbound connection to the Internet

Using an existing VPC

By default, Tectonic Installer creates a new AWS Virtual Private Cloud (VPC) for each cluster. Advanced users can choose to use an existing VPC instead. An existing VPC must have an Internet Gateway. Tectonic Installer will not create an Internet Gateway in an existing VPC.

An existing VPC for a public cluster must have a public subnet for controllers, and a private subnet for workers. An existing VPC for an internal cluster must have 2 private subnets, one each for controllers and workers.

Public subnets have a default route to the Internet Gateway and should auto-assign IP addresses. Private subnets have a default route to a default gateway, e.g. a NAT Gateway, a Virtual Private Gateway etc.

"DHCP Options Set" attached to the VPC must have AWS private domain name. In us-east-1 region AWS private domain name is ec2.internal whereas other regions use region.compute.internal.