Your First Deployment

The Simplest Basket of Kittens

Let's build something! The following is a fully-functional, legal deployment descriptor, or "Basket of Kittens¹," for creating a VPC.

---
appname: myvpc
vpcs:
- name: vpc1

One of Mu's major design principles is to use sensible defaults for common use cases, and this really shines when creating VPCs. Just declaring a VPC by name will cause Mu to deploy a VPC with publicly and privately routed subnets and other associated resources. For an exhaustive list of options for the vpc resource type, see the Basket of Kittens documentation.

Run it!

You can deploy this right away. Copy to a file named something like myvpc.yaml. For this we'll assume that you have at least one set of working cloud provider credentials configured, or are running Mu on a host that has those privileges. See [Configuration] if needed.

$ mu-deploy myvpc.yaml
<... lots and lots of informative status messages ...>
Nov 03 19:56:57 - deploy - Deployment MYVPC-DEV-2019110319-EB "Elite Bobtail" complete

Now if I go look in the cloud provider console, I see a whole lot of stuff that I'm glad I didn't have to build by hand.

Why are things named that way?

Like MYVPC-DEV-2019110319-EB-VPC? Mu assumes that you might create many, many versions of the same set of resources, and so builds a deployment string that's guaranteed to be unique across deployments from a given Mu Master. This helps with billing, tracking, and cleanup.

The first component comes from the appname field of your BoK, in this case myvpc The second component is the environment declared for your deploy, which defaults to dev The third is a date string resolved to the current minute, in this case 2019110319 The fourth is a random pair of two characters to guarantee uniqueness for deploys created simultaneously, in this case EB

Those together are the Mu Deployment ID. This is the primary lookup key for resources in your deploy. For example, the metadata for your deployment is stored in Mu's data directory under this name, /opt/mu/var/deployments/MYVPC-DEV-2019110319-EB or ~/.mu/var/deployments/MYVPC-DEV-2019110319-EB depending on the invoking user and type of Mu installation.

The fifth field is the name of the individual resource, when cloud providers permit appropriate naming/tagging. If we had a server named foo in this deployment, its full name tag would be MYVPC-DEV-2019110319-EB-FOO.

If you'd like to create resources with names exactly as you've written them, and without a lot of ancillary features like Mu's default firewall rules and tags, you can set the scrub_mu_isms flag to true, either at the top level or on individual resources.

How do I get rid of my deployment?

The mu-cleanup command can do this for you. You'll need the deploy id as described above. If invoked without any arguments, mu-cleanup will list deploys for which metadata exists, like:

$ mu-cleanup
Nov 03 20:07:33 - mu-cleanup - Must specify a deploy id. Visible deploys:
K8S-DEV-2019071216-KE
MU-ADOPT-2019091609-DG
MUNETWORK-ADOPT-2019102915-QP
MYVPC-DEV-2019110319-EB
$ mu-cleanup MYVPC-DEV-2019110319-EB
<... lots and lots of informative status messages ...>
Nov 03 20:19:41 - clouds/aws/vpc - Deleting VPC vpc-0de3d4c9044d0553c
Nov 03 20:19:42 - mommacat - Purging /opt/mu/var/deployments/MYVPC-DEV-2019110319-EB

You can invoke mu-cleanup --noop|-n to safely see what would be cleaned up, without actually removing any resources or metadata.

mu-cleanup can still find and cleanse resources if no metadata is present for most (but not all) cloud resources, by searching across visible accounts and examining the tags/labels applied to resources by default.

How would I tell what it's going to before I want to really create things?

mu-deploy has a -d flag for displaying the results of parsing out a Basket of Kittens without creating any resources. Think of it like a SQL EXPLAIN command.

Here's what our 3-line BoK expands to with mu-deploy -d myvpc.yaml, when invoked from a Mu Master with credentials configured for AWS, with a default region of us-east-1:

