Adding documentation for versioning feature (#828)

inspectit-ocelot-documentation/docs/config-server/agent-mappings.md

@@ -3,35 +3,39 @@ id: agent-mappings
 title: Agent Mappings
 ---
 
-Agent mappings are used to determine which agent receives which configuration.
+Agent mappings are used to determine which agent receives which configuration. Here, individual files or specific folders can be defined, which serve as the basis for the resulting configuration. Furthermore, you can specify which branch (`WORKSPACE` or `LIVE`) the mapping should use to obtain the configuration files.
+
 It's important to note that the first matching agent mapping will be used to determine which configuration is shipped to an agent.
 Additional agent mappings which may also match the attributes list sent by an agent will be ignored.
 See section [HTTP-based Configuration](configuration/external-configuration-sources.md#http-based-configuration) for information on how to specify which attributes will be sent by an agent.
 
 An agent mapping consists of the following properties:
 
-| Property | Note |
-| --- | --- |
-| `name` | The name of the agent mapping. |
-| `sources` | A list of paths. All configuration files matching this list (Directories are resolved recursively) will be merged together and returned to matching agents. |
-| `attributes` | A map of attributes. This map is used to determine whether an agent will match this agent mapping, thus, get its configuration. |
+| Property | Default | Note |
+| --- | --- | --- |
+| `name` | - | The name of the agent mapping. |
+| `sources` | `[]` | A list of paths. All configuration files matching this list (Directories are resolved recursively) will be merged together and returned to matching agents. |
+| `attributes` | `{}` | A map of attributes. This map is used to determine whether an agent will match this agent mapping, thus, get its configuration. |
+| `sourceBranch` | `WORKSPACE` | Defines which branch is used as source for the configuration files. Supported values are: `WORKSPACE`, `LIVE` |
+
 
 The configuration server is shipped with a default agent mapping.
-This default agent mapping maps each agent to each configuration file.
+This default agent mapping maps each agent to each configuration file of the `workspace` branch.
 
 ```YAML
 - name: "Default Mapping"
   sources:
   - "/"
   attributes:
     service: ".*"
+  sourceBranch: "WORKSPACE"
 ```
 
 ## Example Agent Mappings
 
 ### Example 1
 
-The following agent mapping will deliver all configuration files located in the directory `/common` and `/europe/west` to all agents whose `region` attributes is equal to `eu-west`.
+The following agent mapping will deliver all promoted configuration files located in the directory `/common` and `/europe/west` to all agents whose `region` attributes is equal to `eu-west`.
 
 ```YAML
 - name: "Example Mapping 1"
@@ -41,11 +45,12 @@ The following agent mapping will deliver all configuration files located in the
   attributes:
     service: ".*"
     region: "eu-west"
+  sourceBranch: "LIVE"
 ```
 
 ### Example 2
 
-The following agent mapping will deliver all configuration files located in the directory `/common` and the specific file `/special/customer-service.yml` to all agents whose `service` attributes is equal to `customer-service`.
+The following agent mapping will deliver all configuration files located in the directory `/common` and the specific file `/special/customer-service.yml` of the `workspace` branch to all agents whose `service` attributes is equal to `customer-service`.
 
 ```YAML
 - name: "Example Mapping 2"
@@ -54,4 +59,5 @@ The following agent mapping will deliver all configuration files located in the
   - "/special/customer-service.yml"
   attributes:
     service: "customer-service"
+  sourceBranch: "WORKSPACE"
 ```

inspectit-ocelot-documentation/docs/config-server/cs-configuration.md

@@ -8,7 +8,9 @@ There are several ways to customize the server settings according to your needs.
 
 In the following section, we use the approach of using an `application.yml` file to specify the customized settings which is located in the same directory as the server's JAR file.
 
-> Please note that the inspectIT Ocelot configuration server uses the prefix `inspectit-config-server` for its specific inspectIT properties. Up to version 0.4, the prefix `inspectit` was used which has been changed to avoid confusion between the configurations of the different components.
+:::note
+Please note that the inspectIT Ocelot configuration server uses the prefix `inspectit-config-server` for its specific inspectIT properties. Up to version 0.4, the prefix `inspectit` was used which has been changed to avoid confusion between the configurations of the different components.
+:::
 
 ## Configure the HTTP(S) Port
 
@@ -34,7 +36,9 @@ The following properties can be used to configure SSL.
 | `server.ssl.key-password` | Password used to access the key in the key store | 
 | `server.ssl.key-alias` | Alias that identifies the key in the key store (in case the store contains multiple certificates) |
 
-> Currently, it is not possible to use HTTP and HTTPS at the same time. If HTTPS is configured, the server's endpoint will not accept HTTP requests.
+:::note
+Currently, it is not possible to use HTTP and HTTPS at the same time. If HTTPS is configured, the server's endpoint will not accept HTTP requests.
+:::
 
 The following code causes the server to use the certificate which is mapped to the alias `ocelot` and contained in the key-store `/opt/inspectit/ocelot.p12`.
 

inspectit-ocelot-documentation/docs/config-server/managing-configurations.md

@@ -0,0 +1,38 @@
+---
+id: managing-configurations
+title: Managing Configuration Files
+---
+
+The configuration server internally uses Git to manage its working directory. This allows a versioning of configurations, so that it is possible to track when and how a configuration was created, changed or deleted. Additionally, it allows unwanted changes to be reverted and configuration files to be restored that would otherwise be lost.
+
+Furthermore, a staging of configurations is possible. By default, the configuration server has two branches (`WORKSPACE` and `LIVE`) which contain the configuration files and which can be used as the basis for the configuration to be delivered. All changes made by users to the configuration files affect the `WORKSPACE` branch. The `LIVE` branch cannot be changed directly by users. A change to the `LIVE` branch is only possible by transferring an already done change to the `WORKSPACE` branch to the `LIVE` branch - in this case called "promotion".
+
+:::tip
+It is possible for agents to obtain the configurations exclusively from the `LIVE` branch. As a result, users can now edit configuration files without having to deliver these - possibly incomplete changes - directly, thus preventing warnings due to invalid configurations.
+:::
+
+In order to deliver specific configurations to agents, so-called "agent mappings" can be used. These can be used to define precisely which files and from which branch an agent should receive.
+
+![Configuration Server Workspace Architecture](assets/configuration-server-branches.png)
+
+## Promoting Configuration Files
+
+Changes to configuration files by users only affect the `WORKSPACE` branch. If a user wants to make a change to a configuration file, but the version of the `LIVE` branch is delivered to the agent, the user must do the following:
+
+* First, the user must perform the change, which allows the change to be tracked on the workspace branch.
+* Afterwards the change must be approved and promoted by a user who has promotion rights. Only through promotion the changes to a file will be transferred to the `LIVE` branch.
+
+:::note
+It is important to note that only whole files and not individual changes can be promoted. This means that if two different users have edited a single file it is only possible to promote the whole file and not just the changes of a specific user.
+:::
+
+In the following screenshot, the configuration server's promotion user interface is shown. It can be used to review, approve and promote configurations. Only users who have promotion rights can approve and promote configuration files.
+
+![Configuration Server's promotion UI](assets/configuration-server-promotion-ui.png)
+
+1. The promotion UI can be access via the navigation sidebar.
+2. The UI shows a list of all files which have been changed on the `WORKSPACE` branch, thus, differ from the `LIVE` branch. The icons show whether a file has been newly created, edited or deleted. Approved files that will be promoted to the `LIVE` branch are highlighted in green with a check mark.
+3. The current version of the file on the `LIVE` branch.
+4. The current version of the file on the `WORKSPACE` branch.
+5. Button to promote the approved files.
+6. The selected file can be approved with this button.

inspectit-ocelot-documentation/docs/config-server/overview.md

@@ -13,4 +13,10 @@ This has the advantage that the manual administration of the configuration files
 
 The server provides a web interface to manage all relevant settings and configurations. It can be accessed via `http://<server-address>:<port>/ui/`. By default, the configuration server is listening to port `8090`.
 
-In addition, a Swagger UI is provided which contains a list including documentation of the server's REST API. By default, the Swagger UI can be accessed via `http://<server-address>:<port>/swagger-ui.html`.
+In addition, a Swagger UI is provided which contains a list including documentation of the server's REST API. By default, the Swagger UI can be accessed via `http://<server-address>:<port>/swagger-ui.html`.
+
+## Management of Configuration Files
+
+Since version 1.4, the configuration server uses Git and a local repository to manage the working directory. If a working directory already exists that was created by a configuration server in version 1.3 or lower, it is automatically migrated to a working directory managed using a local Git repository. No manual adjustments are necessary.
+
+Please see [Managing Configuration Files](config-server/managing-configurations.md) for more information on managing of the configuration files.

inspectit-ocelot-documentation/website/sidebars.json

@@ -43,6 +43,7 @@
     "Configuration Server": [
       "config-server/overview",
       "config-server/cs-configuration",
+	  "config-server/managing-configurations",
       "config-server/agent-mappings",
       "config-server/user-authentication",
       "config-server/log-config"