Project: Apollo (Provisioning / Automation & Configuration)
File: apollo-user-guide.md

Common application Common applications refer to programs that run independently, such as Web applications Programs with main functions Public components Public components refer to distributed libraries, client programs that do not run on their own, such as Java jar packages .Net dll file To use Apollo, you need to create a project as the first step. Open apollo-portal homepage Click "Create a project". Enter the project information Department: Select the department where the application is located Application AppId: the unique id used to identify the application, the format is string, it needs to correspond to the app.id configured in the client app.properties Application Name: the name of the application, used only for interface display Application Manager: The person who selects it will be the administrator of the project by default, with permissions to manage project permissions, create clusters, create Namespace, etc. Click Submit After successful creation, it will automatically jump to the project home page The project administrator has the following privileges. Can manage the permissions assignment of the project Create clusters Can create Namespace If you need someone else to be the project administrator, you can follow the steps below. Click "Manage Projects" on the left side of the page Search for the member you want to add and click Add * Configuration permissions are divided into edit and publish. Edit permission allows users to create, modify, and delete configurations on the Apollo interface Configuration modification only changes on Apollo interface and does not affect the actual configuration used by the application Publish permissions allow users to publish and roll back configurations in the Apollo interface Configurations are only actually used by the application after they have been published and rolled back Apollo notifies the application in real time after the user has performed a publish or rollback action and the latest configuration takes effect After the project is created, there are no editing and publishing permissions assigned to the configuration by default, and the project administrator needs to authorize it. Click the authorization button of the namespace application Assign the modify permission Assign publish privileges To edit the configuration, you need to have the edit permission of this Namespace. If you find that there is no Add Configuration button, you can find the project administrator to authorize it. Click Add Configuration Enter a configuration item Click Submit Apollo not only supports table mode to add and modify configurations one by one, but also provides text mode to add and modify them in bulk. This is especially useful for migrating from an existing properties file. Switch to text editing mode Click the Modify Configuration button on the right Enter the configuration entries and click on Submit Changes The configuration will only really be used by the application after it has been published, so after editing the configuration, you need to publish it. If you find that there is no publish button, you can ask the project administrator to authorize

Click the "Publish button" Fill in the information about the publish and click Publish After the configuration is successfully published, the application can read the configuration through the Apollo client. Apollo currently provides a Java client. For more information, please click . If the application uses other languages, you can also get the configuration by directly accessing the Http interface, for details, please refer to If you find any problem with the released configuration, you can roll back the configuration read by the client to the previous release by clicking the "Rollback" button. The rollback mechanism here is similar to the release system, where the rollback operation in the release system rolls back the installed packages deployed to the machine to the previous deployed version, but the code in the code repository is not rolled back, so that development can re-release the code after fixing it. The rollback in Apollo is a similar mechanism. Clicking rollback rolls back the configuration published to the client to the previous published version, which means that the configuration read by the client will be restored to the previous version, but the configuration in the edited state on the page will not be rolled back, so that the developer can re-publish after fixing the configuration. Public components are those client code that are published for use by other applications, such as the CAT client, Hermes Producer client, etc. Although such components are developed and maintained by other teams, the runtime is within the actual business application, so they can essentially be considered part of the application. Usually, the configuration used by these components is maintained by the original development team, but since the runtime and environment of the actual application vary, we also allow the application to override some of the configuration of the public components when they are actually used. The access steps for public components are almost identical to those for normal applications, the only difference being that public components need to create their own unique Namespace. So, first perform the following steps in the common application access document, and then follow the steps later in this section. If you find no Add Namespace button, you can find the project administrator to authorize it. Click Add Namespace on the left side of the page Click "Create New Namespace". Enter the namespace name for the public component. Note that the namespace name is globally unique. Apollo will add the department name at the top by default After clicking Submit, the page will automatically jump to the Associated Namespace page First, select all the environments and clusters that need to have this Namespace, it is generally recommended to select all of them. Second, select the namespace you just created. Finally, click Submit Finally, click Submit * After successful linking, the page will automatically jump to the Namespace permission management page Assign the permission to modify the namespace Assign permission to publish Click "Back" to return to the project page To edit the configuration, you need to have the edit permission of this