---
appname: myvpc
vpcs:
- name: vpc
  cloud: AWS
  region: us-east-1
  credentials: egtdev
  us_only: false
  scrub_mu_isms: false
  optional_tags: true
  create_bastion: true
  create_standard_subnets: true
  create_internet_gateway: true
  create_nat_gateway: true
  enable_dns_support: true
  enable_dns_hostnames: true
  nat_gateway_multi_az: false
  auto_accept_peers: true
  route_tables:
  - name: internet
    routes:
    - destination_network: 0.0.0.0/0
      gateway: "#INTERNET"
  - name: private
    routes:
    - destination_network: 0.0.0.0/0
      gateway: "#NAT"
  traffic_type_to_log: all
  enable_traffic_logging: false
  ip_block: 10.0.0.0/16
  peers:
  - vpc:
      id: vpc-abcd1234
      type: vpcs
      cloud: AWS
  availability_zones:
  - us-east-1a
  - us-east-1b
  - us-east-1c
  - us-east-1d
  - us-east-1e
  - us-east-1f
  subnets:
  - name: Subnet0Internet
    availability_zone: us-east-1a
    ip_block: 10.0.0.0/20
    route_table: internet
    map_public_ips: true
    is_public: true
    create_nat_gateway: true
  - name: Subnet0Private
    availability_zone: us-east-1a
    ip_block: 10.0.16.0/20
    route_table: private
    map_public_ips: false
    is_public: false
    create_nat_gateway: false
  - name: Subnet1Internet
    availability_zone: us-east-1b
    ip_block: 10.0.32.0/20
    route_table: internet
    map_public_ips: true
    is_public: true
    create_nat_gateway: false
  - name: Subnet1Private
    availability_zone: us-east-1b
    ip_block: 10.0.48.0/20
    route_table: private
    map_public_ips: false
    is_public: false
    create_nat_gateway: false
  - name: Subnet2Internet
    availability_zone: us-east-1c
    ip_block: 10.0.64.0/20
    route_table: internet
    map_public_ips: true
    is_public: true
    create_nat_gateway: false
  - name: Subnet2Private
    availability_zone: us-east-1c
    ip_block: 10.0.80.0/20
    route_table: private
    map_public_ips: false
    is_public: false
    create_nat_gateway: false
  - name: Subnet3Internet
    availability_zone: us-east-1d
    ip_block: 10.0.96.0/20
    route_table: internet
    map_public_ips: true
    is_public: true
    create_nat_gateway: false
  - name: Subnet3Private
    availability_zone: us-east-1d
    ip_block: 10.0.112.0/20
    route_table: private
    map_public_ips: false
    is_public: false
    create_nat_gateway: false
  - name: Subnet4Internet
    availability_zone: us-east-1e
    ip_block: 10.0.128.0/20
    route_table: internet
    map_public_ips: true
    is_public: true
    create_nat_gateway: false
  - name: Subnet4Private
    availability_zone: us-east-1e
    ip_block: 10.0.144.0/20
    route_table: private
    map_public_ips: false
    is_public: false
    create_nat_gateway: false
  - name: Subnet5Internet
    availability_zone: us-east-1f
    ip_block: 10.0.160.0/20
    route_table: internet
    map_public_ips: true
    is_public: true
    create_nat_gateway: false
  - name: Subnet5Private
    availability_zone: us-east-1f
    ip_block: 10.0.176.0/20
    route_table: private
    map_public_ips: false
    is_public: false
    create_nat_gateway: false
admins:
- name: Mu Administrator
  email: [email protected]
credentials: egtdev
us_only: false

What all did we automatically create with that VPC?

• If no route_tables are declared, Mu will create one public one (direct internet connectivity), and private one (RFC 1918 private address space. You can, naturally, declare your own route_tables.
• If ip_block is not declared, Mu will choose a sensible /16 network.
• If the Mu Master is hosted on a cloud instance in the same cloud provider, and the new VPC's ip_block does not overlap with its own, it will attempt to peer itself to the new VPC.
• If no subnets are explicitly declared, Mu will declare one per zone² per route table. This behavior can be disabled by setting the create_standard_subnets flag to false. Or you can instead explicitly declare your subnets.
• When auto-generating a private route table, and if public subnets are also available, Mu will attempt to create a NAT gateway³. This behavior can be disabled by setting the create_nat_gateway flag to false.
• Similarly, if Mu will not be able to route directly into private networks in our new VPC via peering, Mu will create a virtual machine in a public subnet to serve as bastion or "jump" host. This behavior can be disabled by setting create_bastion to false.
• Depending on the cloud provider, a generic administrative access firewall_rule will also be injected, which allows blanket network access from the Mu Master host to manage resources inside our new VPC.

---

1: We needed a shorthand for individual resources of various types (vpcs, servers, loadbalancers), as well as the group of them and the configuration language to describe them. We like cats, and the name of the toolkit sounds like "mew" if you say it out loud, so.. Basket of Kittens, "grooming", "adoption," etc.

2: In AWS, subnets are a per-availability zone artifact, and so Mu will create one per AZ in the target region. In Google, VPCs are a global artifact, and subnets a regional one, so Mu will create one subnet per region. In Azure, VPCs and subnets are both region one, so Mu will allocate one subnet per route table.

3: Where applicable, Mu will use the cloud provider's NAT Gateway service (currently only AWS supports this). In other providers, we'll create a small virtual machine configured to perform the same function via iptables.