How it works
Forge builds services based on Docker and Kubernetes. It assumes the output of any service build consists of one or more docker containers along with the kubernetes yaml necessary to spin up these containers. The build process consists of the following stages:
- Find service definitions.
- Compute versions for all input sources.
- Build, tag, and push any missing containers.
- Build and apply the kubernetes yaml.
Forge finds services by searching the filesystem for any file named
service.yaml. Any directory containing such a file is assumed to
following a standard layout:
root | +-- service.yaml # identifies this directory as a service and contains key metadata | +-- k8s/* # deployment templates (jinja2) | +-- **/Dockerfile # one or more container definitions
Forge automatically computes a version for any service it builds. If
the service is located in an unmodified git tree, forge will use
<commit>.git as the version. If the service is not located in a git
tree, or the git tree has changes, forge will compute the sha1 hash of
the filesystem tree for all the services and use a version of the form
<sha1hash>.ephemeral. This enables forge to be conveniently used for
dev builds, but also retains complete traceability for production
Forge computes canonical container image names based on the configured
docker registry, repo, and the computed service names. It then queries
for the existence of these canonical images both remotely and locally,
and if necessary it invokes
docker build in order to build, tag, and
push missing containers.
Note if you are wondering how to avoid including lots of build tools
in your containers, check out docker's
Building Kubernetes yaml
The kubernetes yaml necessary to deploy the containers associated with
a service is produced from the jinja2 templates in the
directory. These templates are invoked with both the service metadata
service.yaml), as well as the build metadata.
service | +-- name # this is defaulted based on directory name if not explicitly specified in service.yaml | +-- ... # any other variables defined in service.yaml build | +-- images # map from Dockerfile relative path to built image name
After generating the kubernetes yaml for all services, forge validates the yaml and ensures that there are no resource name conflicts between services.
Still have questions? Ask in our Gitter chatroom or file an issue on GitHub.