diff options
Diffstat (limited to 'docs/deployment.md')
| -rw-r--r-- | docs/deployment.md | 41 |
1 files changed, 41 insertions, 0 deletions
diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..37cef3b --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,41 @@ +# Deployment + +## Service Endpoint Requirements + +Services with HTTP endpoints MUST expose the following endpoints: + +- `/info` - provides version information, git hash, etc +- `/ping` - implements the equivalent of a [Kubernetes liveness probe][1], returning HTTP status header [200 OK][2] if in a running state, or an HTTP status header [500 Error][3] if not. +- `/ready` - implements a Kubernetes readiness probe, returning a [200-OK][2] header if prepared to accept traffic, and a [500-Error][3] header if not. + +In addition: + +- Liveness and Readiness endpoints MUST be different endpoints with different implementations. + +## Rollout Mechanisms + +Types of rollout mechanisms include: + +- ["In-place"][6]: stops the application or server, updates the application out-of-band, then starts the application or server. + This mechanism always causes downtime for clients as the service is not available to service requests during the update. +- ["Blue/Green"][4]: creates a full replica of the existing production environment, running the newer application. + The load-balancer or other routing system points clients at the new replica (once instantiated), then removes the old systems. + This mechanism uses at least twice the total resources required to run an environment for the duration of the transition, at minimum. +- ["Rolling Update"][5]: requires a multi-instance deploymennt. + Removes one node, then spawns at least two nodes in its place. + If the new nodes pass deployment checks, another old node is stopped, while a new node takes its place until the entire original deployment is replaced. + - ["Canary"][7]: a "permanently halted" type of rolling-update. + Canary deployments exist alongside the older deployment, handling a fraction of the total request volume. + When the canary is verified "working correctly," it is turned into a rolling update, and then the next version is deployed as a canary. + +## Deployment Requirements + +- Services with more than one instance MUST use a rolling-update unless otherwise approved by the Architecture Review group. + +[1]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ +[2]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 +[3]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 +[4]: https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/bluegreen-deployments.html +[5]: https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/rolling-deployments.html +[6]: https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/in-place-deployments.html +[7]: https://wa.aws.amazon.com/wellarchitected/2020-07-02T19-33-23/wat.concept.canary-deployment.en.html |