Connect to ARMS through an NGINX forward proxy - Application Real-Time Monitoring Service

An NGINX forward proxy relays the monitoring data of an ARMS agent to the Alibaba Cloud ARMS server on behalf of applications that have no Internet access. Use a forward proxy when only specific machines in the environment that runs your application can access the Internet.

When to use a forward proxy

You can connect applications that are deployed in non-Alibaba Cloud environments, including on-premises data centers and other cloud environments, to ARMS Application Monitoring as long as the network can communicate with the ARMS server. You can connect over the Internet or over an Express Connect circuit. For more information about the connection methods, see Application Monitoring overview.

If only specific machines in the environment where your application runs can access the Internet, use a forward proxy to relay the traffic. Most users do not need a forward proxy. The requirement can arise in environments that have special network security requirements, such as financial systems.

Architecture

In the preceding figure, the Java application runs in the application deployment zone of an on-premises data center and cannot access the Internet. Only the demilitarized zone (DMZ) has Internet access. NGINX runs in the DMZ and forwards the monitoring data that the ARMS agent reports to the Alibaba Cloud ARMS server. To build this data path, first configure NGINX in the DMZ, and then set the NGINX instance as the destination for reporting monitoring data in the ARMS agent configuration.

Prerequisites

NGINX — Deploy NGINX in the DMZ and make sure that it can access the Internet. For installation instructions, see NGINX official documentation.
ARMS agent — Install the ARMS agent on the Java application. For instructions, see Manually install an ARMS agent for Java applications or Install the ARMS agent in a generic Kubernetes cluster.
Agent version for Kubernetes — To use forward proxy mode with an agent that is automatically installed in a container environment, the agent version must be V3.2.0 or later. If your agent version is earlier than V3.2.0, upgrade the agent first. For instructions, see Update the agent.
Agent version for Arthas and continuous profiling — Agent V4.6.x and later support the Arthas and continuous profiling features in proxy mode.
ARMS endpoints — Obtain the ARMS endpoint domain name and the IP address of the Application Configuration Management (ACM) engine for the Alibaba Cloud region that you want to connect to. For details, see Network configurations required by the ARMS agent for Java.
Alibaba Cloud account ID — Obtain the ID of your Alibaba Cloud account. For details, see How do I view the ID of an Alibaba Cloud account?.

Configure NGINX

NGINX in the DMZ forwards the monitoring data of the ARMS agent to the ARMS endpoints of the region that you connect to. The following table lists the host aliases, listening ports, and forwarding targets that the configuration in this section defines.

Host alias	Listening port	Path	Forwarding target	Value to replace
`arms-service`	80	Alibaba Cloud account ID	Continuous profiling endpoint	Account ID and continuous profiling endpoint
`arms-service`	80	`/arthas`	Arthas download URL	Region ID in the URL
`arms-service`	80	`/`	Trace endpoint	Trace endpoint
`arms-meta`	9990	`/`	ARMS endpoint on port 9990	ARMS endpoint domain name
`arms-metrics`	80	`/`	Metric endpoint	Metric endpoint
`arms-acm`	8080	`/`	Returns `$server_addr`	None
`arms-acm`	8848	`/`	ACM engine on port 8848	IP address of the ACM engine
`arms-arthas`	9092	Not applicable	ARMS endpoint on port 9092	ARMS endpoint domain name

The arms-arthas upstream belongs to the stream block that you configure in Step 2. All other rows are server blocks that you configure in Step 1. On the application side, each host alias in the preceding table, together with the arms-profiling-<region-id>.arms-service alias, resolves to the IP address of NGINX.

Step 1: Configure the server blocks

Modify the /etc/nginx/site-available/default file and add the following content:

server {
  listen 80 default_server;
  listen [::]:80 default_server;

  server_name arms-service;
  ignore_invalid_headers off;

  # Replace the numeric part with your Alibaba Cloud account ID.
  location /1672753017****** {
    # Replace the URL with the continuous profiling endpoint of your region.
    proxy_pass http://arms-profiling-cn-shenzhen.oss-cn-shenzhen.aliyuncs.com;
  }

  location /arthas {
    # Replace the region ID in the following URL with the region that you actually connect to.
    proxy_pass http://arms-apm-cn-shenzhen.oss-cn-shenzhen.aliyuncs.com;
  }

  location / {
    # Replace the URL with the trace endpoint of your region.
    proxy_pass http://arms-dc-sz.aliyuncs.com;
  }
}

server {
  listen 9990;
  server_name arms-meta;
  ignore_invalid_headers off;
  location / {
    # Replace the domain name with the ARMS endpoint of your region.
    proxy_pass http://arms-dc-sz.aliyuncs.com:9990;
  }
}

server {
  listen 80;
  server_name arms-metrics;
  ignore_invalid_headers off;

  location / {
    # Replace the URL with the metric endpoint of your region.
    proxy_pass http://cn-shenzhen.arms.aliyuncs.com;
  }
}

