Skip to content
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
158 lines (101 sloc) 6.26 KB

Building Ambassador

If you just want to use Ambassador, check out! You don't need to build anything, and in fact you shouldn't.


If you're making a code change:

git clone
cd ambassador
# Development should be on branches based on the `master` branch
git checkout master
git checkout -b username/feature/my-branch-here

That will build an Ambassador Docker image for you but not push it anywhere. To actually push the image into a registry so that you can use it for Kubernetes, set DOCKER_REGISTRY to a registry that you have permissions to push to.

It is important to use make rather than trying to just do a docker build. Actually assembling a Docker image for Ambassador involves quite a few steps before the image can be built.

If you want to make a doc change, see the Making Documentation Changes section below.


  • The current release of Ambassador lives on master.

  • Ambassador docs currently live on stable. If you are only updating docs, branch from stable.

Making Code Changes

  1. All development must be on branches cut from master.

    • The name of the branch isn't all that relevant, except:
    • A branch whose name starts with nobuild. will skip CI activities. This is intended for e.g. minor doc changes.
  2. If your development takes any significant time, merge master back into your branch regularly.

    • Think "every morning" and "right before submitting a pull request."
  3. When you have things working and tested, submit a pull request back to master.

    • Make sure you merge master into your branch right before submitting the PR!
    • The PR will trigger CI to perform a build and run tests.
    • Tests must be passing for the PR to be merged.
  4. When all is well, maintainers will merge the PR into master.

  5. Maintainers will PR from master into stable for releases.

Making Documentation Changes

  1. Documentation changes happen on branches cut from stable, not master.

  2. It's OK for minor doc changes (fixing typos, etc) to use a nobuild. branch. If you're doing significant changes, let CI run so you can preview the docs -- use a branch name like doc/major-doc-changes or the like.

  3. If you have a doc change open when we do a release, it's your job to merge from stable into your doc branch. You should avoid this.

  4. When you have things edited as you like them, submit a PR back to stable.

  5. Maintainers (code or doc) will merge the PR to stable, then merge the changes from stable back into master.

Developer Quickstart/Inner Loop


  1. git clone ...
  2. From git root type make shell
  3. Run py.test -k tests_i_care_about
  4. Edit code.
  5. Go back to 3.


Note that make shell will do a bunch of setup the first time it runs, but subsequent runs should be instantaneous.

You can create as many dev shells as you want. They will all share the same kubernaut cluster and teleproxy session behind the scenes.

The first time you run the test_ambassador suite it will apply a bunch of yaml to kubernaut cluster used by your dev session. Be patient, this will be much faster the second time.

If you want to release the kubernaut cluster and kill teleproxy, then run make clean-test. This will happen automatically when you run make clean.

If you change networks and your dns configuration changes, you will need to restart teleproxy. You can do this with the make teleproxy-restart target.

Type Hinting

Ambassador uses Python 3 type hinting to help find bugs before runtime. We will not accept changes that aren't hinted -- if you haven't worked with hinting before, a good place to start is the mypy cheat sheet.

We strongly recommend that you use an editor that supports realtime type checking: we at Datawire tend to use PyCharm and VSCode a lot, but many many editors can do this now. We also strongly recommend that you run mypy itself over your code before opening a PR. The easy way to do that is simply

make mypy

after you've done make shell. This will start the mypy daemon and then do a check of all the Ambassador code. There should be no errors and no warnings reported: that will probably be a requirement for all GA releases.

Note well that at present, make mypy will ignore missing imports. We're still sorting out how to best wrangle the various third-party libraries we use, so this seems to make sense for right now -- suggestions welcome on this front!


CI runs Ambassador's test suite on every build. You will be asked to add tests when you add features, and you should never ever commit code with failing unit tests.

For more information on the test suite, see its README.

Version Numbering

Version numbers will be determined by Git tags for actual releases. You are free to pick whatever version numbers you like when doing test builds.

Normal Workflow

  1. export DOCKER_REGISTRY=$registry

    This sets the registry to which to push Docker images and is mandatory.

    "dwflynn" will push to Dockerhub with user dwflynn "" will push to GCR with user flynn

    If you're using Minikube and don't want to push at all, set DOCKER_REGISTRY to "-".

    You can separately tweak the registry from which images will be pulled using AMBASSADOR_REGISTRY. See the files in templates for more here.

  2. Use a private branch cut from master for your work.

  3. Hack away, then make. This will build Docker images, push if needed, then run the tests.

  4. Commit to your feature branch.

    Remember: not to master.

  5. Open a pull request against master when you're ready to ship.

What if I Don't Want to Push My Images?

NOTE WELL: if you're not using Minikube, this is almost certainly a mistake.

But if you are using Minikube, you can set DOCKER_REGISTRY to "-" to prevent pushing the images. The Makefile (deliberately) requires you to set DOCKER_REGISTRY, so you can't just unset it.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.