这是本节的多页打印视图。点击此处打印.

快速入门

您可以根据文档完成北极星单机版本、集群版本的部署，以及如何使用微服务框架快速接入北极星进行体验

1: 安装服务端

1.1: 单机版安装
1.2: 集群版安装

2: 使用 SDK
3: 使用开发框架

4: 使用K8s和网格代理

4.1: 概念及原理
4.2: 使用k8s服务同步
4.3: Envoy网格接入

5: 使用网关

5.1: Nginx网关接入

1 - 安装服务端

1.1 - 单机版安装

安装说明

北极星单机版包含以下4个组件：

polaris-console：可视化控制台，提供服务治理管控页面
polaris-server：控制面，提供数据面组件及控制台所需的后台接口
prometheus：服务治理监控所需的指标汇聚统计组件
pushgateway：prometheus推送网关，支持数据面通过推送方式上报监控数据到prometheus

北极星单机版默认占用以下端口：

polaris-console：8080(http/tcp)
polaris-server：8090(http/tcp，注册中心端口)、8091(grpc/tcp，注册中心端口)、8093(grpc/tcp，配置中心端口)
prometheus：9090(tcp)
pushgateway：9091(tcp)

单机版组网

单机版北极星，所有的组件都安装在用户机器上，作为多个独立进程提供服务。

控制台

安装服务端

环境准备

北极星单机版支持以下4种运行环境：

Linux（64位）
Windows（64位）
Mac（64位）
容器化

单机版软件包

单机版的安装需要依赖单机版软件包，单机版软件包的命名格式为polaris-standalone-release_*.zip：

单机版

下载地址

执行所有安装之前，需要下载软件包，可以从以下2个地址下载单机版软件包，请选择最新的release版本：

Github下载：polaris standalone releases
Gitee下载：polaris standalone releases

如果有需要自定义单机版相关组件的监听端口，在解压对应的单机版本压缩包后，修改压缩包内的port.properties文件后，执行安装脚本即可

port.properties 文件概览

polaris_eureka_port=8761
polaris_open_api_port=8090
polaris_service_grpc_port=8091
polaris_config_grpc_port=8093
polaris_prometheus_sd_port=9000
polaris_xdsv3_port=15010
polaris_console_port=8080
prometheus_port=9090

Linux

下载Linux单机版软件包（polaris-standalone-release_$version.linux.$arch.zip），执行安装命令：

unzip polaris-standalone-release_$version.linux.$arch.zip

cd polaris-standalone-release_$version.linux.$arch

bash install.sh

Windows

注意事项：

依赖powershell 5.0及以上版本（Windows 10及以上版本默认安装）
需要以管理员身份运行安装脚本，执行powershell需要进行授权操作
安装脚本可能遭到系统安全软件的误杀，请在安全软件中执行信任操作

下载Windows单机版软件包（polaris-standalone-release_$version.windows.$arch.zip），执行安装命令：

执行解压：polaris-standalone-release_$version.windows.$arch.zip

进入目录：polaris-standalone-release_$version.windows.$arch

执行脚本：install.bat

Mac

注意事项：

请在【关于本机】设置中查看Mac机器的芯片类型（Intel/Apple）
Intel芯片请使用amd64的软件包，Apple芯片请使用arm64的软件包

下载Mac单机版软件包（polaris-standalone-release_$version.darwin.$arch.zip），执行安装命令：

unzip polaris-standalone-release_$version.darwin.$arch.zip

cd polaris-standalone-release_$version.darwin.$arch

bash install.sh

Docker 安装

执行一下命令即可

# Publish all exposed ports to random ports
docker run -d --publish-all polarismesh/polaris-server-standalone:latest

# Publish a container's port(s) to the host
docker run -d -p 15010:15010 -p 8080:8080 -p 8090:8090 -p 8091:8091 -p 8093:8093 -p 8761:8761 -p 9000:9000 -p 9090:9090  polarismesh/polaris-server-standalone:latest

docker 暴露的端口列表

EXPOSE 15010 8080 8090 8091 8093 8761 9000 9090

Kubernetes 安装

注意事项：

部署配置使用的是LoadBalancer类型的Service。如果您需要从k8s集群外访问北极星，且您的k8s集群不支持LoadBalancer，可以修改installk8s/02-polaris-server.yaml、installk8s/polaris-prometheus.yaml中Service的类型，调整为NodePort。如果您的集群支持Ingress，也可以通过Ingress从集群外访问。