server {
  listen 8080;
  server_name arms-acm;
  ignore_invalid_headers off;

  location / {
    return 200 $server_addr;
  }
}

server {
  listen 8848;
  server_name arms-acm;
  ignore_invalid_headers off;

  location / {
    # Replace the IP address with the IP address of the ACM engine of your region.
    proxy_pass http://139.196.135.144:8848;
  }
}

Step 2: Configure the stream block

Modify the /etc/nginx/nginx.conf file and add the following content:

stream {
    upstream arms-arthas {
        # Replace the domain name with the ARMS endpoint of your region.
        server arms-dc-sz.aliyuncs.com:9092;
    }

    server {
        listen 9092;
        proxy_pass arms-arthas;
    }
}

Configure the ARMS agent

Change the destination for data reporting of the ARMS agent from the ARMS public endpoint to NGINX. Forward proxy mode supports agents that are manually installed and agents that are automatically installed in a Kubernetes environment.

After the agent is installed, the destination for data reporting is the public endpoint of ARMS. Because the environment where the Java application runs has no Internet access, the agent cannot reach that endpoint. After you change the destination for data reporting to NGINX, the application can be connected to ARMS.

Select the tab that matches your agent version. Agent V4.x and later use the apsara.apm.collector.profile_endpoint and apsara.apm.arthas.download_endpoint configuration items, and agent V3.x and earlier use the profiler.oss.endpoint configuration item. Within each tab, follow the procedure that matches the way the agent was installed.

Agent V4.x and later

Manual installation mode

Step 1: Modify the hosts file

Modify the /etc/hosts file on the host that runs the application and add the following content. Replace the IP address with the IP address of NGINX.

10.0.0.201 arms-service
10.0.0.201 arms-metrics
10.0.0.201 arms-meta
10.0.0.201 arms-acm
# Replace cn-shenzhen in the domain name with the ID of the region that you connect to.
10.0.0.201 arms-profiling-cn-shenzhen.arms-service

Step 2: Modify the network reporting configuration of the agent

Use either of the following methods.

Method 1: Use a configuration file

In the root directory of the agent, create an arms-agent.config file with the following content:

# The following five configuration items exist in ARMS agents of all versions.
profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
# The following two configuration items apply to agent V4.x and later.
apsara.apm.collector.profile_endpoint=arms-service
apsara.apm.arthas.download_endpoint=arms-service

Add -Darms.config.file=/path/to/arms-agent.config to the startup parameters of the application. Replace /path/to/arms-agent.config with the absolute path of the arms-agent.config file.

Method 2: Use startup parameters

Add the following agent startup parameters:

-Dprofiler.collector.trace.endpoint=arms-service -Dprofiler.collector.metric.endpoint=arms-metrics -Dprofiler.collector.meta.endpoint=arms-meta -Dprofiler.collector.endpoint=arms-service -Dprofiler.acm.endpoint=arms-acm -Dapsara.apm.collector.profile_endpoint=arms-service -Dapsara.apm.arthas.download_endpoint=arms-service

Automatic installation mode in a Kubernetes environment

Step 1: Create a ConfigMap

Create a ConfigMap named arms-agent-proxy-mode.config and enter the following content:

apiVersion: v1
kind: ConfigMap
metadata:
  name: arms-agent-proxy-mode.config
data:
  arms-agent.config: |-

### Copy the other content of arms-agent.config and modify only the following 7 configuration items. ####

    profiler.collector.trace.endpoint=arms-service
    profiler.collector.metric.endpoint=arms-metrics
    profiler.collector.meta.endpoint=arms-meta
    profiler.collector.endpoint=arms-service
    profiler.acm.endpoint=arms-acm
    apsara.apm.collector.profile_endpoint=arms-service
    apsara.apm.arthas.download_endpoint=arms-service

### Copy the other content of arms-agent.config and modify only the following 7 configuration items. ####

Step 2: Modify the application YAML

Modify the YAML file of the workload that runs the application, as shown in the following example:

