Microservices architecture
Creating applications from multiple repositories
Release works well with both large complex applications and many smaller applications all talking to each other. If you fall into the latter category, our solution to a microservices architecture is the App Imports feature. App Imports creates single-direction dependencies from one application to another with all services being brought up in the same namespace. This means there is one hard requirement for using App Imports: you cannot have two services with the same name. See Unique service names for further explanation.
Here's an example of setting up App Imports in the Application Template:
app_imports:
- name: backend
branch: new-branch
exclude_services:
- name: redis
The documentation for the schema can be viewed in the Application Template guide. In our example, an application
frontend
uses App Imports with an application named backend
.If our
frontend
app adds an app_imports
section to its template to import backend
, then whenever an environment for frontend
is created, an environment for backend
will also be created. This is the single-direction of the import. If someone were to create an environment for backend
, only the environment for backend
would be created.To create bi-directional imports, both applications need to have an
app_imports
section in their template.If bi-directional imports are set up, you will not create an infinite loop. You might think that
frontend
would import backend
which would import frontend
and create an infinite loop, but the import will only occur once with frontend
importing backend
and finishing. This is because:App Imports are not recursive. So if A imports B and B imports A, you will not get ABABABAB. If A imports B and B imports C, you will get AB when you deploy A, and you will get BC when you deploy B, and you will get C when you deploy C. You will not get ABC in any scenario.
This makes it very simple to reason about what will be deployed for a given template. If you see that application A imports B, then you will just deploy A and B and you need not investigate what the application template for B looks like.
Branch selection has a fallback order that includes three different options. They are:
- 1.The branch is set in the Application Template
app_imports
section via thebranch
key as described above. If set, all environments will always use this branch. Remember that the branch attribute is optional in the template. - 2.A matching branch on GitHub. If
frontend
is on branchexample
, then Release will query GitHub and see if the repository used forbackend
also has a branch namedexample
. If there is a match, that branch will be used. - 3.The
tracking_branch
attribute set in the Application Template. Remember thattracking_branch
is optional so it may not be set. - 4.The default (or "main") branch that is set for the repository on GitHub.
Release autogenerates environment variables in the form of
<SERVICE_NAME>_INGRESS_URL
when the service is exposed to the internet. If, for example, backend
has a service named api
, then Release will generate an environment variable named API_INGRESS_URL
. If our frontend
app has a service named web
, then Release will generate the WEB_INGRESS_URL
environment variable too.When using App Imports, the ingress environment variables are shared between between all environments. This means that
frontend
will have access to API_INGRESS_VARIABLE
and its own WEB_INGRESS_URL
, and the same will apply for backend
. Release shares all the environment variables in case two or more imported apps need to be able to communicate.Given that the ingress environment variables are available, you may need to map those to another environment variable your application is expecting. If
frontend
was using the environment variable REACT_APP_BACKEND_API
to talk to its API, then we would want to map the API_INGRESS_URL
to it. This can be achieved using environment variable mapping.%20(2)%20(2)%20(2)%20(3)%20(1)%20(1)%20(1)%20(1)%20(2)%20(3)%20(1)%20(1)%20(1)%20(2)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(2).png?alt=media)
Environment Variable Mapping Example
Warning: Unexpected behavior is caused by using services with the same name.
If
frontend
has a service named api
and backend
has a service named api
, Release will try to deploy two services named api
into the same namespace. By default, Kubernetes will remove the first service and replace it with the second – this is a function of how Kubernetes works and is not Release-specific. To avoid naming conflicts, we suggest adding the name of the application as a prefix to the service name to differentiate between the services in each app, for example, ${app_name}-api
.When using App Imports, all the services are placed into the same namespace. This means that when viewing the "Instances" table on an environment's details page, you will be able to see the services from all the applications.

If you look under the
Namespace
section in the top left, you'll see that the environment jer-k-main
from the application backend
is imported into this namespace. The backend
application defines the api
, db
, redis
, and sidekiq
services, which can see seen in the "Instances" table. The frontend
application defines the app
service, which can also seen.While the App Imports feature is able to be fully controlled through the templates, you can also manage them through the Release UI.
From the Environments page, when creating a new Environment, expand the Advanced Options section to see which Apps are available to use. Apps that are imported in the Application Template show up as preselected with additional Apps listed below. If
branch
is specified in the template, the branch selector will be pre-filled. Use the selector if a specific branch is required, otherwise leave it blank and the branching logic described above will be used.
App Imports during Environment creation
After the Environment has been created, visit the App Imports tab to make changes to which Apps are imported.

Managing App Imports after Environment creation
After selecting a new App to import, this time with a branch and clicking the Save button, the selected App will be saved into the template and move to the top of the list.

Saving a new App Import
If we view the Environment Template, we will see
app_imports:
- name: rails-postgres-redis
- name: angular
branch: main
which matches the visual representation from the UI. After successfully updating, use the Deploy Setup button to start a new deployment with the new imported Apps.
Last modified 4mo ago