下载k8s部署文件（polaris-standalone-release_$version.kubernetes.zip），将文件拷贝到配置了kubectl的机器上，执行安装命令：

unzip polaris-standalone-release_$version.kubernetes.zip

kubectl create -f polaris-standalone-release_$version.kubernetes/

部署配置介绍：

00-polaris-console-config.yaml：创建名为polaris-console-config的Configmap，polaris-console组件的配置文件。
01-polaris-server-config.yaml：创建名为polaris-server-config的Configmap，polaris-server组件的配置文件。
02-polaris-server.yaml：创建名为polaris的StatefulSet ，其中包含了两个容器，分别是polaris-server的容器和polaris-console的容器。也创建了名为polaris的Service，暴露了8080 、8090和8091端口，其中8080为控制台提供web服务，8090提供北极星控制面的http服务，8091提供北极星控制面的grpc服务。
03-prometheus.yaml：创建名为polaris-prometheus的Deployment，其中包含了两个容器，分别是prometheus和pushgateway。也创建了名为polaris-prometheus的Service，暴露了9090和9091端口，其中9090为prometheus请求端口，9091为pushgateway的请求端口。

安装验证

打开控制台

在浏览器里输入北极星控制台地址（127.0.0.1:8080），非容器化场景127.0.0.1可替换成安装北极星的机器host。

登录控制台的默认登录账户信息

用户：polaris
密码：polaris

容器化场景，您需要通过北极星创建的名为polaris的Service来访问控制台，根据您采用的网络方案，有以下几种情况：

如果您的k8s集群支持LoadBalancer的Service，并且您直接使用北极星提供的yaml部署，您需要使用polaris Service的EXTERNAL-IP:8080来访问。
如果您修改了北极星提供的yaml，使用的是NodePort的Service，您需要使用集群Node的host和polaris Service中8080对应的NodePort来访问。
如果您的k8s集群支持Ingress，您需要配置Ingress的backend的serviceName为polaris，并选择servicePort为8080。配置正常后，您可以通过您设置的域名访问。

控制台

新建服务

进入服务列表页面，点击【新建】按钮，确认是否可以新建服务。新建服务成功表示安装成功

新建服务

1.2 - 集群版安装

集群版组件说明

组件		类型	功能说明	必选/可选
polaris	最新stable版本	系统组件	服务治理控制面	必选
polaris-console	最新stable版本	系统组件	服务治理控制台	必选
polaris-limiter	最新stable版本	系统组件	分布式限流服务	可选
MySQL	`>= 5.7`	第三方依赖	服务数据存储	必选
Redis	`>=4.0`	第三方依赖	心跳状态数据缓存	必选
Prometheus	`>=2.28.0`	第三方依赖	可观测性	可选

最小生产组网规格

节点类型	节点数量	规格要求
polaris-console & polaris	2	CentOS 7.5，1C2G，存储10G
polaris-limiter	1	CentOS 7.5，1C2G，存储10G
MySQL	1	1C2G，存储10G
Redis	1	1C2G
Prometheus	1	1C1G

部署架构

核心组网

获取最新软件包

可以从以下2个地址下载北极星软件包，请选择最新的release版本：

Github下载：
Gitee下载：

下载软件包

安装第三方依赖

部署MySQL

北极星可以与应用程序共用一个数据库，如果有现成MySQL则可以跳过这一步。

安装开源版本MySQL的步骤可参考：MySQL安装

初始数据导入

解压源码包并执行导入：

第一次安装北极星

unzip polaris-$version.zip
cd polaris-$version
mysql -u $db_user -p $db_pwd -h $db_host < store/sqldb/scripts/polaris_server.sql

已有在运行的北极星，执行升级store/sqldb/scripts/delta中的升级脚本

unzip polaris-$version.zip
cd polaris-$version
mysql -u $db_user -p $db_pwd -h $db_host < store/sqldb/scripts/delta/v160-v170.sql

部署Redis

北极星可以与应用程序共用一个Redis，如果有现成Redis则可跳过这一步。

安装开源版本Redis的步骤可参考：Redis安装

安装后，需要设置Redis允许远程主机访问。可以修改redis.conf配置文件：

bind 0.0.0.0
protected-mode no

修改后重启Redis生效。

安装系统组件

部署在kubernetes

修改配置

