Infrastructure repository

This section assumes you have read and followed the Quick Start pages.

If you only have a single "infrastructure", for example you're just running ce-provision for your own company servers and there really aren't that many of them, you can probably stick with basic usage and the ce-provision-config approach.

However, if you have logically separate sets of servers and services with one or more cloud or hosting providers, you may want to separate their configurations and playbooks out into separate repositories to make management easier. At Code Enigma we call these logical groupings "infrastructures" and we keep the playbooks and variables unique to the elements of each infrastructure in its own Git repository, typically on the controller server.

Create an infra repo

Firstly, we need to create the new repository on our GitLab server:

1. In a web browser go to your GitLab installation, for example https://gitlab.controller.acme.com/, and login - instructions here, step 3
2. Click on Groups on the left menu
3. Click the New group button on the right, then Create group
   • we recommend you name it Infras and leave it private - this is where we will store our "infra" repositories
4. On the next page click New project -> Create a blank project
   • we recommend you name it something sensible and recognisable, beginning with infra, leave it private and do not create a README
   • for this example we will use infra-main-website

At this point you should have a new repository at https://gitlab.controller.acme.com/infras/infra-main-website (obviously with your controller server URL, not our example one).

Seed your infra repository.

We have a template repository for an AWS account. To use it:

1. Still in GitLab, as stated in the README for the template, create a global environment variable called ENV in Admin -> Settings -> CI/CD -> Variables
2. Go to our templates repository, click the green Code button and click Download ZIP
3. Create a folder on your computer where you want to keep your repository and copy the contents of the extracted NETWORK folder into it
   • Be sure to get all the hidden files!
   • You can delete README.md if you wish
4. As stated in the README for the template, find and replace all instances of these strings:
   • SHORTNAME - your infrastructure name
   • CIDR_BASE - your VPC CIDR base for IPv4 addressing

Example:

# do this within your infra repo folder
find ./ -type f -exec sed -i -e 's/SHORTNAME/main-website/g' {} \;
find ./ -type f -exec sed -i -e 's/CIDR_BASE/10.0/g' {} \;

5. Back in GitLab, add an SSH key by clicking the Add SSH key button in the banner, if you have not already done so
   • Extensive help on using SSH keys with GitLab can be found here.
6. On your project page, follow the Push an existing folder instructions on your project front page, but use the branch name apply

Set up your AWS user and credentials

Ansible uses the Python library boto3 to manage connections to AWS accounts. In order for boto3 to have permissions to connect to your AWS account, we have to set up a profile. There is an Ansible role that will take care of this for you in our controller server set up process, it will write the ~/.aws/credentials file that Ansible needs, however you need to create the variables required to allow it to do so.

Follow this guide to create an IAM user for your controller server. Once you have done that, you need to set up the aws_credentials role for your controller. We strongly recommend you do this using SOPS.

Configuration with SOPS - recommended

Firstly, follow our guide to set up SOPS.

Then, using your ce-provision-config repository, which you will need checked out on to your workstation:

1. Open a local terminal and change directory to your repository location
2. Create a SOPS variables file in the _controller host group: sops hosts/group_vars/_controller/_encrypted.sops.yml
3. Place the access key details you saved in the AWS guide into the resulting file, like so:

_encrypted_aws_credentials_provision:
    acme:
        access_key_id: AKIAXXXXXXXXXXXXXXXX
        secret_access_key: sOmeVeryloNgStriNgFrOm+aWS

If you have more than one AWS IAM user Ansible might need to use, you can add them one after the other in this file.

4. Edit the provided hosts/group_vars/_controller/aws_credentials.yml file, it initially looks like this:

---
# Placeholder for boto credentials later
# Docs: https://codeenigma.github.io/ce-provision-docs/2.x/roles/aws/aws_credentials/
aws_credentials:
  - user: controller
    profiles: []

And you should add your AWS profile like this:

---
aws_credentials:
  - user: controller
    profiles:
      - name: acme
        access_key_id: "{{ _encrypted_aws_credentials_provision.acme.access_key_id }}"
        secret_access_key: "{{ _encrypted_aws_credentials_provision.acme.secret_access_key }}"

5. Add, commit and push your changes to the config repo
6. In GitLab build your controller server again

The /home/controller/.aws/credentials file should get created on the server. You can optionally verify by logging in over SSH, you should see something like this:

$ sudo cat /home/controller/.aws/credentials
[acme]
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
aws_secret_access_key = sOmeVeryloNgStriNgFrOm+aWS

Configuration without SOPS

This looks much the same as configuration with SOPS, but you simply put your raw AWS access credentials directly into the hosts/group_vars/_controller/aws_credentials.yml file. This is clearly a terrible idea, as the credentials have full admin access, so anyone who copies them from your repository will also have full admin access.

Run a network build

Now your controller is rebuilt with your AWS credentials you can have it begin orchestrating your AWS infrastructure.

In your GitLab server and within the infra repository, go to Build -> Pipelines and click the New pipeline button in the top right. On the following form pick the ENV (environment) you want to build. Convention is to do util first, then dev, stage and prod in that order. To save on cost, do not build environments you do not need, even if you might need them later. Then set TRIGGER_NETWORK_BUILD to yes and click the New pipeline button at the bottom of the form. Your environment and networks should be automatically created.

Building your first AWS EC2 instance (server)

TODO