Quick start: Overview of Sanic

Sanic is a tool to help you build Docker images and deploy them to a Kubernetes cluster.

Sanic's project structure

The root of a sanic project is a file called sanic.yaml placed in the same directory as .git with something like the following contents:

environments: dev: clusterProvisioner: dummy commands: - name: tests_for_our_project command: echo 'testing dev!' prod: clusterProvisioner: dummy commands: - name: tests_for_our_project command: echo 'testing prod!'

This file is the core of a sanic project: It tells sanic where your project's files are located. The environments key describes places you can build and push to. In this case, we have two.

For a more comprehensive configuration reference, see the README for the project.

Environment specific commands

Notice that in the configuration above, we define a command called "tests_for_our_project". When we sanic run tests_for_our_project, the command run will change depending on which environment we are in. You could use sanic env and sanic run to configure running tests on a per-environment basis.

For more details about sanic run as well as common paradigms, please see the sanic run documentation

Building and Pushing

Sanic recursively finds all files called "Dockerfile" in the project directory and builds them when you type sanic build. Consider the following directory structure: project/ sanic.yaml services/ web/ Dockerfile api/ Dockerfile

In this project, sanic would build images named "web" and "api" if you used sanic build. The tag for the images would be automatically generated from the current files in the repository. At deployment time, simply run sanic build --push to build and push to the registry for your current environment.


After having built and pushed your images, you'll want to create kubernetes manifests to actually run them in a cluster.

When you run sanic deploy, Sanic looks for templated kubernetes .yaml files in deploy/in and templates them to the deploy/out directory.

Sanic then runs sanic kubectl apply -f deploy/out.

Sanic uses docker images for templating, and has official support for go templates and kustomize patches. If your team is already familiar with a specific templating solution, it's easy to add new templating functionality to sanic by creating a new docker image that runs your templater. See the golang templater for a reference implementation. After deploying your image to dockerhub, set it as the value for templaterImage in the deploy section of your sanic.yaml.

Cluster Provisioners

Sanic environments usually define a clusterProvisioner key which tells sanic how to connect to a kubernetes cluster. There are currently two options:

Next Steps

Want to give it a try? Visit the downloads page!