下载软件包：下载polaris-standalone-release_$version.kubernetes.zip，解压后进入polaris-standalone-release_$version.kubernetes目录。
配置数据库参数：修改02-polaris-server-config.yaml里面的store配置，去掉boltdbStore相关配置，并放开defaultStore相关配置。

# 存储配置
store:
# 数据库存储插件
  name: defaultStore
  option:
    master:
      dbType: mysql
      dbName: polaris_server
      dbAddr: ##数据库地址，格式为ip:port##
      dbUser: ##数据库用户名##
      dbPwd: ##数据库密码##

开启自动注册：修改02-polaris-server-config.yaml里面的服务自注册配置，将enable_register改成true，并填入probe_address：

bootstrap:
  polaris_service:
    # 设置为true代表启用自动注册
    enable_register: true
    # 填入数据库地址，用于获取当前节点ip信息
    probe_address: ##数据库地址##

配置Redis参数：修改02-polaris-server-config.yaml里面的healthcheck配置，去掉heartbeatMemory相关配置，并放开heartbeatRedis相关配置。

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
	  #填入redis的IP以及端口
      kvAddr: ##REDIS_ADDR##
	  #填入redis的密码
      kvPasswd: ##REDIS_PWD##
      maxIdle: 200
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200

执行部署

kubectl create -f 00-polaris-namespace-config.yaml 
kubectl create -f 01-polaris-console-config.yaml  
kubectl create -f 02-polaris-server-config.yaml  
kubectl create -f 03-polaris-server.yaml
kubectl create -f 04-prometheus.yaml
kubectl create -f 05-polaris-limiter-config.yaml
kubectl create -f 06-polaris-limiter.yaml

部署在Linux虚拟机

安装polaris

下载软件包：下载polaris-server-release_$version.linux.$arch.zip，解压后进入polaris-server-release_$version.linux.$arch目录
配置数据库参数：修改polaris-server.yaml里面的store配置，去掉boltdbStore相关配置，并放开defaultStore相关配置。

# 存储配置
store:
# 数据库存储插件
  name: defaultStore
  option:
    master:
      dbType: mysql
      dbName: polaris_server
      dbAddr: ##数据库地址，格式为ip:port##
      dbUser: ##数据库用户名##
      dbPwd: ##数据库密码##

开启自动注册：修改polaris-server.yaml里面的服务自注册配置，将enable_register改成true，并填入probe_address：

bootstrap:
  polaris_service:
    # 设置为true代表启用自动注册
    enable_register: true
    # 填入数据库地址，用于获取当前节点ip信息
    probe_address: ##数据库地址##

配置Redis参数：修改polaris-server.yaml里面的healthcheck配置，去掉heartbeatMemory相关配置，并放开heartbeatRedis相关配置。

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
	  #填入redis的IP以及端口
      kvAddr: ##REDIS_ADDR##
	  #填入redis的密码
      kvPasswd: ##REDIS_PWD##
      maxIdle: 200
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200

启动polaris-discover：

bash ./tool/start.sh
bash ./tool/p.sh

安装prometheus

下载软件包：点击下载链接，下载prometheus版本，解压后进入prometheus-2.28.0.linux-amd64目录中。
修改配置：打开 prometheus.yml文件，修改prometheus的job配置，增加http_sd_configs，其作用是告知prometheus需要从北极星获取应用的监控上报的地址。

  - job_name: 'prometheus'
    static_configs:
    - targets: ['localhost:9090']

    http_sd_configs:
      - url: http://${polaris部署IP地址}:9000/prometheus/v1/clients

    honor_labels: true

启动prometheus：

nohup ./prometheus --web.enable-lifecycle --web.enable-admin-api >> prometheus.out 2>&1 &

安装polaris-console

下载软件包：下载polaris-console-release_$version.linux.$arch.zip，解压后进入polaris-console-release_$version.linux.$arch目录
修改配置：打开polaris-console.yaml文件，修改monitorServer的地址，将原来的127.0.0.1:9090替换成prometheus的监听地址

monitorServer:
  address: "${prometheus部署IP地址}:9090"

启动polaris-console：

bash ./tool/start.sh
bash ./tool/p.sh

安装polaris-limiter

下载软件包：下载polaris-limiter-release_$version.linux.$arch.zip，解压后进入polaris-limiter-release_$version.linux.$arch目录
修改配置：打开polaris-limiter.yaml文件，修改polaris-server-address的值为北极星服务端地址。

