ir.md

Ambassador operates by reading its configuration resources and constructing an intermediate representation (IR), which is used to build the Envoy configuration. The IR dates pretty far back in Ambassador's life, and largely grew up under the demands of quickly supporting Ambassador's ability to group Mappings to handle the various types of deployments, so it’s emphatically not pretty, and we’re at the point now where it costs us development velocity. It needs a lot of improving.

We’re going to get together as a group and discuss what kind of improvements to make and how to go about them, and you’re invited to participate. We'll be dealing more in terms of concepts and structure than literal code, so we expect to be talking more about data structures and objects, less about syntax and formatting.

You’ll need to have a handle on how Ambassador works with the IR for this, so you’ll need to start by grabbing and building the Ambassador source code:

git clone [email protected]:datawire/ambassador.git
cd ambassador

# This DOCKER_REGISTRY setting is not a typo: a single - means not to do a docker push
make DOCKER_REGISTRY=- version setup-develop

The build process creates a virtualenv, and you’ll need to have that activated to do any real work with Ambassador:

# you will need to run this for every shell
source venv/bin/activate

# this is just a sanity check
ambassador --version

Once you have everything set up, you can try some of the following to see how things work. Fair warning: there are several directories named ambassador, so $git_root is used to mean the top of the Git repo.

1. Ambassador has a CLI command to dump the IR directly.

   • The CLI lives in $git_root/ambassador/ambassador/cli.py
   • ambassador dump $config_dir will parse the Ambassador configuration in $config_dir, build the IR and dump it as JSON to stdout.
   • A sample default configuration is in $git_root/ambassador/default-config. Others are in $git_root/ambassador/tests/: each test has a config directory.

2. Ambassador has a diagnostics service that uses the IR to build a human-readable display.

   • The diag service lives in $git_root/ambassador/ambassador_diag/diagd.py.
   • You can run it for testing with diagd --no-checks $config_dir; point a web browser to http://localhost:8877/ambassador/v0/diag/ (*Note well that you need that whole path; just pointing a browser at the root URL will give you a 404.)

3. Most of the IR code itself is in the Config class.

   • This lives in $git_root/ambassador/ambassador/config.py
   • Its __init__ method instantiates the object, parses an Ambassador config, and builds the IR -- there is no separate parse step.