# 使用原生服务有哪些规则约束
#### 使用说明
在AstroZero上开发整个Native Service时，需要配置Chart、API等，本章节主要介绍开发过程中，需要遵循的规范和约束，供您在开发时进行参考。
#### 术语定义
**规则**：开发时，强制必须遵守的约定。
**建议**：开发时，必须加以考虑的约定。
#### 镜像开发中的规则约束
用户可自行开发镜像，并上传到CCE华为云容器中或使用第三方镜像仓库的镜像。在进行镜像开发时，需要遵循如下的规则约束：
- 规则1：容器镜像必须使用，1.11.2或以上版本的Docker客户端进行制作。 如何制作Docker镜像，请参考[如何编写高效的Dockerfile](https://support.huaweicloud.com/bestpractice-swr/swr_bestpractice_0002.html)。
  
- 规则2：Native服务向AstroZero平台开放的接口，必须是"application/json"格式的restful接口。 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001932888784.png "点击放大")
  开放给AstroZero应用调用的Native服务接口，请求消息和响应消息的"Content-Type"都必须是"application/json"。
  ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001960287309.png "点击放大")
  
- 规则3：Native服务开放的接口应使用HTTP消息头进行认证，不要依赖于Cookie。 AstroZero会丢弃Native服务返回的Cookie信息，因此，Native不能使用Cookie来维持状态。 Native服务示例代码如下：
  ```
  LOG.info("Authentication begin.");
  String auth = request.getHeader("Authorization");
  // next: verify auth
  ```
  
- 建议：服务的日志建议输出到一个独立的目录，且日志文件命名以".log"、".trace"或".out"后缀结尾，方便后续使用华为云的应用运维管理（简称AOM），采集日志文件，并将日志展示在AOM的界面上。
 
#### 配置Chart时的规则约束
- 规则1：在配置Chart时，Chart中应尽量避免包含密码等敏感信息。若需要配置敏感信息，用户需要自行对敏感信息进行加密，且Chart中不能包含解密敏感信息需要的密钥。
- 规则2：将Chart中的易变参数定义为全局变量，可避免因为参数变更时，修改并重新生成Chart包。
  ![](https://support.huaweicloud.com/usermanual-astrozero/public_sys-resources/note_3.0-zh-cn.png)
  全局变量将用于生成Chart包中的"values.yaml"文件。在华为云CCE上部署Chart时，"values.yaml"文件的内容可以通过界面进行修改。因此，应将和环境相关的信息或其他易变参数定义为全局参数，例如镜像地址、pod实例数等。
  
- 规则3： 必须要为Ingress资源配置注解，注解中键为"nginx.ingress.kubernetes.io/ssl-redirect"，值为"false"。 华为云CCE的Kubernetes集群默认部署Nginx控制器，需要在Ingress上添加注解。如何添加注解，请参考[Kubernetes资料](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/)。
  AstroZero平台在调用Native服务的接口时，无法处理重定向的响应，必须给Ingress添加[表1]中的注解。
   表1注解1 
  | 注解中键                                     | 注解中值  |
  |:---|:---|
  | nginx.ingress.kubernetes.io/ssl-redirect | false |
     
  Nginx控制器默认后端service使用http协议，如果后端service使用的是https协议，请添加[表2]中的注解。
   表2注解2 
  | 注解中键                                         | 注解中值  |
  |:---|:---|
  | nginx.ingress.kubernetes.io/backend-protocol | HTTPS |
  | nginx.ingress.kubernetes.io/secure-backends  | true  |
     
  
- 建议1：保持Chart简洁，建议一个Chart中工作负载不超过3个。 保持Chart简洁，可以降低部署、升级失败的概率，在升级时能更有效地控制升级的范围。
  
- 建议2 ：同一个Chart中，为所有图元的名称定义相同的前缀。 例如，某Chart中所有图元以"template-"为前缀，无状态负载的名称可以命名为"template-deployment"，ConfigMap的名称可以命名为"template-dbconfig"等。使用相同的前缀，可以使用户更方便识别Kubernetes资源的归属，同时降低命名冲突的可能性。
  
- 建议3：当全局变量的值是多行文本时，文本中出现的空行应不含任何空格字符。 全局变量将用于生成Chart包中的"values.yaml"文件，在yaml文件中，通过缩进表达层次关系，而空行中的空格字符会影响yaml文档的缩进排版。例如，当全局变量名为"dbConfig"，变量值为：
  ```
  jdbc.url: jdbc:mysql://127.0.0.1:3306/testdb
  jdbc.username: admin
  jdbc.password: {XXXXXXXX}
  jdbc.driver-class-name: org.mariadb.jdbc.Driver
  ```
  生成的values.yaml内容为：
  ```
  dbConfig: |-
    jdbc.url: jdbc:mysql://127.0.0.1:3306/testdb
    jdbc.username: admin
    jdbc.password: {XXXXXXXX}
    jdbc.driver-class-name: org.mariadb.jdbc.Driver
  ```
  当全局变量名为"dbConfig"，变量值为（第4行中包含一个空格字符）。
  ```
  jdbc.url: jdbc:mysql://127.0.0.1:3306/testdb
  jdbc.username: admin
  jdbc.password: {XXXXXXXX} 
  jdbc.driver-class-name: org.mariadb.jdbc.Driver
  ```
  生成的values.yaml内容为：
  ```
  dbConfig: "jdbc.url: jdbc:mysql://127.0.0.1:3306/testdb\njdbc.username: admin\njdbc.password:\
    \ changeit\n \njdbc.driver-class-name: org.mariadb.jdbc.Driver"
  ```
  通过流水线部署Chart时，第一种格式的"values.yaml"文件，更容易通过脚本进行修改。
  
 
#### 配置API时的规则约束
规则：在"API设计"页签，单击"开始设计API"，创建API时，API的命名空间应选择"局部命名空间"。
在创建API时，"命名空间"支持选择"局部命名空间"和"全局命名空间"。使用"局部命名空间"，可保证API的名称不会和其他Native服务的API名称出现冲突。而"全局命名空间"，是为了版本向前兼容而保留的。在AstroZero 1.2.10及之前的版本中，API无命名空间的概念，相当于API定义在全局名称空间中，因此，不同Native服务的API命名出现冲突的可能性比较大。