diff --git a/inspectit-ocelot-documentation/docs/assets/agent_mappings_source_branch.png b/inspectit-ocelot-documentation/docs/assets/agent_mappings_source_branch.png new file mode 100644 index 0000000000..2d9892611a Binary files /dev/null and b/inspectit-ocelot-documentation/docs/assets/agent_mappings_source_branch.png differ diff --git a/inspectit-ocelot-documentation/docs/config-server/agent-mappings.md b/inspectit-ocelot-documentation/docs/config-server/agent-mappings.md index 31ebf3a477..994a33804d 100644 --- a/inspectit-ocelot-documentation/docs/config-server/agent-mappings.md +++ b/inspectit-ocelot-documentation/docs/config-server/agent-mappings.md @@ -3,11 +3,14 @@ id: agent-mappings title: Agent Mappings --- -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. +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. +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: @@ -31,6 +34,27 @@ This default agent mapping maps each agent to each configuration file of the `wo sourceBranch: "WORKSPACE" ``` +## Git Staging + +:::tip +You can find more detailed information about file staging and promotion [here](config-server/files-staging.md). +::: + +Since the version `2.5.7` the configuration for the agent mappings itself will also be included into the git staging. For all agent mappings +the configuration is stored in one file. After one or several agent mappings have been edited, the changes will also +appear on the promotion page. The promotion of the agent mappings configuration works directly like the promotion of agent configuration files. + +Additionally, it is possible to select a source branch (`WORKSPACE` or `LIVE`) for the agent mappings configuration itself. +This will determine, whether changes in the agent mappings should be applied directly or only after the promotion of the +agent mappings configuration. + +:::important +The source branch for the agent mappings configuration will **not affect** the defined `sourceBranch` in each **individual agent mapping**! +The `sourceBranch` property of an individual agent mapping determines, which branch should be used for the agent configuration files. +::: + +![Different Source Branches on Agent Mappings Page](assets/agent_mappings_source_branch.png) + ## Example Agent Mappings ### Example 1 @@ -60,4 +84,5 @@ The following agent mapping will deliver all configuration files located in the attributes: service: "customer-service" sourceBranch: "WORKSPACE" -``` \ No newline at end of file +``` + diff --git a/inspectit-ocelot-documentation/docs/config-server/configuration-staging.md b/inspectit-ocelot-documentation/docs/config-server/files-staging.md similarity index 95% rename from inspectit-ocelot-documentation/docs/config-server/configuration-staging.md rename to inspectit-ocelot-documentation/docs/config-server/files-staging.md index a71c800323..4458f5c694 100644 --- a/inspectit-ocelot-documentation/docs/config-server/configuration-staging.md +++ b/inspectit-ocelot-documentation/docs/config-server/files-staging.md @@ -1,16 +1,16 @@ --- -id: configuration-files-staging -title: Configuration Files Staging Using Remote Git -sidebar_label: Configuration Files Staging +id: files-staging +title: File Staging Using Remote Git +sidebar_label: File Staging --- :::tip -It is recommended to first familiarize yourself with [how the configuration server manages configuration](config-server/managing-configurations.md) files before reading this chapter. +It is recommended to first familiarize yourself with [how the configuration server manages files](config-server/managing-files.md) before reading this chapter. ::: Since version `1.11.0` the Configuration Server offers the possibility that external Git repositories can be connected. This allows configuration files to be obtained from an external Git repository and also transferred to it. -This allows us to secure configuration files (e.g. for creating backups), initialize configuration servers with a specific set of configuration files or chain several configuration servers together. +This allows us to secure configuration files and agent mappings (e.g. for creating backups), initialize configuration servers with a specific set of configuration files or chain several configuration servers together. The latter can be used, for example, to cover more complex scenarios, such as synchronizing configuration files across multiple system stages. :::important @@ -170,4 +170,4 @@ All configuration server properties mentioned below refer to being set under the | `authentication-type` | `NONE` | The type of authentication to use. Possible values: `NONE`, `PASSWORD`, `PPK`. | | `username` | `null` | The username for accessing the remote repository. Only used in case of `PASSWORD` authentication. | | `password` | `null` | The password for accessing the remote repository. Only used in case of `PASSWORD` authentication. | -| `private-key-file` | `null` | Additional private key to use for SSH authentication. The server will automatically load the known hosts and private keys from the default locations (identity, id_rsa and id_dsa) in the user’s `.ssh` directory. Only used in case of `PPK` authentication. | \ No newline at end of file +| `private-key-file` | `null` | Additional private key to use for SSH authentication. The server will automatically load the known hosts and private keys from the default locations (identity, id_rsa and id_dsa) in the user’s `.ssh` directory. Only used in case of `PPK` authentication. | diff --git a/inspectit-ocelot-documentation/docs/config-server/managing-configurations.md b/inspectit-ocelot-documentation/docs/config-server/managing-files.md similarity index 64% rename from inspectit-ocelot-documentation/docs/config-server/managing-configurations.md rename to inspectit-ocelot-documentation/docs/config-server/managing-files.md index 98c3797723..6ae229b8f9 100644 --- a/inspectit-ocelot-documentation/docs/config-server/managing-configurations.md +++ b/inspectit-ocelot-documentation/docs/config-server/managing-files.md @@ -1,23 +1,38 @@ --- -id: managing-configurations -title: Managing Configuration Files +id: managing-files +title: Managing Files +sidebar_label: Managing 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. +The configuration server internally uses Git to manage its working directory. +This allows a versioning of configurations as well as the agent mappings, so that it is possible to track when and how a file 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". +Furthermore, a staging of configurations and agent mappings is possible. By default, the configuration server has two +branches (`WORKSPACE` and `LIVE`) which can be used as the basis for the configurations to be delivered. +All changes made by users to the configuration files and the agent mappings 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. +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. + +You can achieve this by setting the source branch for a specific agent mapping to `LIVE`. ::: -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. +**Agent Mappings** can be used, in order to deliver specific configurations to agents. +They can also 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 +## Promoting 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: +Changes to configuration files or agent mappings 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. @@ -40,8 +55,8 @@ In the following screenshot, the configuration server's promotion user interface ## Four-Eyes Promoting Restriction By default, any user with promotion rights can promote any changes. -In some setups it can be beneficial to enforce peer-reviews before promoting configuration changes. -The configuration server offers a mechanism to enforce a four eyes principle for configuration changes which can be enabled using the following setting: +In some setups it can be beneficial to enforce peer-reviews before promoting changes. +The configuration server offers a mechanism to enforce a four eyes principle for changes which can be enabled using the following setting: ```YAML inspectit-config-server: @@ -49,7 +64,7 @@ inspectit-config-server: four-eyes-promotion: true ``` -When this setting is enabled, users with promotion rights will no longer be able to promote their own configuration changes. +When this setting is enabled, users with promotion rights will no longer be able to promote their own changes. :::note This restriction is only applied to non-admin users! Users with admin rights will still be able to promote their own changes. @@ -70,7 +85,7 @@ inspectit-config-server: ## External Changes -While it is not recommended, it is possible to directly change the configuration files in the filesystem instead of via the +While it is not recommended, it is possible to directly change the files in the filesystem instead of via the configuration server's UI or REST-API. In order for your changes in the file-system to become active, you need to let the configuration server know about the external changes. @@ -79,4 +94,4 @@ A request to this endpoint causes all external changes to be committed to the `W Alternatively, you can also manually commit to the `WORKSPACE` branch in the working directory of the configuration server. However, you need to make sure that the server is either shut down or you need to have the guarantee that no other users are currently editing files via the UI, -otherwise your repository might get corrupted. \ No newline at end of file +otherwise your repository might get corrupted. diff --git a/inspectit-ocelot-documentation/website/sidebars.json b/inspectit-ocelot-documentation/website/sidebars.json index c3b203f988..53bfd828d1 100644 --- a/inspectit-ocelot-documentation/website/sidebars.json +++ b/inspectit-ocelot-documentation/website/sidebars.json @@ -49,8 +49,8 @@ "Configuration Server": [ "config-server/overview", "config-server/cs-configuration", - "config-server/managing-configurations", - "config-server/configuration-files-staging", + "config-server/managing-files", + "config-server/files-staging", "config-server/agent-mappings", "config-server/scope-wizard", "config-server/class-browser",