registry:
  enable: true
  polaris-server-address: { 北极星服务端 grpc 协议地址 }
  name: polaris.limiter
  namespace: Polaris
  health-check-enable: true
api-servers:
  - name: http
    option:
      ip: 0.0.0.0
      port: 8100
  - name: grpc
    option:
      ip: 0.0.0.0
      port: 8101
limit:
  myid: { 服务端节点唯一标识信息，int 类型}

注意事项：如果是部署单节点的 polaris-limiter，myid 设置为 1 即可；如果是部署多节点的 polaris-limiter，每个节点的 myid 必须保证唯一。

启动polaris-limiter：

bash ./tool/start.sh
bash ./tool/p.sh

部署后验证

登录控制台的默认登录账户信息。

用户：polaris
密码：polaris

访问http://{控制台IP}:8080，可以看到登录页面，登录后可以成功看到北极星服务治理控制台内容。
执行以下命令，查看 polaris.limiter 服务下的实例信息，是否包含限流服务。

curl --location --request POST '127.0.0.1:8090/v1/Discover' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": 1,
    "service": {
        "name": "polaris.limiter",
        "namespace": "Polaris"
    }
}'

FAQ

MySQL 版本支持

开源MySQL版本支持：当前仅支持 >= 5.7，低版本暂未支持。
云厂商MySQL支持
- 腾讯云：支持 Tencent MySQL版，暂不支持 TDSQL-C MySQL兼容
- 阿里云：支持云数据库RDS MySQL 版

2 - 使用 SDK

功能简介

北极星网格提供多语言 SDK 作为高性能接入方式：

polaris-java
polaris-go
polaris-cpp
polaris-php
polaris-python（即将开源）
polaris-nodejs（即将开源）

以插件化和配置化的方式实现服务发现和治理功能：

被调方功能：服务注册、上报心跳、限流
主调方功能：服务发现、动态路由、负载均衡、熔断降级
观测性功能：服务调用、熔断降级和限流的监控统计

接口说明

被调方功能接口

Register

功能：注册服务实例
描述：将实例注册到某个服务下，实例信息包含地址和元数据

Deregister

功能：反注册服务实例
描述：将某个服务下的实例反注册

Heartbeat

功能：上报心跳
描述：如果在注册服务实例时，开启服务端健康检查功能，需要定期上报心跳到服务端，不然服务实例状态异常

GetLimitQuota

功能：获取请求处理配额
描述：如果使用限流功能，在每次处理请求之前，获取请求处理配额。若有配额，则处理请求，否则拒绝处理请求

主调方功能接口

GetAllInstances

功能：获取全部实例
描述：获取注册到某个服务下的全部实例，包含健康、异常和隔离的实例。本接口只使用服务发现功能模块

GetOneInstance

功能：获取一个可用实例
描述：在每次服务调用之前，获取一个可用实例。本接口使用服务发现、动态路由、负载均衡和熔断降级功能模块
备注：几个功能模块采用插件化设计，默认插件配置适用于基本场景，可以根据业务场景调整插件配置

UpdateServiceCallResult

功能：上报服务调用结果
描述：在每次服务调用之后，上报本次服务调用的结果。服务调用结果用于熔断降级和监控统计

接口使用说明

服务被调方

// 在应用启动阶段，注册服务实例
Register(namespace, service, instance)

// 如果使用服务端健康检查功能，在应用运行阶段，需要定期上报心跳到服务端
{
    Heartbeat(namespace, service, instance)
}

// 如果使用限流功能，在每次处理请求之前，获取请求处理配额
{
    if( GetLimitQuota(limiter) ) {
        Handle(request)
    } else {
        Refuse(request)
    }
}

// 在应用停止阶段，反注册服务实例
Deregister(namespace, service, instance)

服务主调方

// 发起一次服务调用
{
    // 获取本次服务调用的实例
    instance = GetOneInstance(namespace, service)

    // 发起服务调用
    response = ServiceCall(instance.address, request)

    // 上报本次服务调用的结果
    UpdateServiceCallResult(instance.id, response.code, response.delay)
}

快速入门示例

各语言 SDK 的快速入门示例：

3 - 使用开发框架

4 - 使用K8s和网格代理

4.1 - 概念及原理

什么是服务网格

服务网格（service mesh），作为服务间通信的基础设施层，最早出现在 Buoyant 公司的 CEO Willian Morgan 在他的这篇文章 WHAT’S A Service Mesh? AND WHY DO I NEED ONE中：

