1. “One codebase tracked in revision control, many deploys”

The code that runs an application has to come from one and only one code repository. For example, a single git repository. It also means that you deploy the same codebase in all of your application environments. Your development, testing and production environments should all run the same code from the same repository.

This is a good constraint because it means that we’ll always know where the code for the application resides. That means that when we need to maintain our application our troubleshoot a problem, we won’t waste any time or energy hunting down the location of the source code. Most importantly, it means that we don’t need to worry about understanding a nest of dependencies between code repositories in order to understand how our application works.

It’s really important that we follow this practice for our Microservices build. We should treat each microservice as if it’s an application. That means that each of our microservices should have its own code base and its own repository. It also means that our microservice code should exist in only one code base and we use that code base for all of the environments that we deploy our service into.

2. “Explicitly declare and isolate dependencies”

When we follow the first factor, the code for the application will be contained in a single codebase. But in practice our code will still depend on other libraries, frameworks or components in order to run. For example, if we are writing a NodeJS application, we’ll probably import a few Node modules so we don’t have to re-invent code for problems that have already been solved.

The second factor helps us deal with those dependencies by stating that all of the application’s dependencies need to explicitly declared. That means that our application needs to be able to define exactly which libraries, components or modules it needs in order to run. It also means that the environment that the application runs within should only contain those dependencies.

Declaring dependencies explicitly and isolating them from the libraries and components that may already exist in a run-time environment is an important practice. If you’ve ever had to maintain an application that doesn’t explicitly define its dependencies you’ll know why. No one wants to waste time having to reverse engineer an application they’ve inherited in order to find out which libraries need to be installed for it to run properly. We also don’t want to deal with uncertainty about how the application will run in different environments because we haven’t been able to isolate dependencies properly.

Instead, we should build applications with frameworks that allow us to define dependencies in a readable and parseable form. For example, if we use NodeJS we’ll be able to define the dependencies for our code in a package.json file. We’ll also need to use tools and platform that can isolate those dependencies and prevent other libraries or modules from “leaking” into our application’s runtime environment.

This constraint is really important for our Microservices system. As we start to scale up the number of microservices we write and operate, it’s vital that we keep the predictability of our services high and the cost of maintenance and learning the code low. To make that happen, we’ll need to be careful we are choosing which programming languages, frameworks and deployment tools we want to use when we build our Microservices.

3. “Store config in the environment”

We’ve seen that a twelve factor application is built on a single codebase that declares its dependencies. So far, so good. But, in practice, its difficult to deploy the same codebase to multiple environments because each environment will have its own particular details. For example, the location of a shared database in production environment may have a different address than the database in a development environment.

To address the variable nature of different environments, it’s common to have the application depend on configurable values that are unique for each environment that the application is deployed in. That way, we can keep a single code base that references configurable values or properties and just change those values depending on where we deploy the application. These values become another dependency that we can explicitly declare and isolate.

Those configurable values can be stored in a lot of different ways. You could keep values in a properties file that you deploy with the application and maintain one file per environment. You could keep configurable values in a central database that all of your applications can access. You could even inject values into the code as part of the deployment process on an environment-by-environment basis.

But, the third factor of the 12 factor method tells us that we must keep those configurable values in the environment that we are deploying into. In fact, it specifically says that the environment-specific configurable values must be stored as environment values. This leads to two good outcomes:

1. The configuration is managed and stored separately from the code, which makes the code easier to manage and maintain.

2. Configuration values are easily manageable in a platform agnostic way (since most operating systems and languages support retrieval of environment variables)

This is a good constraint to introduce for our microservices as well. Each microservice should be deployable as an independent unit that relies on environment variables to define environment specific behaviour. Writing our microservices this way will help us to maintain a single code base, while supporting deployment of those services in many different environments and configurations. But building this way means we’ll need to be purposefully design our infrastructure to provide config as environment variables to our services.

4. “Treat backing services as attached resources”

Applications can have lots of different dependencies. We’ve talked a bit already about libraries and code modules, but applications often need to interact with other running processes or services. For example, it’s pretty common for an applications to access a shared database. Its also bcoming increasingly common for applications to depend on services that are managed by someone else. For example, an application that needs to send SMS messages might use a cloud based API that can send SMS messages. How should all of these backing services be managed?

The 12 factor approach advocates that we treat all of these services as addressable resources that can be swapped in and out as needed. Another way to say this is that the application and the service it uses should be loosely coupled in terms of its specific network address. Taking this further, it means that the deployment team should be able to specify which specific network instance of a backing service an application uses at deployment time.

