Flying Circus is a tool for describing AWS infrastructure as code (using
Python). It uses the same data structures as the AWS Cloud Formation service,
except described as Python objects instead of the usual YAML. The Python
program generates a YAML template, which is passed across to Cloud Formation
in the usual manner.
It is a bit unusual to use a full programming language to describe
infrastructure, instead of a static configuration file like many of us are
used to (whether or not we also utilise a templating tool).
We hope that the Flying Circus library can empower DevOps folk by unlocking
some of the techniques that are available for software code, like named
variables and techniques to structure code independently of the output format,
libraries to allow code re-use with versioning, automated refactoring tools
and so on.
You can learn how to use Flying Circus yourself by reading the
documentation
Installation
Install Flying Circus through the Python packaging system:
pip install flying-circus
Many people also use the Amazon Web Services command line tools to deploy
their CloudFormation stacks. If you want this, a good way to install an
up-to-date version is also with pip:
# Optional
pip install awscli
Example
Here is a simple example of how you can use Flying Circus to describe some EC2
instances and deploy them using the AWS CloudFormation service.
First, create a python script (called my_ec2_stack.py in this case) to
describe your infrastructure. Any valid Python can be used to create the
Flying Circus objects, along with any valid CloudFormation properties and
attributes.
This example is intentionally simplistic – it just creates two EC2 instances
with varying configuration, and outputs the internal IP for one. However, it
does hint at some of the more complex and powerful usage patterns.
Now generate CloudFormation YAML from your Python script. Note that the result
will always be valid well-formatted YAML, and internal checks mean that it
is also difficult to generate invalid CloudFormation.
Finally, use the AWS command line tools to create/update a stack and it’s
associated resources.
You could do these steps in your Continuous Integration server 😉
Is/Is Not
There’s a lot of tools for managing Infrastructure as Code, often with subtle
differences and passionate advocates. A quick discussion of our scope may
help you understand where Flying Circus fits into this ecosystem, and whether it can
help you. This is presented in the simple “Is/Is Not” format.
Flying Circus Is…
…a Pythonic DSL for writing fully featured Python code
…a generator that always produces valid, consistent, human-readable, good-practice YAML
Flying Circus Is Not…
…YAML or JSON. It’s Python.
…a tool to make it easier to write YAML or JSON. You write Python, and YAML is an output format.
…a DSL with a completely new syntax. You use normal Python syntax with all
of it’s features and nothing changed.
…a templating language, like Jinja2.
…a template management tool, like Ansible.
…an independent implementation of infrastructure management, like AWS
Cloud Formation stacks, or Terraform.
…a cloud-agnostic abstraction layer.
…multi-cloud – although it could become this in the future.
The current implementation is focused on representing AWS infrastructure
using the CloudFormation data model. Other cloud providers have similar
native data models, so it is feasible that we could re-use the concepts and
tooling to support Google Cloud Platform, etc.
…a tool for interacting with the Cloud Formation service. There
are other tools that can do this for you (such as boto3 or the AWS CLI,
for starters)
…a validation tool – although it could become this in the future, and
already has elements of validation as a by-product of presenting a helpful
interface to users.
Flying Circus is currently in Beta. This means it is expected to work,
and is in use by real customers. However, there is a possibility that the
details of the interface may change in an incompatible way.
I have not been involved with wAMMA or in the making of this demo.
How to get the original files
Download the original Quantum Disco Brothers file from e.g. pouet.net.
If the file is compressed, extract it to get an iNES ROM file (quantum_disco_brothers_by_wAMMA.nes, MD5 hash 2c932e9e8ae7859517905e2539565a89).
Generate the CHR ROM data from chr*.png with nes_chr_encode.py from my NES utilities; see assemble.sh for details.
How to assemble
asm6 quantum.asm "quantum-reassembled_(e).nes" (the (e) in the filename tells FCEUX to start the ROM in PAL mode)
Verify that the .nes file is identical to the original:
diff -q quantum_disco_brothers_by_wAMMA.nes "quantum-reassembled_(e).nes" (on Linux)
fc /b quantum_disco_brothers_by_wAMMA.nes "quantum-reassembled_(e).nes" (on Windows)
Note: the Linux script assemble.sh is intended for my personal use. Do not run it before reading it.
iNES ROM header info
mapper: CNROM (iNES mapper number 3)
PRG ROM: 32 KiB (1 × 32 KiB)
CHR ROM: 32 KiB (4 × 8 KiB)
name table mirroring: horizontal
no trainer
no save RAM
The parts of the demo
Screenshots from FCEUX in PAL mode.
Frame numbers: FCEUX’s Frame Display in PAL mode.
The internal part numbers are at RAM address 0x0001.
1st part (internally part 0, starts at frame ~6): “GREETINGS! WE COME FROM…”; uses CHR bank 0
2nd part (internally part 2, starts at frame 1156): “wAMMA – QUANTUM DISCO BROTHERS”; uses CHR bank 0
3rd part (internally part 11, starts at frame 1923): red&purple gradients; uses CHR bank 1
4th part (internally part 1, starts at frame 2690): horizontal color bars; uses CHR bank 1
5th part (internally part 4, starts at frame 3458): a woman; uses CHR bank 3
6th part (internally part 5, starts at frame 4481): “IT IS FRIDAY…”; uses CHR bank 0
7th part (internally part 7, starts at frame 6362): Coca Cola cans; uses CHR bank 2
8th part (internally part 6, starts at frame 7304): Bowser’s spaceship; uses CHR bank 2
9th part (internally part 3, starts at frame 8071): credits; uses CHR bank 1
10th part (internally part 10, starts at frame 9692): a checkered wavy animation; uses CHR bank 1
11th part (internally part 12, starts at frame 10380): “GREETS TO ALL NINTENDAWGS”; uses CHR bank 2
12th part (internally part 13, starts at frame 11298): “GAME OVER – CONTINUE?”; uses CHR bank 2
13th part (internally part 9, starts at frame 14018): more horizontal color bars; uses CHR bank 2
The demo should probably end at this point, as on this YouTube video.
However, on FCEUX, it starts to glitch from frame ~17603 on.
I omitted the glitchy part from the code/data log file.
An unused part of the demo
There is an unused ninja-themed sequence in the demo.
It was probably meant to be used in place of the 6th part of the demo which displays the same text.
The relevant subroutines are $ec99 and $ed4b (labels init_ninja and anim_ninja in my disassembly).
To see the hidden sequence (although glitched) in place of the second part of the demo,
replace jsr init_title and jsr anim_title with calls to those subroutines or use Game Genie codes OPPYKX + KTPYSX + LGPYNX + STPNEX.
A hidden crescent moon
In the Bowser’s spaceship part, you can make another smaller crescent moon appear with Game Genie code YILVEY:
Code/data log
I created a code/data log file (.cdl) of the ROM using the Code/Data Logger in FCEUX.
The file is in quantum.cdl.gz (gz compressed).
I also converted the CDL file into a human-readable format using my cdl-summary:
https://github.com/garyd203/flying-circus