服务网格（Service Mesh）是处理服务间通信的基础设施层。
它负责构成现代云原生应用程序的复杂服务拓扑来可靠地交付请求。
在实践中，Service Mesh 通常以轻量级网络代理阵列的形式实现，这些代理与应用程序代码部署在一起，对应用程序来说无需感知代理的存在。

服务网格的出现，可以让应用开发者更专注于业务本身的开发，无须关心服务之间的那些原本通过服务框架实现的事情，比如服务流量调度，服务高可用，服务鉴权等服务治理相关的事情。

服务网格通过透明代理来为应用完成这些服务治理的相关事情：

北极星如何支持服务网格

北极星提供服务网格的接入能力，用户使用北极星可以轻松得接入服务网格，其实现原理如下：

被调方应用在POD启动时，k8s会自动将pod ip注册到k8s service中，polaris-controller监听到注册事件后，会同时往北极星服务端注册服务实例。
- 同步kubernetes service时，将 kubernetes service 的 namespace、name、labels、ports 信息同步为北极星的服务
- 同步kubernetes endpoint时，将kubernetes endpoint和对应的kubernets pod信息进行合并，同步为北极星的服务实例
每个POD中，除了业务容器外，还有额外存在两个容器
- polaris-sidecar容器，负责接管POD中的DNS请求，对服务调用的DNS请求重定向给envoy容器。
- envoy容器，负责接管应用的业务流量，接受业务的请求并进行流量调度。
polaris-server会通过XDS的方式，下发服务数据、规则数据以及DNS数据到envoy以及polaris-sidecar中。
Consumer以域名方式发起服务调用时，根据iptables规则，会将DNS请求转发给polaris-sidecar容器，polaris-sidecar容器将含有服务名的DNS请求解析成envoy的地址。
Consumer根据DNS解析结果，向envoy发起请求调用，envoy根据polaris-server下发的服务数据，进行流量调度，最终转发给Provider所在的POD。
Provider收到请求后，通过iptables规则，转发到envoy中处理，envoy进行一些被调的治理操作（比如熔断，鉴权等），最终通过127.0.0.1的IP转发给Provider应用。

北极星服务网格的优势

跨集群的服务发现更简单

北极星是一个计算与存储分离的系统，具备极强的可扩展性，一个北极星集群可以支持多个k8s集群同时接入。

接入到同一个北极星的集群的多个k8s集群中的应用，可以共享同一份服务数据，实现集群间的无感知调用。

支持proxyless网格

北极星提供了多种SDK，可以支持当下比较流行的proxyless网格模式的接入，同时，由于北极星采用了统一的服务治理模型，因此，可以通过同一份服务治理的规则配置，同时应用到proxyless和proxy的应用中，实现统一的服务治理体验。

4.2 - 使用k8s服务同步

原理说明

PolarisMesh提供polaris-controller，基于kubernetes的controller机制，监听service&pod事件，同步集群内的POD实例信息到PolarisMesh注册中心。

准备Polaris服务端

需要预先安装好Polaris服务端，安装方式可参考：安装指南

安装polaris-controller

您需要在应用所在的 Kubernetes 集群部署 Polaris Controller ，如果您有多个 Kubernetes 集群需要接入 Polaris ，需要在每个集群安装一次。

部署包下载

到polaris-controller的下载页面，根据您这边的kubernetes版本号（版本号小于等于1.21.x，选择k8s1.21.zip；版本号为1.22.x，选择k8s1.22.zip），下载最新版本polaris-controller安装包。

github下载

部署包安装

安装前，需确保kubectl命令已经加入环境变量Path中，并且可以访问kubernetes的APIServer。

以polaris-controller-release_${version}.k8s1.21.zip为例：

解压并进入部署包：

unzip polaris-controller-release_${version}.k8s1.21.zip
cd polaris-controller-release_${version}.k8s1.21

查询用户token，由于controller需要直接访问polaris的控制台OpenAPI，因此需要填写token。

打开北极星控制台，选择用户->用户列表->选择polaris用户->查看token，即可获取到token。

修改variables.txt文件，填写polaris的地址（只填IP或者域名，无需端口），如果在同一个集群中，则可以填写集群内域名，同时需要填写上一步所查询到的token

