Introduction to the Project resource

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 Project.

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.

The Project Resource

A Project resource requires the following configuration:

Required attributeDescription
nameA string identifying the Project
hostThe hostname at which you would like to publish your Project
prefixThe URL prefix at which you would like to publish your Project
githubTokenA token that has access to the repo with your source code
githubRepoThe owner/name of the github repo that holds your source code. The repo must have a Dockerfile located in the root that builds your server and runs it on port 8080.

The 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:

kind: Project
name: <your-project-name>
namespace: <your-project-namespace>
host: <your-hostname>
prefix: <your-project-prefix> # e.g. /foo/
githubRepo: <your-github-org>/<your-github-repo>
githubToken: <your-github-api-token>

Project Repositories

The Project Controller expects Project repositories to have a Dockerfile in the root of the referenced github repo:

+-- Dockerfile // Required: tells the controller how to build your project
+-- project-revision.yaml.tmpl // Optional: allows customization of kubernetes resources
+-- ...

This Dockerfile will be used to build and deploy the Project. 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>

The 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.

How it Works

The Project Controller publishes each Project by:

  1. Building and deploying the default (usually master) branch of the git repo.
  2. Building and staging each open PR at a preview URL. Note that for security reasons, the Project Controller will only build PRs whose base branch is in the repo itself. This prevents third party PRs from being used for nefarious purposes.

The 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>>
| |
| +-----+-----+
| | |
| . 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.../

The ProjectRevision resource

The 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 projectrevisions
foo-07d04b... foo refs/heads/master 07d04b... Deployed 2d
foo-19f77a... foo refs/pull/8/head 19f77a... Building 25s
foo-3d88e5... foo refs/pull/12/head 3d88e5... Deployed 4h
foo-5664e9... foo refs/pull/11/head 5664e9... Deploying 65s

Each ProjectRevision will create a Job to perform the build, and a Deployment + Service + Mapping to publish the commit:

+---> ProjectRevision_1
| |
| +-> Job (builds and pushes the image)
| |
| |
| +---> Deployment (runs the image)
| | /|\
| | |
| +-----> Service
| | /|\
| | |
| +--------> Mapping (publishes the image at /.preview/... or /<prefix>)
+---> ProjectRevision_N

A 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:

ReceivedThe initial state of a ProjecCommit when it is first created.
BuildQueuedWaiting for other builds to finish.
BuildingThe build is in progress.
BuildFailedThe build has failed. This is a terminal state.
DeployingThe commit has been succesfully built and the deploy is in progress.
DeployFailedThe commit has been succesfully built but the deploy has failed. This is a terminal state.
DeployedThe commit has been succesfully built and deployed. This is a terminal state.

There are three terminal states: BuildFailed, DeployFailed, and Deployed. Every 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 kubectl. The Edge Policy Console provides a live streaming in-browser terminal for viewing build and server logs as well as the full state of each ProjectRevision resource.


We’re here to help if you have questions.