Polaris provides the capability to associate Kubernetes clusters. After a TKE cluster is associated, the Polaris Controller component will be installed. The Polaris Controller can synchronize resources such as Namespaces, Services, and Endpoints from your Kubernetes cluster to Polaris, enabling automatic registration of Kubernetes Services to Polaris. These services can be accessed using Polaris APIs and multi-language SDKs, as well as through open-source frameworks like gRPC and Spring Cloud. Service discovery can also be performed via DNS Agent, and non-intrusive access can be achieved through Java Agent.
Primarily applicable to the following scenarios:
In scenarios of heterogeneous systems and multi-technology stack, frameworks such as Spring Cloud call K8s cluster services.
Service invocation across clusters.
This document describes the capabilities of using K8s clusters via the TSF console.
Operation Steps
Create Engine
1. Log in to the TSF console, and select Polaris (North Star) from the left menu bar.
2. On the engine instance list page, click the "ID" of the target engine to go to the basic information page.
3. Click the K8s Cluster tab at the top, and click Associate Cluster.
Note:
1. Adding a TKE cluster will install the Polaris-Controller component. Ensure that your cluster has at least 1C2G of idle resources; otherwise, the cluster will fail to be added.
2. After the Polaris-Controller component is installed in a TKE cluster, it supports the following capabilities by default: K8s Service synchronization (on-demand), DNS Agent for specified domain name resolution, and Java Agent auto-injection. You can also select full synchronization in the console to choose the k8s full synchronization mode.
Cluster selection: You can choose the target K8s cluster based on your business requirements. Supported cluster types include TKE (TKE cluster) / EKS (Elastic Kubernetes Service cluster).
Capabilities: K8s Service synchronization; DNS Agent resolution; Java Agent access.
Working Principles
K8s Service Synchronization
By associating K8s clusters, services are automatically synchronized to Polaris, supporting on-demand/full synchronization. Services can be accessed via Polaris APIs / multi-language SDKs / DNS Agent / open-source frameworks (gRPC / Spring Cloud, etc.).
polaris-controller
After tke/eks clusters are associated in the TSF console, polaris-controller will be automatically deployed in your corresponding tke/eks clusters. For details, see Resource Manifest.
You can specify annotations in the K8s service to control the synchronization behavior of polaris-controller. For specific guidelines and examples, see Annotations Supported by polaris-controller.
1.
Resource Manifest
The K8s resource manifest created in your tke/eks clusters is as follows:
Resource Type
Resource Name
Resource Purpose
namespace
polaris-system
polaris-controller and its related configurations are located under this namespace.
deployment
polaris-controller
workload that provides synchronization services
configmap
injector-mesh, polaris-sidecar-injector
configuration files used by polaris-controller
serviceAccount
polaris-controller
providing permissions required for accessing K8s resources
clusterRole
polaris-controller
providing permissions required for accessing K8s resources
clusterRoleBinding
polaris-controller
providing permissions required for accessing K8s resources
mutatingWebhookConfiguration
polaris-sidecar-injector
providing automatic injection capability
You can use the command in the image below to view the resources mentioned above.
2.
polaris-controller Synchronization Behavior
polaris-controller synchronizes all namespaces, services, and endpoints in the K8s cluster by default.
Resource Type
Resource Action
namespace
When a namespace is created, a namespace with the same name is created in polarismesh.
When a namespace is deleted, the namespace with the same name in polarismesh is not removed.
service
When a service is created, a service with the same name is created in the corresponding namespace in polarismesh, regardless of the service type.
When a service is deleted, the service in the corresponding namespace in polarismesh is not removed. However, the instances of the corresponding service in polarismesh are removed (only the instances synchronized from this K8s cluster to the corresponding service in polarismesh are removed).
endpoints
When endpoints for a service are created, each combination of IP address and port from the endpoints list is synchronized to polarismesh as a service instance under the corresponding service. If an IP address is in the ready address list of the endpoints, the service instance status in polarismesh is healthy. If it is in the not-ready address list, the status in polarismesh is unhealthy.
When the address list of a service's endpoints changes, it is dynamically synchronized to polarismesh. If the address list expands, new instances are registered under the service in polarismesh. If the address list shrinks, the corresponding instances under the service in polarismesh are deregistered.
When the endpoints of a service are removed, all instances synchronized from this K8s cluster to the corresponding service in polarismesh are removed from the service in polarismesh.
3.
polaris-controller Supported Annotations
You can specify annotations in the k8s service to control the synchronization behavior of polaris-controller. The following annotations are currently supported.
Annotation Name
Annotation Description
polarismesh.cn/sync
Whether to synchronize this service to polarismesh. true for synchronization, false for no synchronization, default is no synchronization.
polarismesh.cn/aliasService
The name of the service alias created when the k8s service is synchronized to polarismesh.
polarismesh.cn/aliasNamespace
The namespace where the created alias resides, used in conjunction with polarismesh.cn/aliasService.
4. How to Synchronize On Demand
polaris-controller synchronizes all services in the K8s cluster by default. In certain scenarios, you may only want to synchronize specific services to polarismesh. In such cases, you can set the synchronization mode to (on-demand synchronization) and use the polarismesh.cn/sync annotation to specify the services to be synchronized.
On-demand synchronization of a single service: When the following service is created, polaris-controller will synchronize the service to polarismesh.
apiVersion: v1
kind: Service
metadata:
name: details
annotations:
polarismesh.cn/sync: true
... ...
On-demand synchronization of all services in a namespace: Label the namespace, and polaris-controller will synchronize all services created within that namespace to polarismesh.
apiVersion: v1
kind: Namespace
metadata:
name: default
annotations:
polarismesh.cn/sync: "true"... ...
5. Create Alias Example
polaris-controller creates a corresponding polarismesh service using the service name by default. The following scenarios may require creating a service alias:
If you do not want to use the service name as the polarismesh service name—for example, if you want the polarismesh service name to be in uppercase while Kubernetes service names are restricted to lowercase—you can use the alias annotation to specify an uppercase polarismesh service name.
You want to expose a service in a namespace to another namespace. In this case, you can use an alias annotation to specify another namespace.
When the service in the following example is created, polaris-controller will create a service named productpage under the development namespace in polarismesh. It will also create a service alias named Productpage under the Development namespace.
apiVersion: v1
kind: Service
metadata:
namespace: development
name: productpage
annotations:
polarismesh.cn/aliasService: Productpage
polarismesh.cn/aliasNamespace: Development
... ...
6. How to Check the polaris-controller Version
Click the cluster ID to navigate to the Container Console page and check the image version of the polaris-controller StatefulSet in the polaris-system namespace.
DNS Agent Access
In the DNS Agent service discovery solution of Polaris, Polaris serves as your control plane, and Polaris Sidecar functions as a local DNS server to implement service discovery.
Container Scenarios:
polaris-server: the Polaris server that handles service registration and service discovery requests.
polaris-controller: injects the polaris-sidecar container into business Pods and issues iptables commands to intercept DNS requests from business containers, redirecting them to polaris-sidecar.
polaris-sidecar: functions as a local DNS server that resolves DNS domain names to services in Polaris to implement service discovery.
Virtual Machine Scenarios:
polaris-server: the Polaris server that handles service registration and service discovery requests.
polaris-sidecar: functions as a local DNS server that resolves DNS domain names to services in Polaris to implement service discovery.
Note: When using DNS for service discovery, ensure that both namespace and service names are registered in all lowercase letters on Polaris; otherwise, resolution will fail.
1. Configuration Interpretation
Virtual Machine:
polaris-sidecar.yaml content and configuration are described as follows:
bind:0.0.0.0 # the DNS server listens on this IP
port:53 # DNS server listening port
namespace:default # the namespace where polaris-sidecar resides
recurse: # recursive resolution: when polaris-sidecar cannot resolve the domain name itself, it forwards tothe upstream DNS server for further resolution.
enable:true
timeoutSec:1
resolvers: # DNS resolution plugin
- name: dnsagent # DNS proxy plugin
enable:true # whether the plugin is enabled
dns_ttl:10 # client-side TTL for dns records
suffix:"." # determines which domain name resolutions will be handled by polaris-sidecar, defaults toall domain names, example:".abc"
Container:
DNS Agent supports the following configuration in the deployment YAML of the caller side in a k8s environment, with description and examples as follows:
Recursive configuration: enable recursive resolution with a timeout of 5 seconds for requesting the next nameserver;
DNS proxy resolution configuration: resolution suffix is .dns-test, client-side DNS resolution records TTL is 3 seconds;
spec:
template:
metadata:
labels:
env:dev
annotations:
polarismesh.cn/sidecarConfig:|
{
"recurse": {
"enabled": true,
"timeout": 5
},
"dns": {
"suffix": ".dns-test",
"ttl": 3
}
......
2. Quick Access
Virtual Machine Onboarding
1) Install polaris-sidecar.
Ensure that port 53 (UDP/TCP) is not occupied.
Download the latest version of the installation package from Releases.
Upload the installation package to the virtual machine environment, unzip it, and enter the unzipped directory.
Modify /etc/resolv.conf with root privileges by adding nameserver 127.0.0.1 to the file and placing it before all existing nameserver records, as follows:
nameserver 127.0.0.1
nameserver x.x.x.x
3) Verify.
Access using the domain name in the format <service>.<namespace>, and you are expected to obtain the IP address of an instance under the service.
➜ dig polaris.checker.polaris
...
;; ANSWER SECTION:
polaris.checker.polaris. 10 IN AAAA ::ffff:127.0.0.1
...
Container Access
1) Associate the k8s cluster.
2) Enable polaris-sidecar injection.
Note:
The sidecar requires the polaris controller version to be above V2.1.0.0. You can unbind and rebind the cluster to upgrade the polaris controller version. During the process from unbinding to rebinding, do not perform service registration and deregistration.
Option 1: Enable polaris-sidecar injection for a Kubernetes namespace using the label command:
# Enable polaris sidecar injection for a kubernetes namespace
Check whether the container injection is successful. After automatic injection is enabled, polaris-controller will inject the Polaris Sidecar container into pods created in this namespace. It can be seen that the running pods all contain two containers: the first container is the user's business container, and the second container is the Polaris Sidecar container injected by the Polaris Controller injector. You can obtain more information about the pods using the following command:
Enter the verification pod. The address format of the called service is <service>.<namespace>:<port>. The following example shows a request to the /echo interface of the echoserver service in the default namespace.
After the polaris controller is installed, non-intrusive integration is supported via Java Agent. You can inject Java Agent into Spring Cloud applications by adding annotations. The Java Agent automatically introduces SpringCloud Tencent dependencies to integrate with the Polaris registration and configuration governance center. See Overview of Java Agent Integration.