#polaris地址，只填IP或者域名，无需端口
POLARIS_HOST:polaris.polaris-system
#polaris的用户token
POLARIS_TOKEN:4azbewS+pdXvrMG1PtYV3SrcLxjmYd0IVNaX9oYziQygRnKzjcSbxl+Reg7zYQC1gRrGiLzmMY+w+aCxOYI=

执行安装部署。

./install.sh

安装后验证

安装成功后，可以在k8s集群中，polaris-system命名空间，看到polaris-controller的statefulset已经部署完成。

同步完成

安装并启动后，polaris-controller会自动同步kubernetes上面的命名空间，服务以及实例数据。

4.3 - Envoy网格接入

概览

在 Polaris 的服务网格方案中，Polaris 是您的控制平面，Envoy Sidecar 代理是您的数据平面。

服务数据同步：polaris-controller 安装在用户的Kubernetes集群中，可以同步集群上的 Namespace，Service，Endpoints 等资源到 polaris 中，同时 polaris-controller 提供了 Envoy Sidecar 注入器功能，可以轻松地将 Envoy Sidecar 注入到您的 Kubernetes Pod 中，Envoy Sidecar 会自动去 Polaris 同步服务信息。
规则数据下发：polaris控制面通过XDS v3标准协议与envoy进行交互，支持官方开源的envoy直接接入，当前支持的envoy版本为1.18

环境准备

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

部署 polaris-controller

您需要在应用所在的 Kubernetes 集群部署 polaris-controller ，用于将集群中的服务数据接入到polaris （如果已经部署可忽略）。如果您有多个 Kubernetes 集群需要接入 polaris ，需要在每个集群都部署 polaris-controller。

部署包下载

github下载

部署包安装

安装前，需确保kubectl命令已经加入环境变量Path中，并且可以访问kubernetes的APIServer。

以polaris-controller-release_v1.3.0-beta.0.k8s1.21.zip为例：

解压并进入部署包：

unzip polaris-controller-release_v1.3.0-beta.0.k8s1.21.zip
cd polaris-controller-release_v1.3.0-beta.0.k8s1.21

查询用户token，由于controller需要直接访问polaris的控制台OpenAPI，因此需要填写token。

打开北极星控制台，选择用户->用户列表->选择polaris用户->查看token，即可获取到token。

#polaris地址，只填IP或者域名，无需端口
POLARIS_HOST:polaris.polaris-system
#polaris的用户token
POLARIS_TOKEN:4azbewS+pdXvrMG1PtYV3SrcLxjmYd0IVNaX9oYziQygRnKzjcSbxl+Reg7zYQC1gRrGiLzmMY+w+aCxOYI=

执行安装部署。

./install.sh

快速接入

服务调用关系说明

启用 sidecar 自动注入功能

创建命名空间 bookinfo ：kubectl create namespace bookinfo
为 bookinfo 命名空间启用注入：

kubectl label namespace bookinfo polaris-injection=enabled

使用一下命令来验证 bookinfo 命名空间是否已经正确启用：

kubectl get namespace -L polaris-injection

此时应该返回：

NAME             STATUS   AGE    POLARIS-INJECTION
bookinfo          Active   3d2h   enabled

部署样例

下载样例部署文件：bookinfo
执行部署：kubectl create -f bookinfo.yaml
查看容器注入是否注入成功

启动自动注入后，polaris-controller 会将 Envoy Sidecar 容器注入到在此命名空间下创建的 pod 中。

可以看到运行起来的 pod 均包含两个容器，其中第一个容器是用户的业务容器，第二个容器是由 Polaris Controller 注入器注入的 Envoy Sidecar 容器。您可以通过下面的命令来获取有关 pod 的更多信息：

kubectl describe pods -l app=productpage --namespace=bookinfo

此时应返回：

... ...
Init Containers:
# polaris-bootstrap-writer 产生 Envoy 的 Bootstrap 配置
polaris-bootstrap-writer:
... ... 
# istio-init 为 envoy sidecar 设置流量拦截
istio-init:
... ... 
Containers:
# demo 的业务容器
productpage:
... ...
# Envoy 是代理流量的容器
envoy:
... ...

打开productpage界面

通过productpage暴露的地址，可以访问productpage的主界面，进入Normal User或者TestUser后，可以看到（红、黑、无）三种形态的星星，代表demo已经部署成功。

mTLS

北极星网络支持服务间的mTLS认证及加密通讯，提供三种不同的服务粒度模式供用户选择：