If you find that there is no Add Configuration button, you can find the project administrator to authorize it. Click Add Configuration Enter the configuration items Click Submit This part is the same as normal application, please refer to for the detailed steps. The configuration will only really be used by the application after it has been published, so after editing the configuration, it needs to be published. If you find that there is no publish button, you can ask the project administrator to authorize it. Click the "Publish button" Fill in the information about publishing and click Publish Once the configuration is successfully published, the application can read the configuration through the Apollo client. Apollo currently provides a Java client. For more information, click . If the application uses other languages, you can also get the configuration by directly accessing the Http interface, for details, please refer to For reading the configuration of public components, you can refer to the "Getting the Configuration of Public Namespace" section in the above document. As mentioned earlier, the configuration of public components is usually maintained by the original development team, but since the actual application runtime and environment vary, we also allow applications to override some of the configuration of public components when they are actually used. Here is how the application can override the configuration of the public component. For simplicity, assume that the apollo-portal application uses the hermes producer client and wants to adjust the batch send size of hermes. Go to the home page of the application project that uses the public component and click the Add Namespace button on the left So, in this example, we need to go to the home page of apollo-portal. (Adding Namespace requires project administrator privileges, if you find no Add Namespace button, you can find the project administrator to authorize it) Find the namespace of the hermes producer and select which environments and clusters to associate with it After successful linking, the page will automatically jump to the Namespace permission management page Assign modify permission Assign permission to publish Click "Back" to return to the project page Click Add Configuration Enter the configuration items to be overridden Click Submit The configuration will only really be used by the application after it is published, so after editing the configuration, it needs to be published. To publish the configuration, you need to have the publish permission of this Namespace, if you find that there is no publish button, you can ask the project administrator to authorize it. Click the "Publish button" Fill in the information about the publication and click Publish After the configuration is successfully published, the value of sender.batchSize read by the hermes producer client when running inside the apollo-portal application is 1000. In some special cases, the application has the need to do different configurations for different clusters, such as the application deployed in server room A connects to a different es server address than the application deployed in server room B connects to a different es server

In this case, it can be solved by creating different clusters in Apollo. If you find that there is no Add Cluster button, you can ask the project administrator for authorization. Click the "Add Cluster" button on the left side of the page Enter the cluster name, select the environment and submit Switch to the corresponding cluster, modify the configuration and release it With the above configuration, the application deployed in the SHAJQ server room will read the configuration under the SHAJQ cluster If the application is also deployed in other server rooms, then with the above configuration, the configuration under the default cluster will be read. In some cases, although the application itself is not a public component, it still needs to share the same configuration among multiple AppId, such as different projects of the same product: XX-Web, XX-Service, XX-Job and so on. In this case, if you want to implement multiple AppId to use the same configuration, the basic concept is the same as the configuration of public components. Specifically, we create a namespace under one of the AppId, write the public configuration information, and then read the configuration of the namespace in each project. If an AppId needs to override the public configuration information, then associate a public namespace under that AppId and write the configuration that needs to be overridden. The specific steps can be referred to . With the grayscale release function, you can achieve. For some configurations that have a relatively large impact on the program, you can first take effect in one or more instances, and observe no problem for a period of time before releasing the configuration in full. For some configuration parameters that need to be tuned, A/B testing can be achieved through the grayscale release function. You can apply different configurations on different machines and keep tuning and evaluating for a period of time to find out the better configuration before releasing the configuration in full. The following is a practical example to describe how to use the grayscale release function. The 100004458 (apollo-demo) project has two clients. 10.32.21.19 10.32.21.22 Grayscale targets: Currently there is a configuration timeout=2000, we want to grayscale release timeout=3000 for 10.32.21.22 and still timeout=2000 for 10.32.21.19. First click the `create grayscale` button in the top right corner of the application namespace. After clicking OK, the grayscale version is created successfully and the page will automatically switch to the `grayscale version` tab. Click on the `Configure main version`, the `Gray this configuration` button on the far right of the timeout configuration Fill in the popup box with the value to be grayed out: 3000 and click Submit. After the grayscale configuration, confirm the grayscale configuration and the major version configuration. Click on the `Grayscale Publish` button. Confirm the grayscale configuration to be released by comparing the value of the major version and the published value of the grayscale

