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.

A step-by-step example of using App Imports can be found at App Imports: Connecting two apps.

Setting up App Imports

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.

Single-directional and bi-directional imports

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.

Branch selection

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 the branch 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 branch example, then Release will query GitHub and see if the repository used for backend also has a branch named example. If there is a match, that branch will be used.

3. The tracking_branch attribute set in the Application Template. Remember that tracking_branch is optional so it may not be set.

4. The default (or "main") branch that is set for the repository on GitHub.

Ignoring Deployments

Imports can be set to ignore deployments for specific refs via the ignore_deployment_refs key. An example would be

app_imports
- name: backend
  ignore_deployment_refs:
    - main

In this scenario, if the branch selected for backend is main then whenever a deployment is created, it will be automatically aborted. There is support for negation and path globs as well.

app_imports
- name: backend
  ignore_deployment_refs:
    - "!main"
    - releases/**

In this scenario, if the branch for backend was anything other than main or something like releases/10/20 then the deployment would be automatically aborted.

Ingress environment variables

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.

Mapping environment variables

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.

Environment Variable Mapping Example

Unique service names

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.

Viewing services in the namespace

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.

Managing App Imports via the UI

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.