It’s useful to manage the backing services of an application (or our microservices) this way because it empowers our operations and deployment teams to make changes at runtime. For example, if we abide by this factor we could design a microservice that uses a configurable URI to locate and connect to a backing database. Building our service this way means that our operations team can point our service to a specific database instance without co-ordinating with the development team that built the service.

That kind of freedom will allow us to build an environment that is more configurable and flexible. It means that we can make changes to backend services without going through the work of changing code and re-buildling applications - as long as we have a running service to point the application towards.

5. “Strictly separate build and run stages”

A lot of the factors we’ve covered so far depend on one particularly important constraint: that we won’t change our application code once it’s in the deployment environment. Twelve factor applications have distinct release and run stages for their code. Application code changes always flow in a single direction through each of these phases consecutively.

In the build stage, the code is transformed into an executable bundle. Depending on the language that the application is written in, this may mean compiling your code. But, the build stage isn’t limited to code compilation. Instead, it’s a bundling of all the complied binaries, interpretable code, dependencies and assets that the application needs in order to run in target environments. All applications have a build stage, even if they are written in a language that doesn’t need to be complied.

In the deployment stage the bundled application is deployed into an environment. Specialised tools can be used to deploy the application bundle and the deployment release can be versioned to keep track of changes. Once the application is deployed, it transitions into the run stage in which the application process is started using the bundled assets that were deployed.

One of the advantages of separating these stages is that it allows us to separate the types of work and changes that we want to perform on the application. In particular, it means that once we have built the application, we can’t make any changes to the code unless we start over with the build, release and run process. Adhering to this constraint means that we will allways know what we are running in our production environment. It also means that we can easily re-release our application in a predictable way.

This is an important attribute for our microservices system. As the number of microservices that we need to manage grows, its important that we know that our environments and services can be easily re-built.

6. “Execute the app as one or more stateless processes”

When a twelve factor application is deployed, it is run as one or more executable processes. That means, we can transition the application into a running state by starting one of its process in an execution environment. For example, a NodeJS-based tweleve factor application could be run using a shell script that starts its node server along with the accompanying javascript code files. Similarly, A docker based containerized application could be run by starting a container process for the application.

Executing an application by starting one or more processes isn’t a particularly novel idea. But, the tweleve factor application also needs to abide by a special caveat: it needs to be run as a stateless process. That means that the application can’t retain any permanent or persistent data in it’s execution processes. For example, a twelve factor shopping application might allow its users to store items in a shopping basket. But, it wouldn’t be able to keep that customer’s shopping basket data in the execution process alone.

Of course, the application processes will need to store temporary (or ephemeral) data. Our shopping application will still need to have access to a shopping basket in order to serve our users. The key to this constraint is that any data contained in our application process doesn’t need to live longer than the process itself. That means we should be able to kill a twelve factor application process and start it again without losing the data our application needs to serve its users. In practice, that means that applications depend on backing services and databases to store information that needs to outlive the process itself.

Building applications as stateless processes comes with a cost. The application will need to manage a lot more dependencies to access and store persistent data. There will also be a rising latency cost as the application needs to interact with components over the network in order to serve requests that use that persistent data. That can result in complex caching and data synchronization implementations in the application to counter that performance cost.

But, the payoff for going with stateless process comes in the way that the application can be scaled and managed in the execution environment. With this constraint, we know that the impact of killing any individual twelve factor application process is limited entirely to its ability to serve requests. That means, we are free to dynamically scale, replace and clone application processes as needed. If we want to maintain continuous availability, we only need to ensure that at least one application process is running to serve requests.

Running an application as a stateless process is an important property. It makes it easier to run an application as a self-contained unit that can be independently deployed and managed. This is a characteristic that we want for our microservices as well. To achieve this, we’ll need to be diligent about how we design our services, how we manage their data and how we package them for execution.

Remember that stateless processes doesn’t mean that our Microservices won’t have to deal with state. It only means that the state of a microservice isn’t bound to the executable process it is running within. That means we may need to rely on shared data stores, caching mechanisms and data synchronization techniques. In fact, dealing with this conflict of stateless processes and stateful data is one of the most difficult problems to solve in a Microservices architecture. We’ll dive into it in more detail in Chapter TK when we talk about Microservices data.

7. “Export services via port binding”