模式	解释
Permissive	宽容模式，服务接受纯文本/mTLS服务调用；发起服务调用时，根据对端接受状况自动选择发起mTLS或纯文本服务调用
Strict	严格模式，服务仅接受/发起mTLS服务调用
None	无加密模式（为默认选项），服务仅接受/发起纯文本服务调用

启用方式

只需要在服务的metadata中加入键为polarismesh.cn/tls-mode的label即可开启该功能，可选的值为strict,permissive,none，无此label时或者值错误时，默认为无加密的none模式。

使用示例

部署polaris-security

polaris-security是北极星的证书机构，负责签发证书以供服务使用，是开启双向TLS功能的必要组件。

下载polaris-security
将示例证书/密钥加载为k8s secret：./deploy/load-certs-into-k8s.sh
验证secret加载成功：kubectl get secrets -n polaris-system
使用Helm部署polaris-security, cd deploy/helm && helm install polaris-security .
验证polaris-security部署成功：kubectl get po -n polaris-system | grep polaris-security

部署mTLS版bookinfo示例

下载样例部署文件：mTLS版bookinfo
执行部署：kubectl create -f bookinfo.yaml

mTLS版bookinfo在配置文件中使用polarismesh.cn/tls-mode的label为不同的服务启用了各自的双向TLS模式，部署完成后服务调用图如下所示：

效果验证

Strict模式验证由于Reviews V3服务使用了None模式，它将向Ratings服务发起纯文本请求，而Ratings服务使用了Strict模式，仅接受mTLS服务调用，因此Reviews V3到Ratings之间的服务调用总会失败。
因此，使用浏览器访问部署好的ProductPage，无论怎么刷新都无法看到红色的星星评级。
mTLS验证使用Wireshark抓包验证mTLS启用,如下图：

可以看到Server向Client提供证书后，要求Client提供自身证书，验证通过后方可开始加密数据通信。

使用服务治理能力

流量调度

北极星网格支持根据http请求的头部字段进行路由，支持通过path, header, query这3种类型的属性来进行路由。

使用场景

demo 项目中，productpage 会访问 reviews 服务，reviews 服务共有三个实例，三个实例分别部署了三个版本（会显示红、黑、无三种颜色的星星），需要保证特定的灰度用户（用户名为jason），请求到特定版本的 reviews 服务。

配置路由规则

为 reviews 服务创建路由规则。将请求中 header 包含字段 end-user=jason 的请求，路由到 version=v2 的服务实例中。同时再创建一条路由规则，指定标签键值为任意请求，路由到 version=v1 的服务实例中。

路由规则的标签填写格式要求：

对于Path：标签KEY需要填写$path
对于Header：标签KEY需要带上前缀$header，如$header.end-user
对于Query：标签KEY需要带上前缀$query，如$query.end-user

验证路由是否生效

未登陆时，刷新 productpage 的页面，可以看到只返回没有颜色的星星（version=v1）。当使用 jason 登陆后，productpage 请求 reviews 时，会带上 header，end-user=jason，此时再刷新 productpage 页面，发现只会显示黑色的星星，即上面 version=v2 的实例。

访问限流

北极星网格支持单机限流和分布式限流，同时直接细粒度的配额的设置。

在envoy接入的场景中，受XDS协议的限制，当前限流粒度只能支持到header以及客户端IP这2个维度。

实现原理：polaris-sidecar提供标准的RLS协议的实现，使得envoy可以直接对接北极星的限流引擎。

使用场景

demo项目中，为details服务设置流量限制，对于jason用户的请求，设置访问的频率为5/m，其余请求不做限制。

设置限流规则

指定请求中 header 包含字段 end-user=jason 的请求，设置限流规则为5/m，限流类型为分布式限流。

详细的限流规则匹配及使用指南可参考：访问限流

验证限流是否生效

未登陆时，多次刷新界面，不会出现错误。

以jason用户身份登陆，一分钟刷新超过5次，details界面出现限流的错误信息。

5 - 使用网关

5.1 - Nginx网关接入

功能简介

北极星的服务治理能力，支持在微服务网关层使用，下面主要介绍如何在Nginx网关上，基于北极星使用动态upstream管理、访问限流、流量监控等能力。

快速入门示例

kubernetes环境使用

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

访问限流