apiVersion: apps/v1
kind: Deployment
metadata:    
  labels:
    app: spring-boot-demo
  name: spring-boot-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: spring-boot-demo
  template:
    metadata:
      labels:
        app: spring-boot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: spring-boot-demo
    spec:
      hostAliases:
      # Replace this IP address with the IP address of NGINX.
      - ip: "192.168.172.171" 
        hostnames:
        - "arms-service"
        - "arms-metrics"
        - "arms-meta"
        - "arms-acm"
        # Replace cn-shenzhen in the domain name with the ID of the region that you connect to.
        - "arms-profiling-cn-shenzhen.arms-service"
      containers:
        - env:
            # Point the agent configuration to the new modified configuration file.
            - name: ARMS_CONFIG_FILE
              value: /home/admin/.opt/ArmsAgent/arms-agent-proxy-mode.config
          image: >-
            registry.cn-hangzhou.aliyuncs.com/ahas_apsara_adp/spring-boot-demo:wt-test
          imagePullPolicy: Always
          name: spring-boot-demo
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            limits:
              cpu: 500m
              memory: 1Gi
            requests:
              cpu: 250m
              memory: 512Mi
          volumeMounts:
            # Mount it to the agent directory as the new configuration file.
            - mountPath: /home/admin/.opt/ArmsAgent/
              name: arms-agent-proxy-mode
      imagePullSecrets:
        - name: wt-test
      volumes:
        # Map the configMap to a volume named arms-agent-proxy-mode.
        - configMap:
            name: arms-agent-proxy-mode.config
          name: arms-agent-proxy-mode

Note

In the preceding YAML file, the commented parts are the content that you need to check and modify.

Agent V3.x and earlier

Manual installation mode

Step 1: Modify the hosts file

Modify the /etc/hosts file on the host that runs the application and add the following content. Replace the IP address with the IP address of NGINX.

10.0.0.201 arms-service
10.0.0.201 arms-metrics
10.0.0.201 arms-meta
10.0.0.201 arms-acm
# Replace cn-shenzhen in the domain name with the ID of the region that you connect to.
10.0.0.201 arms-profiling-cn-shenzhen.arms-service

Step 2: Modify the agent configuration file

In the agent directory, find the arms-agent.config configuration file and modify the values of the following configuration items:

# The following five configuration items exist in ARMS agents of all versions.
profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
# The profiler.oss.endpoint configuration item is added in agent V3.2.0 and later. You must change the value of this configuration item to arms-service.
profiler.oss.endpoint=arms-service

Automatic installation mode in a Kubernetes environment

Step 1: Obtain the content of the agent configuration file

For a Java application on which the ARMS agent is automatically installed, log on to one of its pods. You can find the configuration file of the agent in the /home/admin/.opt/ArmsAgent/arms-agent.config path and copy the content of the file.

Step 2: Create a ConfigMap

In the content that you copied in the previous step, modify the values of the following configuration items:

profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
profiler.oss.endpoint=arms-service

Create a ConfigMap named arms-agent-proxy-mode.config and enter the modified content:

apiVersion: v1
kind: ConfigMap
metadata:
  name: arms-agent-proxy-mode.config
data:
  arms-agent.config: |-

### Copy the other content of arms-agent.config and modify only the following 6 configuration items. ####

    profiler.collector.trace.endpoint=arms-service
    profiler.collector.metric.endpoint=arms-metrics
    profiler.collector.meta.endpoint=arms-meta
    profiler.collector.endpoint=arms-service
    profiler.acm.endpoint=arms-acm
    profiler.oss.endpoint=arms-service

### Copy the other content of arms-agent.config and modify only the following 6 configuration items. ####

Step 3: Modify the application YAML

Modify the YAML file of the workload that runs the application, as shown in the following example:

apiVersion: apps/v1
kind: Deployment
metadata:    
  labels:
    app: spring-boot-demo
  name: spring-boot-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: spring-boot-demo
  template:
    metadata:
      labels:
        app: spring-boot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: spring-boot-demo
    spec:
      hostAliases:
      # Replace this IP address with the IP address of NGINX.
      - ip: "192.168.172.171" 
        hostnames:
        - "arms-service"
        - "arms-metrics"
        - "arms-meta"
        - "arms-acm"
        # Replace cn-shenzhen in the domain name with the ID of the region that you connect to.
        - "arms-profiling-cn-shenzhen.arms-service"
      containers:
        - env:
            # Point the agent configuration to the new modified configuration file.
            - name: ARMS_CONFIG_FILE
              value: /home/admin/.opt/ArmsAgent/arms-agent-proxy-mode.config
          image: >-
            registry.cn-hangzhou.aliyuncs.com/ahas_apsara_adp/spring-boot-demo:wt-test
          imagePullPolicy: Always
          name: spring-boot-demo
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            limits:
              cpu: 500m
              memory: 1Gi
            requests:
              cpu: 250m
              memory: 512Mi
          volumeMounts:
            # Mount it to the agent directory as the new configuration file.
            - mountPath: /home/admin/.opt/ArmsAgent/
              name: arms-agent-proxy-mode
      imagePullSecrets:
        - name: wt-test
      volumes:
        # Map the configMap to a volume named arms-agent-proxy-mode.
        - configMap:
            name: arms-agent-proxy-mode.config
          name: arms-agent-proxy-mode

Note

In the preceding YAML file, the commented parts are the content that you need to check and modify.

Verify the connection

Restart your application and wait about 2 minutes. If your application appears on the Application Monitoring > Application List page of the ARMS console and reports data, the connection is successful.