If you just want to use Ambassador, check out https://www.getambassador.io/! You don't need to build anything, and in fact you shouldn't.
If you're making a code change:
git clone https://github.com/datawire/ambassador cd ambassador # Development should be on branches based on the `master` branch git checkout master git checkout -b username/feature/my-branch-here make DOCKER_REGISTRY=-
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
Ambassador docs currently live on
stable. If you are only updating docs, branch from
Making Code Changes
All development must be on branches cut from
- 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.
If your development takes any significant time, merge master back into your branch regularly.
- Think "every morning" and "right before submitting a pull request."
When you have things working and tested, submit a pull request back to
- Make sure you merge
masterinto 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.
- Make sure you merge
When all is well, maintainers will merge the PR into
Maintainers will PR from
Making Documentation Changes
Documentation changes happen on branches cut from
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-changesor the like.
If you have a doc change open when we do a release, it's your job to merge from
stableinto your doc branch. You should avoid this.
When you have things edited as you like them, submit a PR back to
Maintainers (code or doc) will merge the PR to
stable, then merge the changes from
Developer Quickstart/Inner Loop
- git clone ...
- From git root type
py.test -k tests_i_care_about
- Edit code.
- Go back to 3.
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
make clean-test. This will happen automatically when you run
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.
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
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 numbers will be determined by Git tags for actual releases. You are free to pick whatever version numbers you like when doing test builds.
This sets the registry to which to push Docker images and is mandatory.
"dwflynn" will push to Dockerhub with user
dwflynn"gcr.io/flynn" will push to GCR with user
If you're using Minikube and don't want to push at all, set
You can separately tweak the registry from which images will be pulled using
AMBASSADOR_REGISTRY. See the files in
templatesfor more here.
Use a private branch cut from
masterfor your work.
Hack away, then
make. This will build Docker images, push if needed, then run the tests.
Commit to your feature branch.
Remember: not to
Open a pull request against
masterwhen 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.