Web-based applications use the HTTP protocol to listen for message based requests that they can service. To do that, they need to bind to a TCP/IP address and port. This is the network address that consumers of the application will send requests into. Most application developers understand that this is how their web-based applications need to work - but, very few of those developers have the experience and knowledge to implement a production-grade web server for their application.

Write code to handle HTTP based communication at scale is a non-trivial exercise. So, it makes sense for application developers to use tools, frameworks, libraries and servers that will do this work for them. In the early days of web application development, it was common practice to write application code that would be deployed into an HTTP based application server. In this way, the server would handle the complexities of communication and invoke instances of the application as part of the server process.

The seventh factor forbids this type of server container architecture. Instead, a twelve factor application must implement it’s own HTTP server and bind to a TCP/IP port itself. When the application process is started, it binds to a network address and listens for messages that it can service. This doesn’t mean that the application developer has to write this code themselves. Instead it means that the application bundle must contain its own server libraries and dependencies that are instantiated and managed by the application itself. Instead of the application being deployed in the server, the server is embedded into the application.

Another way of saying this is that the application becomes self-contained. It means that we can deploy the application as a single executable bundle and run it by starting a single state-less process. The benefit of this approach is that we do not have to maintain and tune shared server containers that may differ from environment to environment. Instead, we can maintain and deploy application bundles individually. But keep in mind, we’ll still need to scale, co-ordinate and secure these network bound application processes.

This seventh factor is a key part of what defines an application as a microservices. The birth of the microservices style of architecture has its roots in this shift towards self-contained, independently deployable applications that bind to a port. The principle of self-containment and encapsulation lead architects down a road towards smaller bounded applications that could be easier to develop and maintain. So, this will be an easy factor for us to incorporate into our design.

8. “Scale out via the process model”

One of the advantages of running our application within stateless processes is that it becomes easier to scale. The eighth factor addresses this scalability specifically by mandating that we should scale our applications only by replicating execution processes. This is commonly referred to as “scaling out"as opposed to “scaling up” an application.

When we scale up an application, we give it additional resources to help it cope with an increase in demand or utilisation. The problem with this approach is that it requires a diagnostic, hands-on approach for each server that needs to be managed in a system. In order to scale an application up, we need to understand how its resources are currently being utilised and what steps need to be taken in order to help it continue to operate properly. This can work well when we are managing a single monolothic application, but doesn’t work as well when we have multiple applications which may each have multiple processes.

Instead, the twelve factor application is designed to be scaled out through its executable processes. For example, an e-commerce application can be scaled out by spinning up additional worker processes that handle web requests as more customers use the site. These worker processes can be killed once the demand goes back down again. Approaching scalability this way reduces the cost and complexity of managing our application. A more modern version of scaling out would be the management of a cluster of containers for a dockerized application. We only need to manage the number of processes running rather than the complex allocation of resources to an application.

Process-based scalability is a useful property for our microservices to have, so we’ll need to design our systems and services to behave this way. We want to have the freedom to dynamically and elastically grow, shrink and maintain our microservices as needed. But, to do this, we’ll need to be able to manage our microservices as interchangeable biological cells that collectively perform work instead of whole organisms that retain their own unique identities and state. But, process based management can be complicated - especially at scale. So, we’ll need to think carefully about how we will manage all of our microservices processes.

9. “Maximise robustness with fast startup and graceful shutdown”

So far, we’ve described how a twelve factor application needs to be run in a stateless process designed to be scaled out rather than up. But, the ninth factor highlights an important practical consideration for us to benefit from stateless processes. Our applications need to be optimised to run in this stateless, replaceable way.

A twelve factor application needs to be more than just an existing application that has been modified to run in a stateless process. It needs to be purposefully designed. That means, that care has been taken to reduce the startup time. It means that it has been designed to be shutdown when needed. It also means that the application can handle unexpected termination in a graceful manner.

By purposefully designing an application to handle these lifecycle events, we improve its robustness. The robustness of a software application indicates its ability to react appropriately to unexpected and unforseen conditions. Increasing the robustness of an application improves the overall stability and resiliency of our system, because it means that our application is less likely to introduce instability to our execution environment when unexpected activity occurs. Most importantly, it means that we can exert less effort in managing individual application processes in our execution environment.

