> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/guides-and-examples/advanced-guides/microservices-architecture.md). # 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](#unique-service-names) for further explanation. A step-by-step example of using App Imports can be found at [App Imports: Connecting two apps](/guides-and-examples/common-setup-examples/app-imports-connecting-two-apps-together.md). ## 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](/reference-documentation/application-settings/application-template.md#app-imports). 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: {% hint style="warning" %} 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. {% endhint %} ## 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 `_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](/reference-documentation/environment-settings/environment-specific-environment-variables/environment-variable-mappings.md). ![Environment Variable Mapping Example](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-14b08ff72ac298c38cda210e2e4f1f5d60805534%2Fenv_var_mapping%20\(1\).png?alt=media) ## Unique service names {% hint style="danger" %} Warning: Unexpected behavior is caused by using services with the same name. {% endhint %} 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. ![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-2d06fea550ca6517e9243da8c54b01b4b911b20b%2Fnamespace_instances.png?alt=media) 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 ```yaml 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.release.com/guides-and-examples/advanced-guides/microservices-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.