使用原生服务有哪些规则约束

使用说明

在AstroZero上开发整个Native Service时，需要配置Chart、API等，本章节主要介绍开发过程中，需要遵循的规范和约束，供您在开发时进行参考。

术语定义

规则：开发时，强制必须遵守的约定。

建议：开发时，必须加以考虑的约定。

镜像开发中的规则约束

用户可自行开发镜像，并上传到CCE华为云容器中或使用第三方镜像仓库的镜像。在进行镜像开发时，需要遵循如下的规则约束：

• 规则1：容器镜像必须使用，1.11.2或以上版本的Docker客户端进行制作。

  如何制作Docker镜像，请参考如何编写高效的Dockerfile。

• 规则2：Native服务向AstroZero平台开放的接口，必须是“application/json”格式的restful接口。

  

  开放给AstroZero应用调用的Native服务接口，请求消息和响应消息的“Content-Type”都必须是“application/json”。

  

• 规则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包。
  

  全局变量将用于生成Chart包中的“values.yaml”文件。在华为云CCE上部署Chart时，“values.yaml”文件的内容可以通过界面进行修改。因此，应将和环境相关的信息或其他易变参数定义为全局参数，例如镜像地址、pod实例数等。

• 规则3： 必须要为Ingress资源配置注解，注解中键为“nginx.ingress.kubernetes.io/ssl-redirect”，值为“false”。

  华为云CCE的Kubernetes集群默认部署Nginx控制器，需要在Ingress上添加注解。如何添加注解，请参考Kubernetes资料。

  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命名出现冲突的可能性比较大。