Simple Use Cases
The deployment descriptor below is a single-file BOK to start a demonstration rails application. It goes beyond the previous minimal examples in a number of interesting ways:
- This BOK deals with Virtual Private Cloud, as should any serious deploy. Best practices in AWS are to run services in a virtual cloud with an address space that you control, and this has become the default in newer accounts
- The server provisioning is more complex in specifying an image to run (ubuntu), some attached storage, an externally available static IP, and most importantly, a configuration to run to actually create a rails service
- There is a second database service which the server can access thru Mu orchestration
Everything else is left fairly simple ... note no shared firewall rules yet, etc.
Let's walk through some of the differences:
Typically you'll either create a VPC as part of your deployment, or reference a VPC that already exists. A well-made BOK will allow for either alternative.
We introduce some ERB code (between <% and %> that:
Line 2: Invokes a Mu utility function to retrieve all available AWS availability zones from the current account and stores the result in a global $azs variable that will be available from any BOK component or include in this deploy. The ListAZs function is so often used that it's a top level call, usable without the MU:: namespace prefix.
Line 3: In AWS availability zones map to data centers, and sometimes data centers are retired. In that transition process, some availability zones don't support features supported in other zones. To account for this difference in function, which can derail a deploy, users can pass parameters to the mu deploy command to skip provisioning into certain availability zones. Use the -p flag to pass parameters to the mu deploy command. Ex: mu-deploy -p skip-azs.
Line 4: Defines the current_vpc as the VPC the deploying master is running in, as retrieved by another custom MU function, this one namespaced.
CAUTION: This BOK illustrates the use of an RDS relational database, and RDS databases require at least two availability zones in their VPC, regardless of whether they are multizone. If you use the current_vpc functionality and accompanying $use_current parameter (Line 27) you should be sure your current VPC has two public AZs.
We use "provisioning" to describe creating resources, "configuration" to describe bringing the resources into the desired form with the desired capabilities, and "orchestration" to describe relating resources to one another.
Line 11 augments our default provisioning by specifying the SSH user Mu will use to configure the server. Since we're going to be addressing a Ubuntu server we need to access via the ubuntu user, per the usual ubuntu pattern. Sometimes you'll want to specify other users, for example ec2-user for Amazon Linux or RHEL Linux.
Line 16 defines the base AMI to be provisioned and configured. Simply specifying "ubuntu" accesses our default Ubuntu AMI, built into MU. You can configure the defaults or specify a specific AMI of your choice by substituting an ami: "someAMI" directive.
These lines specify a Chef run-list in the form of a single recipe. You can, of course, configure multiple recipes, or Chef roles as well. mu uses Chef as its current configuration service of choice. The recipe for this Rails server is available in a demo site_cookbook.
Lines 21:23 augment our default provisioning by specifying that the server gets a static public IP address. the address will be assigned from the account's pool of unused static IP's, or a new one will be created for the deploy.
The server needs to know about its relationship to its VPC -- which subnets to use, how it can be reached, etc. The vpc stanza inside of server defines that relationship. Note that these lines do not create or declare a VPC, but rather define how the server relates to whichever VPC is declared or created. You'll see similar stanzas in many mu configuration objects, including load balancers, pools, etc.
We determine the VPC to launch the server in, covering three cases:
- Deploy the server to an existing VPC created by the mu tooling (or)
- Deploy the server to the current VPC the master is running in (or)
- Deploy the server to a to-be-created VPC in this BOK
We manage these cases by mu's parameter capability
Parameters are passed to the mu-deploy command using the -p flag. To target a specific VPC, we can pass an existing deploy ID as follows:
mu-deploy –p deploy_id=something.
Line 25: First, look to see if we deployed with a parameter specifying the deploy_id of an existing mu-created VPC. If so, use the existing VPC.
Line 27: Use the current master VPC if the $use_current parameter is present.
Line 30: Otherwise, let's make a VPC of the appropriate shape
The server needs to work in relationship to the other provisioned and configured artifacts. Here we declare a couple of open ports, barely orchestration at all. In more advanced configurations, however, this section is imported as a BOK of its own, and can orchestrate complex interlocking security rules, for example "only open port 8080 of the server to another specified server", etc.
This very simple orchestration example declares that the server depends on the existence of the database and should not be provisioned until the database is deployed.
This section defines and provisions a VPC, to be created when no existing VPC is specified. It's a fairly common pattern, although usually implemented as an include file rather than inline in a single file BOK (see the complex use case wordpress section for an example of the include file pattern.
Line 45: Only create a deploy VPC if one isn't otherwise specified
Lines 46:59: Define the VPC to be created
Lines 54:58: Again use some ERB magic, this time to iterate over the available AZs we retrieved earlier in lines 2 and 3. This simplified code creates a public subnet in each AZ that is available. More complex demonstrations are available in demos that, for example, create a public and private subnet in each available AZ, etc.
In the context of a database resource, configure the VPC. Databases can, for example, be deployed in either public or private subnets.
The logic for selecting a VPC is similar to that in the server, with an addition. In the existing VPC scenarios we introduce the subnet_pref attribute. subnet_pref is a convenient Mu capability that allows you to define what VPC subnets a resource will be deployed into without knowing their names or IDs in advance. This is especially helpful when deploying into a VPC this deploy did not create.
In our example we specify all_public, meaning the DB will be available in all the public AZ's of an external VPC. In the "create your own VPC" stanza we implement ERB code to map to all public subnets, but using all_public there would work as well. **[After we merge in the feature branch!] **
This example includes an AWS RDS database for the rails installation. Provisioning is fairly basic and places the DB in all public subnets, as discussed in our VPC section. A more advanced pattern would create the database in private subnets with minimal changes to the VPC stanza in databases.
Orchestration at the database level is absent in this example -- a more robust example might, for example, configure database firewall rules orchestrated with the server firewall rules to ensure that only servers if a particular tier can reach the database.
These lines define the database provisioning in terms of name, size, the DB engine to use, access port and the like. Many more options are available, see the MU Documentation.
These lines define a VPC provisioning pattern similar to the pattern we discussed in the Server resource. In this case we provision the database in all public subnets, again as discussed in the VPC section.
Note that if this deployment references a VPC with less than two public subnets it will fail based on AWS requirements.
Also note that for simplicity the database uses public subnets, but unless this is a specific requirement, it's a bad idea. Put databases in private subnets, and access them via instances as a general rule.
Administrators are notified of provisioning and other events. Define them in this stanza