AWS Quick Start Guide - Business and Start-Up

Simplified guide for the impatient

Install mac command line interface

curl -sSL https://manageacloud.com/mac | sudo bash

Login (new user?)

mac login

Install awscli

sudo pip install awscli

Configure awscli (new at AWS?, How to create API keys)

aws configure

Activate AWS at ManageaCloud (check the documentation for mac provider credential)

mac provider credential amazon <Access Key> <Secret Access Key>

Build an infrastructure (load balancer + instance)

mac -s infrastructure macfile https://raw.githubusercontent.com/manageacloud/quickstart/master/roles.macfile

List instances

mac instance list

SSH an instance

mac instance ssh <name or id>

List instances and resources

mac infrastructure items

List infrastructures

mac infrastructure list

Get the DNSName (CNAME to access to the application using the load balancer)

mac resource get_stdout demo 1.0 "load balancer 01"

Destroy the infrastructure

mac infrastructure destroy demo 1.0

Introduction

ManageaCloud can help you to achieve some of the following goals:

  • Convert infrastructure into code
  • Application deployment (one click deployment, blue-green deployments, continuous delivery, continuous deployment ...)
  • Automation of infrastructure
  • Manage complex infrastructure scenarios

This Quick Start guide will show you the basic features of ManageaCloud by deploying the demo application using blue green deployments in Amazon Web Services.


Your first infrastructure

A Macfile is a ManageaCloud configuration file which contains the architecture blue print. It shows how your infrastructure is created and destroyed. Imagine that you want to create a load balancer in Amazon Web Services. The macfile will look like this:

mac: 0.9.27
description: elastic_load_balancer
name: demo
version: 1.0
resources:
    elastic_load_balancer:
        create bash:
          aws elb create-load-balancer
            --load-balancer-name my-demo-load-balancer
            --listeners Protocol=HTTP,LoadBalancerPort=80,InstanceProtocol=HTTP,InstancePort=80
            --availability-zones us-east-1b us-east-1c
            --region us-east-1
infrastructures:
    load balancer 01:
        resource: elastic_load_balancer

Pre-requirements

Executing this example requires two additional items:

  • - mac, the ManageaCloud Command Line Interface
    curl -sSL https://manageacloud.com/mac | sudo bash
    Log into ManageaCloud (New user?):
    mac login
  • - aws the official Amazon Web Service command line interface
    sudo pip install awscli
    Configure it (new at AWS?, How to create API keys):
    aws configure

Where is aws elb create-load-balancer coming from ?

ManageaCloud is a framework that allows you to organize the different command line interfaces that manages different cloud suppliers. In this case, as we are managing Amazon Web Services, we choose the AWS command line interface.

aws elb create-load-balancer is the command that creates a load balancer.

You can execute this file using the following command:

mac infrastructure macfile https://raw.githubusercontent.com/manageacloud/quickstart/master/first_infrastructure.macfile

The previous command will create a load balancer in Amazon Web Services. You can verify that an infrastructure demo version 1.0 is currently active.

$ mac infrastructure items
There is no active instances in infrastructure

+---------------------+---------+-----------------------+------------------+--------+
| Infrastructure name | Version | Resource type         | Resource name    | Status |
+---------------------+---------+-----------------------+------------------+--------+
| demo                | 1.0     | elastic_load_balancer | load balancer 01 | Ready  |
+---------------------+---------+-----------------------+------------------+--------+

However, if you destroy the infrastructure, no action will be performed in Amazon Web Services

$ mac infrastructure destroy demo 1.0
Resource load balancer 01 skipped

What happens with all the stuff created by the Quickstart guide ?

Don't worry! This Quickstart guide won't leave anything running in your AWS account. If you follow all the steps, all the resources that this guide creates will be eventually destroyed.


Destroying infrastructures

Let's add more information to the macfile so we can create destroy infrastructure:

mac: 0.9.27
description: elastic_load_balancer
name: demo
version: 1.0
resources:
    elastic_load_balancer:
        create bash:
            aws elb create-load-balancer
            --load-balancer-name my-demo-load-balancer
            --listeners Protocol=HTTP,LoadBalancerPort=80,InstanceProtocol=HTTP,InstancePort=80
            --availability-zones us-east-1b us-east-1c
            --region us-east-1
        destroy bash:
            aws elb delete-load-balancer
            --load-balancer-name my-demo-load-balancer
            --region us-east-1