部署polaris-limiter：注意，如果使用的是1.12之前版本的polaris单机版，则需要额外部署polaris-limiter，作为分布式限流的集中式token-server。部署方法可参考：polaris-limiter
获取样例：下载最新版本的nginx-gateway的release，获取对应版本的源码包：Source code (zip)。
部署文件说明：以1.1.0-beta.0为例，源码包名称为：nginx-gateway-1.1.0-beta.0.zip，解压后，部署文件为examples/ratelimit/nginx.yaml，里面包含有如下环境变量，用户可以按照自己的需要进行修改。

变量名	默认值	说明
polaris_address	polaris.polaris-system:8091	北极星服务端地址，8091为GRPC端口
polaris_nginx_namespace	default	网关服务所在的命名空间
polaris_nginx_service	nginx-gateway	网关服务所在的服务名，用于查找并关联限流规则
polaris_nginx_ratelimit_enable	true	是否启用限流功能

部署样例：以1.1.0-beta.0为例，源码包名称为：nginx-gateway-1.1.0-beta.0.zip

unzip nginx-gateway-1.1.0-beta.0.zip
cd nginx-gateway-1.1.0-beta.0
kubectl apply -f examples/ratelimit/nginx.yaml

配置限流规则

在北极星控制台新建一个限流规则，服务名和命名空间分别选择nginx-gateway以及default，设置根据http header（user=1000）进行流量限制。

验证限流效果

通过postman，在http请求中带上头信息：user:1000，一分钟超过5次调用，会返回限流错误。

虚拟机环境使用

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在linux虚拟机环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

安装nginx网关

下载安装包：可以在GITHUB的版本页面下载最新的虚拟机安装包，当前只提供基于ubuntu-latest编译的虚拟机安装包，如需其他版本，可以通过源码编译的方式来进行打包。版本下载地址：release
解压安装包：以nginx-gateway-release-1.1.0-beta.0.linux.x86_64.tar.gz为例。

tar xf nginx-gateway-release-1.1.0-alpha.6.linux.x86_64.tar.gz
cd nginx-gateway-release-1.1.0-alpha.6.linux.x86_64

修改端口号（可选）：nginx默认端口号为80，如需修改端口号，可以通过编辑conf/nginx.conf配置文件进行修改。

http {
  server {
    listen 80; #这里修改成希望监听的端口号
  }
}

添加环境变量（可选）：可通过添加环境变量的方式，指定nginx-gateway对应的参数设置。环境变量说明。

变量名	默认值	说明
polaris_address	polaris.polaris-system:8091	北极星服务端地址，8091为GRPC端口
polaris_nginx_namespace	default	网关服务所在的命名空间
polaris_nginx_service	nginx-gateway	网关服务所在的服务名，用于查找并关联限流规则
polaris_nginx_ratelimit_enable	true	是否启用限流功能

重启nginx

cd nginx-gateway-release-*/sbin
bash stop.sh
bash start.sh

其他资料

如果需要编译Nginx网关，可以参考：nginx-gateway

快速入门

1 - 安装服务端

1.1 - 单机版安装

安装说明

单机版组网

安装服务端

环境准备

单机版软件包

下载地址

Linux

Windows

Mac

Docker 安装

Kubernetes 安装

安装验证

打开控制台

新建服务

1.2 - 集群版安装

集群版组件说明

最小生产组网规格

部署架构

获取最新软件包

安装第三方依赖

部署MySQL

初始数据导入

部署Redis

安装系统组件

部署在kubernetes

修改配置

执行部署

部署在Linux虚拟机

安装polaris

安装prometheus

安装polaris-console

安装polaris-limiter

部署后验证

FAQ

MySQL 版本支持

2 - 使用 SDK

功能简介

接口说明

被调方功能接口

主调方功能接口

接口使用说明

服务被调方

服务主调方

快速入门示例

Java语言

Go语言

C++语言

PHP语言

3 - 使用开发框架

4 - 使用K8s和网格代理

4.1 - 概念及原理

什么是服务网格

北极星如何支持服务网格

北极星服务网格的优势

跨集群的服务发现更简单

支持proxyless网格

4.2 - 使用k8s服务同步

原理说明

准备Polaris服务端

安装polaris-controller

部署包下载

部署包安装

安装后验证

同步完成

4.3 - Envoy网格接入

概览

环境准备

部署polaris

部署 polaris-controller

部署包下载

部署包安装

快速接入

服务调用关系说明

启用 sidecar 自动注入功能

部署样例

mTLS

启用方式