Switch to the `Gray Rule` Tab and click the `Add Rule` button In the popup box `Grayed IP` dropdown box will show the list of machines currently using the configuration by default, select the IP we want to gray. In addition to the IP dimension, from version 2.0.0 onwards there is also support for identifying the list of instances in grayscale by label, which is suitable for scenarios where the IP is not fixed such as `Kubernetes`. Manually enter the label you want to set, and click the Add button when you're done. After the above rules are configured, the grayed configuration will take effect for instances with AppId `100004458`, IP `10.32.21.22` or `Label` marked as `myLabel` or `appLabel`. For more information on how to label `Label`, you can refer to the configuration instructions in . If the required IP is not found in the drop-down box, it means that the machine has not yet taken the configuration from Apollo, you can enter it by clicking Enter IP manually, and click the Add button after entering the IP. Note: For the grayscale rule of public Namespace, you need to specify the appId to be grayscale first, then select the IP and Label. The configuration rules are in effect, but the grayscale configuration has not been published yet. Switch to the `Configuration` Tab. Check the grayscale configuration section again, and if there are no problems, click `Grayscale Publish`. In the popup box, you can see that the value of the master version is 2000 and the value of the gray version to be released is 3000. fill in the other information and click on release. After the release, switch to the `gray instance list` Tab and you can see that 10.32.21.22 has used the values of the gray release. Switch to the `instance list` of the `master release` and you will see that only 10.32.21.19 of the master configuration is in use. You can continue with configuration changes or rule changes later. Configuration changes need to click Gray Release before they take effect, and rule changes take effect in real time after the rule is clicked to complete. If the grayscale configuration is tested down ideally and meets expectations, then you can operate `full release`. The effect of a full release is that The grayscale configuration will be merged back to the main version, in this case, the timeout of the main version will be updated to 3000 The configuration of the main version will be automatically published once In the full release page, you can choose whether to keep the current grayscale version, the default is not to keep. I chose not to keep the grayscale version, so the effect after the release is that the configuration of the master version is updated and the grayscale version is deleted. Clicking on the instance list of the main version, you can see that 10.32.21.22 and 10.32.21.19 both use the latest configuration of the main version. If the grayscale version is not ideal or not needed anymore, you can click `Drop

Click the `release history` button of the main release to see the release history of the current namespace's main release as well as the grayscale version. Starting from version 1.1.0, apollo-portal has added support for view permissions, which allows you to configure an environment to allow only project members to view the private Namespace configuration. The project members here are : The project's administrator Have the permission to modify or publish the private Namespace in that environment The configuration is very simple. After logging in with your super administrator account, go to the `Administrator Tools - System Parameters` page and add or modify the `configView.memberOnly.envs` configuration item. Apollo has added an access key mechanism since version 1.6.0, so that only authenticated clients can access sensitive configurations. If the application has access keys enabled, the client needs to configure the keys, otherwise the configuration cannot be accessed. The project administrator opens the Manage Keys page Generate an access key for each environment of the project, note that it is disabled by default, and it is recommended to turn it on after the clients are all configured Client-side . As a basic service, the configuration center stores very important configuration information of the company, so security factors need to be focused on, some considerations are listed below for your reference, and you are also welcome to share your own practice cases. It is recommended to access the company's unified authentication system, such as SSO, LDAP, etc. The access method can be found in If you use Spring Security simple authentication provided by Apollo, you must remember to change the password of super administrator apollo Apollo supports fine-grained permissions control, so please make sure to control the permissions according to the actual situation: 1. Apollo allows all logged-in users to create projects by default. If you only allow some users to create projects, you can turn on Configuration editing and publishing privileges support configuration by environment, for example, the development environment developers can complete the process of configuration editing and publishing by themselves, but the production environment publishing privileges to the test or operation and maintenance personnel It is recommended to turn on at the same time for production environment, so as to control that only one person can modify a configuration release and another person can release it. This ensures that configuration changes are adequately checked. You can specify that only project members of an environment are allowed to view the configuration of a private Namespace, thus avoiding sensitive configuration leaks, such as production environments In addition to user permissions, system access also needs to be considered in terms of. `apollo-configservice` and `apollo-adminservice` are designed based on the intranet trusted network, so for security reasons, `apollo-configservice` and `apollo-adminservice` are prohibited from being exposed directly to the public network For sensitive configurations, consider enabling so that only authenticated clients can access sensitive configurations version 1.7.1 and above can consider enabling for `apollo-adminservice`, so that only `apollo-portal` can access the corresponding interface to enhance security version 2.1.0 and above can consider enabling for `eureka`, so that only controlled `apollo-configservice` and `apollo-adminservice` can be registered to `eureka` to enhance security