infrastructures:
    load balancer 01:
        resource: elastic_load_balancer

Now if we create new infrastructure

mac infrastructure macfile https://raw.githubusercontent.com/manageacloud/quickstart/master/destroy_infrastructure.macfile

We also have the ability to destroy it

$ mac infrastructure destroy demo 1.0
Resource load balancer 01 has been successfully removed

Parameterising Resources

resources knows how to create while infrastructures section creates them. Let's make the elastic_load_balancer a bit more generic, so it will be easy to create more load balancers if required.

mac: 0.9.27
description: elastic_load_balancer
name: demo
version: 1.0

resources:
    elastic_load_balancer:
        create bash:
            aws elb create-load-balancer
                --load-balancer-name infrastructure.param.name
                --listeners infrastructure.param.listeners
                --availability-zones infrastructure.param.availability-zones
                --region infrastructure.param.region

        destroy bash:
            aws elb delete-load-balancer
                --load-balancer-name infrastructure.param.name
                --region infrastructure.param.region

infrastructures:
    load balancer 01:
        resource: elastic_load_balancer
        params:
            name: my-demo-load-balancer
            listeners: Protocol=HTTP,LoadBalancerPort=80,InstanceProtocol=HTTP,InstancePort=80
            availability-zones: us-east-1b us-east-1c
            region: us-east-1

Test it!

mac infrastructure macfile https://raw.githubusercontent.com/manageacloud/quickstart/master/parameterising_resources.macfile

Destroy the infrastructure

mac infrastructure destroy demo 1.0

Roles

roles are a shortcut used to create instances in the cloud that bootstraps the server configuration.

Those server configurations can be created, tested and configured in your account. Then you can use it as a role in the macfiles.

This example will use the demo application server configuration. The configuration is bootstrapped via a repository in github, which configures apache and php using bash.

Public Server Configurations

ManageaCloud provides a repository of public server configurations that you can use right away in your macfiles if using Manageacloud Business or Start-Up.

Private server configurations

You can list your private server configurations by executing mac configuration list. You can create private server configurations on your account.

Activating your cloud supplier

ManageaCloud uses your supplier's API authentication to create and destroy instances. You can activate your supplier by executing mac provider credential. If no provider is specified, the instances are created in the default supplier configured when the account was created.

mac: 0.9.27
description: Load Balanced Demo Application
name: demo
version: 1.0

roles:
    demo_app:
      instance create:
            configuration: demo_application

actions:
    get_id:
        ssh: wget -q -O - http://169.254.169.254/latest/meta-data/instance-id

resources:
    elastic_load_balancer:
        create bash:
            aws elb create-load-balancer
            --load-balancer-name infrastructure.param.name
            --listeners infrastructure.param.listeners
            --availability-zones infrastructure.param.availability-zones
            --region infrastructure.param.region

        destroy bash:
            aws elb delete-load-balancer
                --load-balancer-name infrastructure.param.name
                --region infrastructure.param.region

    register_lb:
        create bash:
            aws elb register-instances-with-load-balancer
                --load-balancer-name infrastructure.param.load-balancer-name
                --instances infrastructure.param.instances
                --region infrastructure.param.region

infrastructures:
    load balancer 01:
        resource: elastic_load_balancer
        params:
            name: my-demo-load-balancer
            listeners: Protocol=HTTP,LoadBalancerPort=80,InstanceProtocol=HTTP,InstancePort=80
            availability-zones: us-east-1b us-east-1c
            region: us-east-1

    demo_application_instance:
        name: demo
        provider: amazon
        location: us-east-1
        hardware: t1.micro
        role: demo_app
        environment:
        - APP_BRANCH: master

    register_instance:
        ready: role.demo_app
        resource: register_lb
        params:
            load-balancer-name: my-demo-load-balancer
            instances: role.demo_app.get_id
            region: us-east-1

