Integrate SkyWalking Monitoring into Nginx Ingress on Kubernetes

Premise: an available Kubernetes cluster and SkyWalking monitoring.

Software versions

Kubernetes 1.17.2

nginx-ingress-controller 0.34.1

SkyWalking 8.1.0

skywalking-nginx-lua 0.2.0

Step 1: Download skywalking-nginx-lua

<code>git clone https://github.com/apache/skywalking-nginx-lua.git</code>

Step 2: Rename conflicting Lua script

Rename

util.lua

to avoid conflict with the default Nginx‑Ingress Lua script.

<code>$ cd skywalking-nginx-lua/lib/skywalking
# Rename file
mv util.lua swutil.lua
# Find and replace references
grep util `find . -type f`
# Update all require statements from 'util' to 'swutil'
</code>

Step 3: Modify the nginx‑ingress template (nginx.tmpl)

Add SkyWalking Lua script search path.

Read environment variables: SW_SERVICE_NAME, SW_SERVICE_INSTANCE_NAME, SW_BACKEND_SERVERS.

Add a shared memory zone

tracing_buffer

for tracing.

Initialize the SkyWalking Lua agent and extract configuration from environment variables.

Configure HTTP tracing settings.

<code># SkyWalking ENV
env SW_SERVICE_NAME;
env SW_SERVICE_INSTANCE_NAME;
env SW_BACKEND_SERVERS;

events {
    multi_accept {{ if $cfg.EnableMultiAccept }}on{{ else }}off{{ end }};
    worker_connections {{ $cfg.MaxWorkerConnections }};
    use epoll;
}

http {
    # Load Lua scripts
    lua_package_path "/etc/nginx/lua/?.lua;/etc/nginx/lua/skywalking/?.lua;;";
    # Shared memory for tracing
    lua_shared_dict tracing_buffer 100m;

    init_by_lua_block {
        collectgarbage("collect")
        -- load required modules
        local ok, res = pcall(require, "lua_ingress")
        if not ok then error("require failed: " .. tostring(res)) end
        lua_ingress = res
        lua_ingress.set_config({{ configForLua $all }})
        -- other modules omitted for brevity
    }

    init_worker_by_lua_block {
        local metadata_buffer = ngx.shared.tracing_buffer
        metadata_buffer:set('serviceName', os.getenv("SW_SERVICE_NAME"))
        metadata_buffer:set('serviceInstanceName', os.getenv("SW_SERVICE_INSTANCE_NAME"))
        require("swutil").set_randomseed()
        require("client"):startBackendTimer(os.getenv("SW_BACKEND_SERVERS"))
    }

    rewrite_by_lua_block {
        lua_ingress.rewrite({{ locationConfigForLua $location $all }})
        balancer.rewrite()
        plugins.run()
        require("tracer"):start({{ buildUpstreamName $location | quote }})
    }

    body_filter_by_lua_block {
        if ngx.arg[2] then
            require("tracer"):finish()
        end
    }

    log_by_lua_block {
        balancer.log()
        {{ if $all.EnableMetrics }}
        monitor.call()
        {{ end }}
        plugins.run()
        require("tracer"):prepareForReport()
    }
}
</code>

Step 4: Build a custom Nginx‑Ingress Docker image

<code>FROM quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.32.0

ADD --chown=www-data nginx.tmpl /etc/nginx/template
ADD --chown=www-data skywalking /etc/nginx/lua/skywalking
</code>

Step 5: Build and push the image

<code>$ docker build -t registry.cn-hangzhou.aliyuncs.com/rookieops/ingress-nginx-controller-skywalking:0.34.1 .
$ docker push registry.cn-hangzhou.aliyuncs.com/rookieops/ingress-nginx-controller-skywalking:0.34.1
</code>

Step 6: Update the nginx‑ingress Deployment

<code>... 
containers:
  - name: controller
    image: registry.cn-hangzhou.aliyuncs.com/rookieops/nginx-ingress-controller:0.32.0
    imagePullPolicy: IfNotPresent
    env:
      - name: SW_SERVICE_NAME
        value: Kubernetes Ingress
      - name: SW_BACKEND_SERVERS
        value: http://skywalking-oap.skywalking.svc.cluster.local:12800
      - name: SW_SERVICE_INSTANCE_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.uid
... 
</code>

Step 7: Redeploy the ingress‑controller

After applying the updated Deployment, the SkyWalking UI will display tracing information for requests passing through the Nginx ingress.