Skip to content

Deployment Guidelines

A Microservices architecture makes it possible to isolate failures through well-defined service boundaries. But like in every distributed system, there is a higher chance for network, hardware or application level issues. As a consequence of service dependencies, any component can be temporarily unavailable for their consumers. To minimize the impact of partial outages we need to build fault tolerant services that can gracefully respond to certain types of outages.

Containers & Images

Docker Usage

Docker MUST be used as the default container management tool.

Each Microservice MUST use and declare a single Dockerfile.

Docker Images

A Microservice MUST be packaged in a single image. This is meant to ease the containers orchestration.

Each image SHOULD be properly tagged.

It is RECOMMENDED to use alpine linux as a base image and install only the needed system libraries to keep the container image as small as posible.

It is RECOMMENDED to use a multi-stage build to keep the image small.

It is RECOMMENDED to use ctdesarrollo custom docker base images to build a Microservice: https://hub.docker.com/u/ctdesarrollo

To ease development YOU SHOULD include a docker-compose manifest to declare all infrastructure dev-dependencies.

Infrastructure

Infrastructure as Code

Infrastructure as Code (IaC) is the management of infrastructure (networks, virtual machines, load balancers, and connection topology) in a descriptive model, using the same versioning as DevOps team uses for source code.

Any kind of infrastructure configuration and/or adjustments MUST be included in the /etc/(service) folder as part of the Microservice source code. Ex.: /etc/php-fm, /etc/nginx

A Microservice MUST expose port 8080 to handle HTTP traffic only.

The external infrastructure (Databases, Message Queues, Caches, SMTP Servers, etc) MUST NOT be containerized and credentials to these production servers will be provided by the teams in their own cloud projects.

Orchestration

Kubernetes (aka K8S)

Kubernetes MUST be used as the default container orchestration tool.

Each Microservice MUST include all Kubernetes manifests in the /etc/kubernetes/ folder as part of the app code repository.

It is RECOMMENDED to adhere to a K8s manifest filename pattern:

  • deployment.yml: Deployment declaration manifest

  • service.yml: The k8s service manifest

  • config.yml: The config Map Reference

  • hpa.yml: The Horizontal-Pod Autoscaler (if needed)

  • secret.yml: The “secrets” (credentials/sensitive information) service reference

It is RECOMMENDED that the namespace follows the same pattern used to name the main Bounded Context. Examples: teaching-action, academic-administration

Ownership

You build it, you run it

Enterprise DevOps: Why You Should Run What You Build

Each team MUST manage and monitor their own Kubernetes Cluster and infrastructure.

Each Microservice MUST be deployed ONLY in its assigned Kubernetes Cluster.

The Microservices MUST NOT control any type of API Authentication. This is provided by a Cluster-Wide Ingress implementing the API Gateway pattern.

Following the DevOps Culture, the Cluster monitoring, performance tuning and/or failures MUST be performed by its own team.

Deployment

It is RECOMMENDED to deploy an HPA (Horizontal Pod Autoscaler) based on CPU and/or memory usage to handle intensive traffic.

It is RECOMMENDED to use cluster-wide Api-Keys for the Microservices APIs, but this SHOULD be handled by each team(s).

The Microservice MUST handle the X-Request-Path custom header. This allows the API url to be customized directly in the cluster API Gateway and not hard-coded in the Microservice path.