Activate your cloud supplier (check the documentation for mac provider credential)

mac provider credential amazon <Access Key> <Secret Access Key>

Create an infrastructure

mac -s infrastructure macfile https://raw.githubusercontent.com/manageacloud/quickstart/master/roles.macfile

List available infrastructures

mac infrastructure list

View the infrastructure contents

mac infrastructure items

View instances

mac instance list

SSH an instance

mac instance ssh <name or id>

You can always use -h to get all available options or show additional help

mac instance -h

Destroy the infrastructure

mac infrastructure destroy demo 1.0

Parameterising the macfile

We have already built the macfile that defines the configuration of the infrastructure. We will add some parameters so it will be easier to create and destroy multiple independent infrastructures.

mac: 0.9.27
description: Load Balanced Demo Application
name: demo
version: {INF_VERSION}

roles:
    demo_app:
      instance create:
            configuration: demo_application

actions:
    get_id:
        ssh: wget -q -O - http://169.254.169.254/latest/meta-data/instance-id

resources:
    elastic_load_balancer:
        create bash:
            aws elb create-load-balancer
            --load-balancer-name infrastructure.param.name
            --listeners infrastructure.param.listeners
            --availability-zones infrastructure.param.availability-zones
            --region infrastructure.param.name

        destroy bash:
            aws elb delete-load-balancer
                --load-balancer-name infrastructure.param.name
                --region infrastructure.param.name

    register_lb:
        create bash:
            aws elb register-instances-with-load-balancer
                --load-balancer-name infrastructure.param.load-balancer-name
                --instances infrastructure.param.instances
                --region infrastructure.param.region

infrastructures:
    load balancer 01:
        resource: elastic_load_balancer
        params:
            name: my-demo-load-balancer-{INF_VERSION}
            listeners: Protocol=HTTP,LoadBalancerPort=80,InstanceProtocol=HTTP,InstancePort=80
            availability-zones: us-east-1b us-east-1c
            region: us-east-1

    demo_application_instance:
        name: demo
        provider: amazon
        location: us-east-1
        hardware: t1.micro
        role: demo_app
        environment:
        - DB_IP: my_rds_cname
        - APP_BRANCH: {APP_BRANCH}

    register_instance:
        resource: register_lb
        params:
            load-balancer-name: my-demo-load-balancer-{INF_VERSION}
            instances: role.demo_app.get_id
            region: us-east-1

What parameters are accepted by the server configuration ?

The server configuration demo_application bootstraps the file application.sh that accepts two parameters (visible as environment variables):

  • - DB_IP, which specifies where the database is, (According to the immutable infrastructure architecture pattern you have to divide data from everything else, which means that the infrastructure that supports the data is created in another macfile.)
  • - APP_BRANCH contains the name of the branch that is going to be activated.

Let's create an infrastructure and activate the master branch:

$ mac -s infrastructure macfile https://goo.gl/ezRWx1 -p INF_VERSION=1 APP_BRANCH=master
[...]
Resource load balancer 01
-------------------------
Execution successful. Output:
{
    "DNSName": "my-demo-load-balancer-1-835436264.us-east-1.elb.amazonaws.com"
}
[...]

You should be able to access the application by loading the DNSName of the load balancer in a browser.

Patience!

A brand new fully functional load balancer in AWS can take a couple of minutes.


My first blue-green deployment

Did you run the previous example ?

This section assumes that you have the demo infrastructure version 1 from the previous example is operational.

If you run mac infrastructure list you should see demo infrastructure version 1 operational.

$ mac infrastructure list
+---------------------+---------+
| Infrastructure name | version |
+---------------------+---------+
|         demo        |    1    |
+---------------------+---------+

This version is running the branch master. Let's make a deployment of the branch version_2

$ mac -s infrastructure macfile https://goo.gl/ezRWx1 -p INF_VERSION=2 APP_BRANCH=version_2

You should be able to access the application by loading the DNSName of the load balancer in a browser.

When the command is finished, you should have two independent infrastructures that use the same database:

$ mac infrastructure list
+---------------------+---------+
| Infrastructure name | version |
+---------------------+---------+
|         demo        |    2    |
|         demo        |    1    |
+---------------------+---------+

