Agile Cloud Institute

VM Auto Scaling Group in AWS using CloudFormation

This is a minimal starting point for developing an appliance using Cloudformation. One service creates a virtual machine autoscaling group that uses a custom image. The foundation creates the custom image and provides shared networking resources. This starting point contains elements from which you can build out a more full-featured appliance that includes multiple services.

STEP ONE: Create DevBox

You will need a provisioned devbox in order to orchestrate this appliance using the Agile Cloud Manager. Either Windows or Linux.

For convenience, we have defined a simple process for spinning up a at this link .

If you already have a working DevBox that you created for one of the other appliance examples, you can reuse that DevBox for this example if you do the following things first:

Replace keys.yaml and config.yaml with the versions described below that are required for this example.
Use a different empty, new working directory from which to run acm command line interface CLI commands.

STEP TWO: Create keys.yaml and config.yaml

Once you have created a DevBox, you can create a file in the DevBox named config.yaml in the $USER\acm\keys\starter directory and add the following precise contents to the file (REMOVE THE INDENTATION FROM EACH LINE. MAKE UP CUSTOM STRINGS ONLY FOR THE 2 VALUES THAT REQUEST THEM. BUT KEEP EVERYTHING ELSE EXACTLY AS IT IS):

orgCfDemo: <random-5-character-string-withoutspaces>
networkName: some-network-name
sysName: some-system
cfDemoStackName: firststack
region: us-west-2
vpcCIDR: 10.0.0.0/16
stackName: secondstack
imageName: <random-string-under-10-characters-withoutspaces>
SSHLocation: 0.0.0.0/0
imageInstanceType: t2.small 
sNetStackName: thirdstack
availZone: us-west-2a

Make sure to keep all of the given values in config.yaml exactly as they are given above. For example, keep us-west-2 for region, and keep 10.0.0.0/16 for vpcCIDR, and so on. Only create new string values for the 2 keys that request them. Get the example app running with these values before trying to change any of the other values in config.yaml.

Create a file in the DevBox named keys.yaml at $USER\acm\keys\starter\keys.yaml

You can create the AWS keys required to orchestrate this appliance by following the instructions at this link . After you have generated the keys, place the AWSAccessKeyId and AWSSecretKey into your $USER\acm\keys\starter\keys.yaml under secretsType: master, so that your entire keys.yaml will look as follows:

secretsType: master  
KeyName: ACMKeyPair_xyz
AWSAccessKeyId: <ACTUAL-ID-REDACTED>  
AWSSecretKey: <long-alpha-numeric-actual-key-redacted>  

Note that the ACMKeyPair_xyz value for KeyName was what you ran as input for the script that created the keys in the instructions above. For now, keep this value. Later on, you can change the value to correspond with any other valid KeyPair if you want.

STEP THREE: Confirm that ACM Has Been Installed

After you have confirmed that $USER\acm\keys\starter\keys.yaml and $USER\acm\keys\starter\config.yaml have been properly created, navigate the command line to any directory into which you want the Agile Cloud Manager to place resources for the given appliance.

Check the version by running the following command:

$ acm version  
1.3  

Always use the newest version of Agile Cloud Manager because the versions are backward compatible, and because we might change these example appliances over time to only work with newer versions.

STEP FOUR: Run Setup CLI Command

Download and install all the requirements for the appliance by running the following CLI command:

acm setup on sourceRepo=https://github.com/AgileCloudInstitute/acm-demo-cloudformation.git    

After the setup command completes running, confirm that your current working directory directory contains an acmAdmin subdirectory and an acmConfig subdirectory in addition to subdirectories for the other repositories that are listed in the appliance’s setupConfig.yaml file. You should now be able to find setupConfig.yaml inside the acmConfig subdirectory now that the acm setup on sourceRepo=https://github.com/AgileCloudInstitute/acm-demo-cloudformation.git command has completed running.

For example, on a Windows DevBox, you might run the dir command and see:

C:\path\to\mydirectory>dir  
 Volume in drive C is Windows  
 Volume Serial Number is 3E5E-9650  
  
 Directory of C:\p\a\acm_dl  
  
10/25/2023  04:48 PM    <DIR>          .  
10/23/2023  09:09 AM    <DIR>          ..  
10/23/2023  09:35 AM    <DIR>          acm-system-templates  
10/23/2023  09:34 AM    <DIR>          acmAdmin  
10/23/2023  09:34 AM    <DIR>          acmConfig  
10/23/2023  09:35 AM    <DIR>          aws-building-blocks  

The acmAdmin and acmConfig subdirectories will be present for any acm working directory after setup is run. The acm-system-templates and aws-building-blocks subdirectories are specific to this demo, and their names can be validated by examining the contents of the setupConfig.yaml file that you will find inside the acmConfig directory.

STEP FIVE: Run Appliance CLI Commands

After validating setup, create the appliance by running:

acm appliance on

You can watch the appliance being created in the following two ways:

The command line will print out structured logs organized by workflow steps you can read about in the documentation on this web site . These same logs will be stored in local log files on your machine.
The AWS GUI console at aws.amazon.com has a cloudformation stacks dashboard. You can log in to that dashboard and select the us-west-2 region to view the stacks in progress. The region us-west-2 was set in config.yaml above. Get this working in us-west-2 first before trying other regions on subsequent attempts.

After the appliance has been created, you must destroy the appliance with the following command:

acm appliance off

Confirm in the AWS GUI console that all involved stacks have been deleted before moving on. If you encounter a problem, you can diagnose the problem by examining the logs. If you need help, create a ticket at the project website and someone will respond to help you in a timely manner.

STEP SIX: Run Other CLI Commands

Experiment with other CLI commands after the appliance has been destroyed. The other CLI commands will enable you to create and destroy individual components of the appliance.

The documentation for the CLI commands is at this link.

You can read about the language that defines the objects on which the CLI commands work at this second link.

And you can read about operating on the object model using the CLI at this third link.

STEP SEVEN: Clean Up

Back up keys.yaml and config.yaml someplace safe so that you can re-use them later.

Confirm that all relevant stacks have been deleted by viewing the AWS GUI console’s cloudformation stacks dashboard for the us-east-1 region.

Run acm setup off if you wish.

Confirm that anything you created has now been deleted.

Make sure that there are no keys.yaml or config.yaml in your $USER\acm\keys\starter directory after you backed up those files to a safe location.

Dig Deeper

If you encounter any errors, or if you want to experiment, dig deeper, and potentially cleanup after running “acm appliance on” and “acm appliance off”, you can try reading the instructions at this link

Return to the list of example appliances at this link