This is an important quality for our microservices to have. We’ve already mentioned that microserivces shift a lot of complexity into the underlying system and architecture. But, microservices that are designed to be executed statelessly can reduce a lot of the management cost. Knowing that we can destroy and create individual processes of a microservice quickly and safely reduces a great deal of operational burden. It means, we can automate scaling and resilience processes for our services. Taking this further, we could even introduce tooling to manage microservices processes entirely. We’ll see some examples of that when we tackle our Microservices infrastructure in chapter TK.

10. “Keep development, staging, and production as similar as possible”

While most of the twelve factors relate to how the application is designed and managed, this factor describes a more general goal. The execution environments that the application will run in should be as similar as possible. That means that the development, testing and production environments should have as little variation as possible in terms of the configuration of the infrastructure, the software that is installed and the backing services and dependencies that are deployed.

Deploying applications into environments that are as similar will result in less unexpected behaviour when the application is deployed into a production environment. It also eases the work of troubleshooting production issues because non-production testing environments operate in a similar fashion to production. There is great benefit to removing environment variability, but it takes a lot work to pull it off.

Even if we start out by building similar environments, it is difficult to avoid the inevitable “drift” that happens as we make changes. As part of the work of application deployment we are bound to make small changes. Over time and at scale, these changes don’t get reflected back into other environments and we end up in a situation where it is difficult to predict how an application will behave because there is enough variation to create uncertainty.

This is a problem worth solving for our Microservices system as well. As the number of services grows, it is important to be able to test and deploy changes to services as efficiently as possible. If our environments are not similar, the cost of managing change for our microservices estate will grown uncontrollably.

Resolving this variation will require a concerted DevOps oriented effort that touches all parts of the microservices delivery lifecycle. We’ll need to be able to replicate backing services across environments, eliminate human operator “one-off” changes and make our infrastructure changes repeatable and predictable. We’ll dive into this problem in more detail in chapter TK when we build our Microservices DevOps pipeline.

11. “Treat logs as event streams”

Logs are an important part of any application. Without them we don’t have the visibility and observability we need in order to troubleshoot problems, improve efficiency or improve the product it delivers. The application logging domain is inherently a data domain. A good logging solution involves capturing data, normalizing it, categorizing it, persisting it, archiving it and making it searchable and usable.

But, the twelve factor application is purposefully designed to avoid the complexity of the logging implementation. Instead its only responsibility is to send long messages to an output stream that can be captured by the underlying system and routed to the appropriate location. This gives the operations team the freedom to implement a platform logging system that makes sense for the domain. The ops team only needs to capture the log messages that the application produces and handle them appropriately. This is similar to the way an operations team can manage application logs in a Unix based system.

It’s a good constraint to introduce to our microservices as well. By limiting the scope of logging to the emission of logs to a Unix pipe-like stream, we can reduce the development and maintenance load on our microservices developers. We’ll still have to design and develop the underlying logging system, but this loose coupling allows us to address the logging solution in an encapsulated, separate way.

12. “Run admin/management tasks as one-off processes”

When an application is in a running state, there is sometimes a need to run administrative, management or maintenance processes against it. For example, an application may need to migrate data form an existing schema to a new one. Or the application may need to have some data records and processes removed in order to avoid over-runing resource usage limits and remain in a “steady state”.

A twelve factor app allows for these types of activities to occur, but mandates that they must be run as one-off processes. That means that these types of administration and management tasks shouldn’t be run in the execution process that provides runtime functionality. Instead, they should be run as standalone, one-off processes that can be executed alongside the application’s execution process. These management and administrative executables should be shipped as part of the application bundle.

It’s vital that we keep our microservices in a steady state so that we can run them at scale and have them operate predictably and resiliently. For example, suppose we need to run eight process instances of the same microservice deployment, each containing its own temporary data storage. what happens if we run out of storage space? How do we manage and maintain that space across all of the process instances that we need to run? It makes sense for our microservices to provide administrative process to keep them running safely.

But, we also have an opportunity to minimise our need for these kinds of clean-up activities. Applications need run-time maintenance because they degrade or grow stale over time. But, what if we never let our applications grow old and unstable? If we simply killed an application process and launched it again every week (or every night, or every hour) our application would likely be running clean because it wouldn’t have a chance to become unsteady.

This is the essence of the principle of disposability. We’ll endeavour to build our microservices this way so that we can minimise the amount of administration and management processing that will be needed to run them. We’ll even try to build our infrastructure with disposability so that it can be re-built (or “re-hydrated”) on a regular basis. If we build our Microservices architecture correctly this last factor of the twelve factor app should be an easy one to incorporate.