feat(conf) allow user-specified OpenResty install path (#8412)

Kong detects and decides which nginx binary to use by searching a couple
hard-coded paths:

* /usr/local/openresty/nginx/sbin
* /opt/openresty/nginx/sbin

...before finally exec-ing out to check PATH for a found nginx
executable. Therefore, if OpenResty is installed at one of the
hard-coded paths, it is always used, leaving the operator no means of
specifying any alternative. In most workflows, this is not a problem at
all, but during local development and testing it can be limiting.

Changing the behavior to search PATH first is one possible way of
addressing this, but it is backwards-incompatible in ways that will
likely cause headaches for operators, developers, package maintainers,
and CI pipeline owners. Therefore, this development
quality-of-life-inspired change introduces a new config option
(`openresty_path`) that short-circuits the aforementioned behavior.
When this value is set, Kong uses it exclusively for locating the nginx
binary.

Using `openresty_path` instead of something like `nginx_bin` allows us
to expand its usage later on (i.e. potentially having a cascading effect
on LUA_PATH/LUA_CPATH).

kong.conf.default

@@ -1544,3 +1544,14 @@
                                      # **Warning**: Certain variables, when made
                                      # available, may create opportunities to
                                      # escape the sandbox.
+
+#openresty_path =                 # Path to the OpenResty installation that Kong
+                                  # will use. When this is empty (the default),
+                                  # Kong determines the OpenResty installation
+                                  # by searching for a system-installed OpenResty
+                                  # and falling back to searching $PATH for the
+                                  # nginx binary.
+                                  #
+                                  # Setting this attribute disables the search
+                                  # behavior and explicitly instructs Kong which
+                                  # OpenResty installation to use.

kong/cmd/utils/nginx_signals.lua

@@ -13,6 +13,7 @@ local nginx_search_paths = {
   "/opt/openresty/nginx/sbin",
   ""
 }
+
 local nginx_version_pattern = "^nginx.-openresty.-([%d%.]+)"
 local nginx_compatible = version.set(unpack(meta._DEPENDENCIES.nginx))
 
@@ -50,11 +51,19 @@ end
 
 local _M = {}
 
-function _M.find_nginx_bin()
+function _M.find_nginx_bin(kong_conf)
   log.debug("searching for OpenResty 'nginx' executable")
 
+  local search_paths = nginx_search_paths
+  if kong_conf and kong_conf.openresty_path then
+    log.debug("using custom OpenResty path: %s", kong_conf.openresty_path)
+    search_paths = {
+      pl_path.join(kong_conf.openresty_path, "nginx", "sbin"),
+    }
+  end
+
   local found
-  for _, path in ipairs(nginx_search_paths) do
+  for _, path in ipairs(search_paths) do
     local path_to_check = pl_path.join(path, nginx_bin_name)
     if is_openresty(path_to_check) then
       if path_to_check == "nginx" then
@@ -83,7 +92,7 @@ function _M.find_nginx_bin()
 end
 
 function _M.start(kong_conf)
-  local nginx_bin, err = _M.find_nginx_bin()
+  local nginx_bin, err = _M.find_nginx_bin(kong_conf)
   if not nginx_bin then
     return nil, err
   end
@@ -120,7 +129,7 @@ function _M.start(kong_conf)
 end
 
 function _M.check_conf(kong_conf)
-  local nginx_bin, err = _M.find_nginx_bin()
+  local nginx_bin, err = _M.find_nginx_bin(kong_conf)
   if not nginx_bin then
     return nil, err
   end
@@ -152,7 +161,7 @@ function _M.reload(kong_conf)
     return nil, "nginx not running in prefix: " .. kong_conf.prefix
   end
 
-  local nginx_bin, err = _M.find_nginx_bin()
+  local nginx_bin, err = _M.find_nginx_bin(kong_conf)
   if not nginx_bin then
     return nil, err
   end

kong/templates/kong_defaults.lua

@@ -178,4 +178,6 @@ pluginserver_names = NONE
 untrusted_lua = sandbox
 untrusted_lua_sandbox_requires =
 untrusted_lua_sandbox_environment =
+
+openresty_path =
 ]]

spec/02-integration/02-cmd/15-utils_spec.lua

@@ -0,0 +1,75 @@
+local signals = require "kong.cmd.utils.nginx_signals"
+local pl_path = require "pl.path"
+local pl_file = require "pl.file"
+local pl_dir = require "pl.dir"
+
+describe("kong cli utils", function()
+
+  describe("nginx_signals", function()
+
+    describe("find_nginx_bin()", function()
+      local tmpdir
+      before_each(function()
+        tmpdir = pl_path.tmpname()
+        assert(os.remove(tmpdir))
+      end)
+
+      after_each(function()
+        pcall(pl_dir.rmtree, tmpdir)
+      end)
+
+      local function fake_nginx_binary(version)
+        local bin_dir = pl_path.join(tmpdir, "nginx/sbin")
+        pl_dir.makepath(bin_dir)
+
+        local nginx = pl_path.join(bin_dir, "nginx")
+        pl_file.write(nginx, string.format(
+          [[#!/bin/sh
+echo 'nginx version: openresty/%s' >&2]], version
+        ))
+
+        assert(os.execute("chmod +x " .. nginx))
+
+        return nginx
+      end
+
+
+      it("works with empty/unset input", function()
+        local bin, err = signals.find_nginx_bin()
+        assert.is_nil(err)
+        assert.matches("sbin/nginx", bin)
+        assert.truthy(pl_path.exists(bin))
+      end)
+
+      it("works when openresty_path is unset", function()
+        local bin, err = signals.find_nginx_bin({})
+        assert.is_nil(err)
+        assert.matches("sbin/nginx", bin)
+        assert.truthy(pl_path.exists(bin))
+      end)
+
+      it("prefers `openresty_path` when supplied", function()
+        local meta = require "kong.meta"
+        local version = meta._DEPENDENCIES.nginx[1]
+
+        local nginx = fake_nginx_binary(version)
+
+        local bin, err = signals.find_nginx_bin({ openresty_path = tmpdir })
+
+        assert.is_nil(err)
+        assert.equals(nginx, bin)
+      end)
+
+      it("returns nil+error if a compatible nginx bin is not found in `openresty_path`", function()
+        fake_nginx_binary("1.0.1")
+        local bin, err = signals.find_nginx_bin({ openresty_path = tmpdir })
+        assert.is_nil(bin)
+        assert.not_nil(err)
+        assert.matches("could not find OpenResty", err)
+      end)
+
+    end)
+
+  end)
+
+end)