Skip to main content

Installation and Deployment

Prerequisites​

  • Kubernetes version >= 1.11 or OpenShift version >= 3.10.

  • The Kubernetes cluster must have kubectl installed, and all commands need to be executed on the kubectl control node. The OpenShift cluster must have oc installed, and all commands need to be executed on the oc control node.

  • The cluster must enable the MutatingAdmissionWebhook plugin (it is disabled by default on OpenShift 3.x platform).

  • The cluster must have idle resources greater than the minimum required by the Agent: 4 Core CPU, 16GB memory.

    Note:

    • Kubernetes UniAgent has already integrated the Agent Collector, so there is no need to deploy the Agent Collector before deployment.
    • Since the Agent Collector consumes relatively high resources, to avoid affecting the operation of business application Pods, it is recommended to use nodeSelector to fix the Agent Collector to specific Nodes.

Deploying the Agent​

Step 1. Log in to the Guanyun Platform.

Step 2. In the left navigation bar, select Management > Deployment Status.

Step 3. On the UniAgents page, click Add in the upper right corner to deploy a new UniAgent.

Step 4. Select the deployment platform as Kubernetes or OpenShift.

On the OpenShift platform, only APM Agent deployment is supported, Infra Agent deployment is not supported.

Step 5. Configure Kubernetes basic information.

  • Cluster Name: The name of the Kubernetes cluster where UniAgent will be deployed. The fields Deployment Environment and Business System below will automatically synchronize with this value.

  • Kubernetes Version: By default, version 1.18+ is selected. Available options include 1.18+, 1.14–1.17, and 1.11–1.13. Please ensure the selected version matches your actual Kubernetes version.

  • Private Repository Address: You need to upload the probe image to a private image repository. For detailed steps, see Private Image Repository Deployment.

  • Namespace: The name of the Namespace where UniAgent will be deployed. The default value is tingyun. You may customize this name, but please ensure it is a dedicated Namespace.

  • Deployment Environment: The name of the deployment environment where the Kubernetes cluster resides. By default, it is linked with the Cluster Name, but it can also be filled in separately. The environment name can include letters, digits, underscores (_), and hyphens (-).

  • Business System: The business system to which the monitoring data belongs. By default, it is linked with the Cluster Name, but it can also be filled in separately. Applications monitored by UniAgent will be associated with this business system by default.
    If the entered business system does not exist, the TingYun reporting system will automatically create a new one with that name.
    The business system name can include letters, digits, underscores (_), and hyphens (-).

  • APM Aggressive Mode:

    • When disabled, you must first label the Namespace and then label the Deployment before the APM probe can be injected.
    • When enabled, the APM probe will be injected into all applications within any labeled Namespace.

  • Enable Infra: The Infra feature includes monitoring Node-level resources such as CPU and memory usage, file system utilization, and application logs. This feature requires privileged permissions to run.

  • Monitor File System: Requires mounting the Node's root directory and enabling read access.

  • Monitor Application Logs: Requires mounting the Node's root directory and enabling write access to /opt/.position.json.

  • Enabled Collector Replicas: By default, one Collector replica is deployed. If the Trace traffic in the cluster is high, please refer to Collector Deployment to configure the number of Collector replicas.

Step 6. Choose one of the following methods to download the UniAgent yaml file.

  • Method 1: Click Generate, the system will generate an installation command. Click the copy button on the right to copy the installation command to the clipboard, and execute this command on the target server.
  • Method 2: If the network is not connected, you can directly click the Download button on the right to download the yaml file, and upload the yaml file to the target server.

Step 7. If the Namespace (e.g., tingyun) filled in Step 5 does not exist in the Kubernetes cluster, you need to create the Namespace in Kubernetes. If the Namespace already exists, skip this step.

kubectl create namespace tingyun

Step 8. Execute the downloaded yaml file in Kubernetes, and keep the yaml file for future configuration updates, image upgrades, or Agent uninstallation.

kubectl apply -f tingyunagent.yaml