By loading the DNSName of the load balancers in the browser you should be able to see both versions running.

Whenever you feel confident that the new infrastructure is operational, destroy the old one.

$ mac infrastructure destroy demo 1
Instance gcnu3se1ftfl1hh8b0i51hp296 marked as deleted
Resource register_instance skipped
Resource load balancer 01 has been successfully removed

Blue-green deployments in the real world

In the real world, you need to analyse how the deployment works best for your case. One option is to point the DNS of the domain to the CNAME of the active load balancer. If you use this approach you will probably need to reduce the DNS TTL and destroy the old infrastructure only when it is no longer processing any traffic.

Would you like to deploy an infrastructure by performing POST to an URL ?

You should learn about triggers in your account.

Need help ?

If you need help, please contact us.


Appendix I: Cloud Agnostic A load balanced application using resources

ManageaCloud is a technology agnostic platform, allowing you to integrate with any platform. roles are not cloud agnostic, as the provider must be defined. The following example demonstrates the cloud agnostic capability of ManageaCloud when orchestrating an instance using resources in Amazon Web Services.

Roles

When you are creating instances is easier to use roles than resources.

mac: 0.9.27
description: elastic_load_balancer
name: demo
version: 2.0

actions:
    set_private_key:
        bash: |
            cat >/tmp/privkey <<EOL
            resource.ssh_pair.json.KeyMaterial
            EOL
            chmod 600 /tmp/privkey

    bootstrap:
        bash: "ssh -o StrictHostKeyChecking=no ubuntu@action.get_public_ip.text.regex(\"PublicIp\": \"([0-9\\.]+)\") -i /tmp/privkey 'sleep 20 && sudo apt-get update && sudo apt-get install apache2 -y'"

    get_public_ip:
        bash: aws ec2 describe-instances --instance-ids resource.my_instance.json.Instances.0.InstanceId

resources:

    elastic_load_balancer:
        create bash:
            aws elb create-load-balancer
                --load-balancer-name infrastructure.param.name
                --listeners infrastructure.param.listeners
                --availability-zones infrastructure.param.availability-zones
                --region infrastructure.param.region


        destroy bash:
            aws elb delete-load-balancer
              --load-balancer-name infrastructure.param.name
              --region infrastructure.param.region

    ec2 create pair:
        create bash:
            aws ec2 create-key-pair
                --key-name infrastructure.param.key-name
                --region infrastructure.param.region

        destroy bash:
            aws ec2 delete-key-pair
                --key-name infrastructure.param.key-name
                --region infrastructure.param.region

    ec2 instance:
        create bash:
            aws ec2 run-instances
            --image-id infrastructure.param.image-id
            --count 1
            --instance-type infrastructure.param.instance-type
            --key-name infrastructure.param.key-name
            --security-groups default
            --region infrastructure.param.region

        destroy bash:
            aws ec2 terminate-instances
            --instance-ids resource.my_instance.json.Instances.0.InstanceId
            --region infrastructure.param.region

    register_lb:
        create bash:
            aws elb register-instances-with-load-balancer
            --load-balancer-name infrastructure.param.name
            --instances resource.my_instance.json.Instances.0.InstanceId

infrastructures:
    load_balancer_01:
        resource: elastic_load_balancer
        params:
            name: my-demo-load-balancer
            listeners: Protocol=HTTP,LoadBalancerPort=80,InstanceProtocol=HTTP,InstancePort=80
            availability-zones: us-east-1b us-east-1c

    ssh_pair:
        resource: ec2 create pair
        params:
            key-name: MyDemoPair
            region: us-east-1

    my_instance:
        resource: ec2 instance
        params:
            image-id: ami-c53d7ba0 # Ubuntu 14.04 HVM
            instance-type: t2.micro
            key-name: MyDemoPair
            region: us-east-1

    register_instance:
        resource: register_lb
        params:
            name: my-demo-load-balancer
            region: us-east-1

    set_private_key:
        action: set_private_key

    bootstrap_inf:
        action: bootstrap

$ mac -s infrastructure macfile https://goo.gl/EJNnmT