[Docs]OSPP Support Kubernetes ConfigMap for Apollo java, golang client (

#5233) ## What's the purpose of this PR docs for pr apolloconfig/apollo-java#79 discussion #5210 Co-authored-by: ZhangJian He <[email protected]>
apolloconfig · Oct 30, 2024 · 638c506 · 638c506
1 parent d886164
commit 638c506
Show file tree

Hide file tree

Showing 2 changed files with 183 additions and 0 deletions.
diff --git a/docs/en/client/java-sdk-user-guide.md b/docs/en/client/java-sdk-user-guide.md
@@ -171,6 +171,7 @@ The content of the file is stored in properties format, for example, if there ar
 request.timeout=2000
 batch=2000
 ```
+> Note: If deployed in a Kubernetes environment, you can also enable the configMap cache to further improve availability
 
 #### 1.2.3.1 Customizing the cache path
 
@@ -414,6 +415,96 @@ The configuration methods, in descending order of priority, are
 3. Via the `app.properties` configuration file
     * You can specify `apollo.override-system-properties=true` in `classpath:/META-INF/app.properties`
 
+#### 1.2.4.10 ConfigMap cache
+
+> For version 2.4.0 and above
+
+Starting from version 2.4.0, the availability of the client in the Kubernetes environment has been enhanced. After enabling the ConfigMap cache, the client will cache a copy of the configuration information fetched from the server in the ConfigMap. In the case of service unavailability, network issues, and loss of local cache files, the configuration can still be restored from the ConfigMap. Here are the relevant configurations:
+
+`apollo.cache.kubernetes.enable`：Whether to enable the ConfigMap cache mechanism, the default is false.
+
+`apollo.cache.kubernetes.namespace`：The namespace of the ConfigMap to be used (the namespace in Kubernetes), the default value is "default".
+
+The configuration information will be placed in the specified ConfigMap according to the following correspondence:
+
+namespace: Use the specified value, if not specified, the default is "default"
+
+configMapName: apollo-configcache-{appId}
+
+key:{cluster}___{namespace}
+
+value: The content is the JSON format string of the corresponding configuration information.
+
+> appId is the application's own appId, such as 100004458.
+> 
+> cluster is the cluster used by the application, which is usually default if not configured locally 
+> 
+> namespace Indicates the configuration namespace used by the application. If '_' appears in the namespace, it will be escaped to '__' when the key is concatenated.
+> Since this feature is extended, so the client-java dependency is set to optional. You need to import the matching version
+> Since read and write operations on the ConfigMap are required, the pod where the client is located must have the corresponding permissions. The specific configuration method can be referred to below.
+
+How to authorize a Pod's Service Account to have read and write permissions for ConfigMap:
+
+1. Create a Service Account: If there is no Service Account, you need to create one.
+   ```yaml
+   apiVersion: v1
+   kind: ServiceAccount
+   metadata:
+     name: my-service-account
+     namespace: default
+   ```
+2. Create a Role or ClusterRole: Define a Role or ClusterRole to grant read and write permissions for a specific ConfigMap. If the ConfigMap is used across multiple Namespaces, a ClusterRole should be used.
+   ```yaml
+   apiVersion: rbac.authorization.k8s.io/v1
+   kind: Role
+   metadata:
+     namespace: default
+     name: configmap-role
+   rules:
+   - apiGroups: [""]
+     resources: ["configmaps"]
+     verbs: ["get", "list", "watch", "create", "update", "delete"]
+   ```
+3. Bind the Service Account to the Role or ClusterRole: Use RoleBinding or ClusterRoleBinding to bind the Service Account to the Role or ClusterRole created above.
+   ```yaml
+   apiVersion: rbac.authorization.k8s.io/v1
+   kind: RoleBinding
+   metadata:
+     name: configmap-reader-binding
+     namespace: default
+   subjects:
+   - kind: ServiceAccount
+     name: my-service-account
+     namespace: default
+   roleRef:
+     kind: Role
+     name: configmap-role
+     apiGroup: rbac.authorization.k8s.io
+   ```
+4. Specify the Service Account in the Pod configuration: Ensure that the Pod's configuration uses the Service Account created above.
+   ```yaml
+   apiVersion: v1
+   kind: Pod
+   metadata:
+     name: my-pod
+     namespace: default
+   spec:
+     serviceAccountName: my-service-account
+     containers:
+       - name: my-container
+         image: my-image
+   ```
+5. Apply the configuration: Use the kubectl command-line tool to apply these configurations.
+   ```yaml
+   kubectl apply -f service-account.yaml
+   kubectl apply -f role.yaml
+   kubectl apply -f role-binding.yaml
+   kubectl apply -f pod.yaml
+   ```
+
+   These steps give the Service Account in the Pod read and write permissions for the specified ConfigMap.
+   If the ConfigMap is cross-namespace, use ClusterRole and ClusterRoleBinding instead of Role and RoleBinding, and ensure that these configurations are applied in all Namespaces that need to access the ConfigMap.
+
 # II. Maven Dependency
 
 Apollo's client jar package has been uploaded to the central repository, the application only needs to be introduced in the following way when it is actually used.

diff --git a/docs/zh/client/java-sdk-user-guide.md b/docs/zh/client/java-sdk-user-guide.md
@@ -163,6 +163,8 @@ request.timeout=2000
 batch=2000
 ```
 
+> 注：如果部署在Kubernetes环境中，您还可以启用configMap缓存来进一步提高可用性
+
 #### 1.2.3.1 自定义缓存路径
 
 1.0.0版本开始支持以下方式自定义缓存路径，按照优先级从高到低分别为：
@@ -398,6 +400,96 @@ apollo.label=YOUR-APOLLO-LABEL
 3. 通过`app.properties`配置文件
     * 可以在`classpath:/META-INF/app.properties`指定`apollo.override-system-properties=true`
 
+#### 1.2.4.10 ConfigMap缓存设置
+
+> 适用于2.4.0及以上版本
+
+在2.4.0版本开始，客户端在Kubernetes环境下的可用性得到了加强，开启configMap缓存后，客户端会将从服务端拉取到的配置信息在configMap中缓存一份，在服务不可用，或网络不通，且本地缓存文件丢失的情况下，依然能从configMap恢复配置。以下是相关配置
+
+`apollo.cache.kubernetes.enable`：是否开启configMap缓存机制，默认false
+
+`apollo.cache.kubernetes.namespace`：将使用的configMap所在的namespace（Kubernetes中的namespace），默认值为"default"
+
+配置信息会以下面的对应关系放置于指定的configmap中：
+
+namespace：使用指定的值，若未指定默认为"default"
+
+configMapName: apollo-configcache-{appId}
+
+key:{cluster}___{namespace}
+
+value:内容为对应的配置信息的json格式字符串
+
+
+> appId是应用自己的appId，如100004458    
+> cluster是应用使用的集群，一般在本地模式下没有做过配置的话，是default  
+> namespace就是应用使用的配置namespace。 如果namespace中出现‘_’ , 将会在拼接key时被转义为‘__’
+
+> 由于此功能为拓展功能，所以对于client-java的依赖设为了optional。需用户自行导入匹配的版本
+
+> 由于需要对configmap进行读写操作，所以客户端所在pod必须有相应读写权限，具体配置方法可参考下文
+
+如何授权一个Pod的Service Account具有对ConfigMap的读写权限：
+1. 创建Service Account: 如果还没有Service Account，你需要创建一个。
+   ```yaml
+   apiVersion: v1
+   kind: ServiceAccount
+   metadata:
+     name: my-service-account
+     namespace: default
+   ```
+2. 创建Role或ClusterRole: 定义一个Role或ClusterRole，授予对特定ConfigMap的读写权限。如果ConfigMap是跨多个Namespace使用的，应该使用ClusterRole。
+   ```yaml
+   apiVersion: rbac.authorization.k8s.io/v1
+   kind: Role
+   metadata:
+     namespace: default
+     name: configmap-role
+   rules:
+   - apiGroups: [""]
+     resources: ["configmaps"]
+     verbs: ["get", "list", "watch", "create", "update", "delete"]
+   ```
+3. 绑定Service Account到Role或ClusterRole: 使用RoleBinding或ClusterRoleBinding将Service Account绑定到上面创建的Role或ClusterRole。
+   ```yaml
+   apiVersion: rbac.authorization.k8s.io/v1
+   kind: RoleBinding
+   metadata:
+     name: configmap-reader-binding
+     namespace: default
+   subjects:
+   - kind: ServiceAccount
+     name: my-service-account
+     namespace: default
+   roleRef:
+     kind: Role
+     name: configmap-role
+     apiGroup: rbac.authorization.k8s.io
+   ```
+4. 在Pod配置中指定Service Account: 确保Pod的配置中使用了上面创建的Service Account。
+   ```yaml
+   apiVersion: v1
+   kind: Pod
+   metadata:
+     name: my-pod
+     namespace: default
+   spec:
+     serviceAccountName: my-service-account
+     containers:
+       - name: my-container
+         image: my-image
+   ```
+5. 应用配置: 使用kubectl命令行工具应用这些配置。
+   ```yaml
+   kubectl apply -f service-account.yaml
+   kubectl apply -f role.yaml
+   kubectl apply -f role-binding.yaml
+   kubectl apply -f pod.yaml
+   ```
+   这些步骤使Pod中的Service Account具有对指定ConfigMap的读写权限。
+
+   如果ConfigMap是跨Namespace的，使用ClusterRole和ClusterRoleBinding代替Role和RoleBinding，并确保在所有需要访问ConfigMap的Namespace中应用这些配置。
+
 # 二、Maven Dependency
 Apollo的客户端jar包已经上传到中央仓库，应用在实际使用时只需要按照如下方式引入即可。
 ```xml