Skip to content

Open API Update 1 #804

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 19, 2019
Merged

Open API Update 1 #804

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions ref/general/open-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
// Copyright (c) 2018 IBM Corporation and others.
// Licensed under Creative Commons Attribution-NoDerivatives
// 4.0 International (CC BY-ND 4.0)
// https://creativecommons.org/licenses/by-nd/4.0/
//
// Contributors:
// IBM Corporation
//
:page-description: OpenAPI is a standardized mechanism for developers to describe REST APIs for generating structured documentation in a microservice.
:seo-description: OpenAPI is a standardized mechanism for developers to describe REST APIs for generating structured documentation in a microservice.
:page-layout: general-reference
:page-type: general
= Externalizing configuration in microservices

:MP: MicroProfile
:JWT: Java Web Token
:FT: Fault Tolerance

Microservices move among different environments and resource connection details can change. Externalizing configuration means that you can change configuration values without altering your application code.

== Separating configuration and code

During their lifecycle, microservices are deployed repeatedly across multiple environments- development, test, or production. They need different configurations, for example, deployment-specific external URLs or credentials that change regularly. Microservices must run in these conditions without a change in code.

Backing services require changes in connection details in the application source code, for example, in databases, messaging services, SMTP services, API accessible consumer services, and so on. Each backing service must be attached and detached as a resource to your application, as required, without a code change, or a distinction between a local and external service.

In the cloud, microservices deployed to Kubernetes clusters must communicate. Therefore, port binding, or knowing which port to connect to, is important. As instances of microservices are created and destroyed in Kubernetes to scale the app up and down, port numbers can change. New port numbers must be assigned to microservices and information must be injected into the affected microservices during startup. For more information, see link:https://openliberty.io/guides/kubernetes-microprofile-config.html[Configuring microservices running in Kubernetes].

Thus, it is important to change the configuration of microservices without updating or recompiling the code.

== MicroProfile Config

The MicroProfile Config API externalizes configuration from microservices, keeping it separate from the source code. With MicroProfile Config, external configuration can be injected into services in the containers without repackaging them.

Applications can use MicroProfile Config as a single API to retrieve configuration information from different sources. Configuration data can come from different locations and in different formats – link:/docs/ref/config/[system properties], link:/docs/ref/config/[system environment variables], properties files, XML files, or data sources. In MicroProfile Config, these data sources are called ConfigSources. The same configuration property can be defined in multiple ConfigSources. A prioritization can be used to determine which ConfigSource is used for the property value. Each ConfigSource has a specified priority, which is defined by its ordinal value. A higher ordinal means that the values taken from this ConfigSource override ConfigSources with a lower ordinal value.

=== MicroProfile Config has three default configsources

Default configsources in MicroProfile Config

[cols=",",options="header"]
|===
|ConfigSource |Default ordinal values
|All `META-INF/microprofile-config.properties` found on the class path |100
|Environment variables |300
|System properties |400
|===


An optional default value can be specified by using link:https://www.openliberty.io/docs/ref/microprofile/3.0/#package=org/eclipse/microprofile/config/inject/package-frame.html&class=org/eclipse/microprofile/config/inject/ConfigProperty.html[Java annotations] and applies if the application does not find configuration values in any of the ConfigSources. For more information, see link:https://openliberty.io/guides/microprofile-config-intro.html[Separating configuration from code in microservices].

MicroProfile Config can configure other MicroProfile capabilities. It externalizes configuration of keystores when microservices are secured. For example, in {MP} {JWT}, the public key location and verification can be set in properties files so that if the location of the key repository changes, it can easily be updated. MicroProfile Config is also used in configuration of channel attributes. For example, in {MP} Reactive Messaging, it can set the connection details of messaging channels and connectors, and the topic names that are used by the app to use and produce messages. MicroProfile Config helps in overriding values in fault tolerance. For example, in {MP} {FT}, it can set the value of an annotation so that you can change the value if the tolerance is too low or too high.