This feature is in BETA. Please tell me (lead developer of the feature) about your experience.
Please note that the Project functionality is disabled by default. See The Project Quickstart for instructions on enabling the Project Controller and setting up your first
Ambassador is designed around a declarative, self-service management model. The
Project resource takes self-service, declarative configuration, and gitops to the next level by enabling developers to stage and deploy code with nothing more than a github repository.
Project resource requires the following configuration:
|A string identifying the |
|The hostname at which you would like to publish your |
|The URL prefix at which you would like to publish your |
|A token that has access to the repo with your source code|
Edge Policy Console provides a streamlined self-service workflow for creating a
Project resource, but you can define projects just like any other kubernetes resource:
---apiVersion: getambassador.io/v2kind: Projectmetadata:name: <your-project-name>namespace: <your-project-namespace>spec:host: <your-hostname>prefix: <your-project-prefix> # e.g. /foo/githubRepo: <your-github-org>/<your-github-repo>githubToken: <your-github-api-token>
Project Controller expects
Project repositories to have a
Dockerfile in the root of the referenced github repo:
<root>|+-- Dockerfile // Required: tells the controller how to build your project|+-- project-revision.yaml.tmpl // Optional: allows customization of kubernetes resources|+-- ...
Dockerfile will be used to build and deploy the
Dockerfile MUST include an
EXPOSE 8080 instruction, and the server's code MUST be written to bind to port 8080:
FROM <your-base-image>...RUN <your-build-instructions>...EXPOSE 8080 # PLEASE NOTE: Your code must bind to port 8080 also!!CMD <your-server>
project-revision.yaml.tmpl is optional. When present, the contents of this file are evaluated as a golang template, and then used to deploy each revision. See Customizing Project Deployment for more details.
Project Controller publishes each
- Building and deploying the default (usually master) branch of the git repo.
- Building and staging each open PR at a preview URL. Note that for security reasons, the
Project Controllerwill only build PRs whose base branch is in the repo itself. This prevents third party PRs from being used for nefarious purposes.
Project Controller automatically registers a webhook so that it is notified whenever PRs are opened or closed or code changes are pushed. This allows the
Project Controller to automatically and continuously reconcile the cluster state with the git repo and rebuild/restage each PR as well as rebuild/redeploy the default branch as needed.
For example, if the foo
Project points to a repo with 3 open feature branches, the foo
Project will stage 3 commits and deploy 1 commit as depicted below:
. <<Project>> <====> <<Repo>>foo github.com/octocat/foo| || +-----+-----+| | || . PRs . Branches| . .| . .| . master ---------+| PR#1 ---> feature-1 -----+ || PR#2 ---> feature-2 ---+ | || PR#3 ---> feature-3 -+ | | || | | | | Commits\|/ | | | |+----------ProjectRevision_3----------> 3234abc... <--+ | | || +--------ProjectRevision_2----------> 2234abc... <----+ | || | +------ProjectRevision_1----------> 1234abc... <------+ || | | +----ProjectRevision_0----------> 0234abc... <--------+| | | || | | || | | +--> https://<host>/<prefix>/| | +----> https://<host>/.preview/<prefix>/1234abc.../| +------> https://<host>/.preview/<prefix>/2234abc.../+--------> https://<host>/.preview/<prefix>/3234abc.../
Project resource accomplishes its goals by delegating to the
ProjectRevision resource which in turn manages a number of other kubernetes resources. The
Project Controller will create a
ProjectRevision for every git commit that is to be staged or deployed:
$ kubectl get projectrevisionsNAME PROJECT REF REV STATUS AGEfoo-07d04b... foo refs/heads/master 07d04b... Deployed 2dfoo-19f77a... foo refs/pull/8/head 19f77a... Building 25sfoo-3d88e5... foo refs/pull/12/head 3d88e5... Deployed 4hfoo-5664e9... foo refs/pull/11/head 5664e9... Deploying 65s
ProjectRevision will create a
Job to perform the build, and a
Mapping to publish the commit:
Project|+---> ProjectRevision_1| || +-> Job (builds and pushes the image)| || || +---> Deployment (runs the image)| | /|\| | || +-----> Service| | /|\| | || +--------> Mapping (publishes the image at /.preview/... or /<prefix>)|+...|+---> ProjectRevision_N
ProjectRevision progresses through different phases in its lifecycle as it attempts to build and run your server. The
phase of a
ProjectRevision (stored in the status.phase field) tells us exactly what it is doing and what has happened:
|Received||The initial state of a ProjecCommit when it is first created.|
|BuildQueued||Waiting for other builds to finish.|
|Building||The build is in progress.|
|BuildFailed||The build has failed. This is a terminal state.|
|Deploying||The commit has been succesfully built and the deploy is in progress.|
|DeployFailed||The commit has been succesfully built but the deploy has failed. This is a terminal state.|
|Deployed||The commit has been succesfully built and deployed. This is a terminal state.|
There are three terminal states:
ProjectRevision will progress through its lifecycle
until it reaches one of these stages.
The resources managed by each project are prefixed by the project name and the commit sha so that you can easily drill down and examine e.g. the build or server logs using
Edge Policy Console provides a live streaming in-browser terminal for viewing build and server logs as well as the full state of each