Installing the Agent requires MutatingWebhookConfiguration, ClusterRoleBinding, and ClusterRole permissions. If permissions are insufficient, please contact the Kubernetes cluster administrator for operation. For details, see Troubleshooting.

Step 9. Verify whether the installation is successful and confirm that all Pods are in Running status.

kubectl get pods -n tingyun

If the status is abnormal, see Troubleshooting.

Step 10. Enable application monitoring.

By default, APM Agent is not injected into application Pods. To enable application monitoring, perform the following operations:

  • Label the Namespace where the application Pod is located.

    kubectl label namespace [namespace of the application] tingyun-injection=enabled

  • Label the deployment/daemonset/statefulset, set tingyun-agent-injected to true. For example, for a Tomcat deployment, the configuration is as follows:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: demo1
      namespace: default
    spec:
      selector:
        matchLabels:
          app: demo1
      template:
        metadata:
          labels:
            tingyun-agent-injected: "true"
        spec:
          containers:
          - name: demo1
            image: tomcat

  • In aggressive injection mode, all applications under the labeled Namespace will have APM Agent injected:

    kubectl label namespace [namespace of the application] tingyun-injection=enabled

  • For Go applications, only startup commands with the full path to the application are supported. Shell script-based startup is not supported, nor is aggressive mode deployment (requires Agent version v2.5.7.0 or above, see Go Agent Support List for details).

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: demo1
      namespace: default
    spec:
      selector:
        matchLabels:
          app: demo1
      template:
        metadata:
          labels:
            tingyun-go-entrypoint: enabled
        spec:
          containers:
          - name: demo1
            image: goapp
            command: ['/app/demo']

  • To disable monitoring for a specific application, label the deployment/daemonset/statefulset, set tingyun-agent-injected to false. For example, for a Tomcat deployment, the configuration is as follows:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: demo1
      namespace: default
    spec:
      selector:
        matchLabels:
          app: demo1
      template:
        metadata:
          labels:
            tingyun-agent-injected: "false"
        spec:
          containers:
          - name: demo1
            image: tomcat

Step 11. Verify deployment status.

At the bottom of the Add UniAgent Deployment page, click the View Deployment Status button to jump to the UniAgents Management page, where you can see the newly deployed server and its process information. If there is data, it means the UniAgent deployment is successful.

In the left navigation bar, click Application & MicroServices > Business System to enter the business system topology page. In the application area at the bottom left of the operation panel, you can see the newly created application.

In the left navigation bar, click Infrastructure Monitoring > Host Monitoring to see the newly created host information. The number of Nodes in the Kubernetes cluster will correspond to the number of new hosts.

Agent Resource Requirements​

APM Injector​

By default, there is only one Pod, which can be horizontally scaled for automatic injection of application Agents.

limits:
  cpu: "0.5"
  memory: "200Mi"
requests:
  cpu: "0.01"
  memory: "10Mi"

APM initContainer​

This is started with the application Pod and destroyed after initialization. The resources are temporarily used.

limits:
  cpu: "0.5"
  memory: "200Mi"
requests:
  cpu: "0.01"
  memory: "10Mi"

Collector​

By default, there is one Pod, which can be horizontally scaled for collecting application performance data and infrastructure monitoring data.

limits:
  cpu: "4"
  memory: "16Gi"
requests:
  cpu: "2"
  memory: "8Gi"

Infra Agent​

By default, one Pod is started on each Node for infrastructure monitoring.

limits:
  cpu: "2"
  memory: "1Gi"
requests:
  cpu: "0.2"
  memory: "200Mi"

Kubelet Metric​

By default, one Pod is started on each Node for infrastructure monitoring.

resources:
  limits:
    cpu: "200m"
    memory: "200Mi"
  requests:
    cpu: "100m"
    memory: "100Mi"

Cluster Metric​

One Pod for infrastructure monitoring.

resources:
  limits:
    cpu: "200m"
    memory: "200Mi"
  requests:
    cpu: "100m"
    memory: "100Mi"