Merge pull request #518 from Mashape/renamings

[chore] Renamings

CHANGELOG.md

@@ -4,12 +4,14 @@ This release contains breaking changes.
 
 ### Breaking changes
 
-Several breaking changes are introduced. You will have to slightly change your configuration file and a migration script will take care of updating your database cluster. Please follow the instructions in [UPDATE.md](/UPDATE.md#update-to-kong-050).
+Several breaking changes are introduced. You will have to slightly change your configuration file and a migration script will take care of updating your database cluster. **Please follow the instructions in [UPDATE.md](/UPDATE.md#update-to-kong-050) for an update without downtime**.
 
 - Many plugins were renamed due to new naming conventions for consistency. [#480](https://github.com/Mashape/kong/issues/480)
-- The database schema has been updated to be future proof and handle the separation of plugins outside of the core repository.
-
-The Key authentication and Basic authentication plugins routes have changed:
+- In the configuration file, the Cassandra `hosts` property was renamed to `contact_points`. [#513](https://github.com/Mashape/kong/issues/513)
+- `public_dns` and `target_url` properties of APIs were respectively renamed to `inbound_dns` and `upstream_url`. [#513](https://github.com/Mashape/kong/issues/513)
+- `plugins_configurations` have been renamed to `plugins`, and their `value` property has been renamed to `config` to avoid confusions. [#513](https://github.com/Mashape/kong/issues/513)
+- The database schema has been updated to handle the separation of plugins outside of the core repository.
+- The Key authentication and Basic authentication plugins routes have changed:
 
 ```
 Old route                             New route
@@ -21,6 +23,10 @@ Old route                             New route
 
 The old routes are still maintained but will be removed in upcoming versions. Consider them **deprecated**.
 
+- Admin API:
+  - The route to retrieve enabled plugins is now under `/plugins/enabled`.
+  - The route to retrieve a plugin's configuration schema is now under `/plugins/schema/{plugin name}`.
+
 #### Added
 
 - Plugins migrations. Each plugin can now have its own migration scripts if it needs to store data in your cluster. This is a step forward to improve Kong's pluggable architecture. [#443](https://github.com/Mashape/kong/pull/443)

UPDATE.md

@@ -2,38 +2,13 @@ This document describes eventual additional steps that might be required to upda
 
 ## Update to Kong `0.5.0`
 
-It is important that you be running Kong `0.4.2` and have the latest release of Python 2.7 on your system when executing those steps.
+Migrating to 0.5.0 can be done **without downtime** by following those instructions. It is important that you be running Kong `0.4.2` and have the latest release of Python 2.7 on your system when executing those steps.
 
-Several changes were introduced in this version: many plugins were renamed and the database schema slightly changed to introduce "plugins migrations". Now, each plugin can have its own migration if it needs to store data in your cluster. This is not a regular migration since the schema of the table handling the migrations itself changed.
+> Several changes were introduced in this version: some plugins and properties were renamed and the database schema slightly changed to introduce "plugins migrations". Now, each plugin can have its own migration if it needs to store data in your cluster. This is not a regular migration since the schema of the table handling the migrations itself changed.
 
-##### 1. Migration script
+##### 1. Configuration file
 
-[This Python script](/scripts/migration.py) will take care of migrating your database schema should you execute the following instructions:
-
-```shell
-# First, make sure you are already running Kong 0.4.2
-
-# Clone the Kong git repository if you don't already have it:
-$ git clone [email protected]:Mashape/kong.git
-
-# Go to the 'scripts/' folder:
-$ cd kong/scripts
-
-# Install the Python script dependencies:
-$ pip install cassandra-driver pyyaml
-
-# The script will use your first contact point (the first of the 'hosts' property)
-# so make sure it is valid and has the format 'host:port'.
-
-# Execute the migration script:
-$ python migration.py -c /path/to/kong/config
-
-# If everything went well the script should print a success message.
-```
-
-##### 2. Configuration file
-
-You will now need to update your configuration file. Replace the `plugins_available` property with:
+You will need to update your configuration file. Replace the `plugins_available` values with:
 
 ```yaml
 plugins_available:
@@ -57,6 +32,43 @@ plugins_available:
 
 You can still remove plugins you don't use for a lighter Kong.
 
+Also replace the Cassandra `hosts` property with `contact_points`:
+
+```yaml
+properties:
+  contact_points:
+    - "..."
+    - "..."
+  timeout: 1000
+  keyspace: kong
+  keepalive: 60000
+```
+
+##### 2. Migration script
+
+[This Python script](/scripts/migration.py) will take care of migrating your database schema should you execute the following instructions:
+
+```shell
+# First, make sure you are already running Kong 0.4.2
+
+# Clone the Kong git repository if you don't already have it:
+$ git clone [email protected]:Mashape/kong.git
+
+# Go to the 'scripts/' folder:
+$ cd kong/scripts
+
+# Install the Python script dependencies:
+$ pip install cassandra-driver pyyaml
+
+# The script will use the first Cassandra contact point in your Kong configuration file
+# (the first of the 'contact_points' property) so make sure it is valid and has the format 'host:port'.
+
+# Run the migration script:
+$ python migration.py -c /path/to/kong/config
+```
+
+If everything went well the script should print a success message.
+
 ##### 3. Upgrade without downtime
 
 You can now update Kong to 0.5.0. Proceed as a regular update and install the package of your choice from the website. After updating, reload Kong to avoid downtime:
@@ -65,11 +77,23 @@ You can now update Kong to 0.5.0. Proceed as a regular update and install the pa
 $ kong reload
 ```
 
-Your cluster should successfully be migrated to Kong `0.5.0`.
+##### 4. Purge your Cassandra cluster
+
+Finally, once Kong has restarted in 0.5.0, run the migration script again, with the `--purge` flag:
+
+```shell
+$ python migration.py -c /path/to/kong/config --purge
+```
+
+Your cluster is now fully migrated to `0.5.0`.
+
+##### Other changes to acknowledge
 
-##### Other changes
+Some entities and properties were renamed to avoid confusion:
 
-The Key authentication and Basic authentication plugins routes have changed:
+- `public_dns` and `target_url` properties of APIs were respectively renamed to `inbound_dns` and `upstream_url`.
+- `plugins_configurations` have been renamed to `plugins`, and their `value` property has been renamed to `config` to avoid confusions.
+- The Key authentication and Basic authentication plugins routes have changed:
 
 ```
 Old route                             New route
@@ -81,6 +105,10 @@ Old route                             New route
 
 The old routes are still maintained but will be removed in upcoming versions. Consider them **deprecated**.
 
+- Admin API:
+  - The route to retrieve enabled plugins is now under `/plugins/enabled`.
+  - The route to retrieve a plugin's configuration schema is now under `/plugins/schema/{plugin name}`.
+
 ## Update to Kong `0.4.2`
 
 The configuration format for specifying the port of your Cassandra instance changed. Replace:

kong-0.4.2-1.rockspec

@@ -84,14 +84,14 @@ build = {
     ["kong.dao.schemas_validation"] = "kong/dao/schemas_validation.lua",
     ["kong.dao.schemas.apis"] = "kong/dao/schemas/apis.lua",
     ["kong.dao.schemas.consumers"] = "kong/dao/schemas/consumers.lua",
-    ["kong.dao.schemas.plugins_configurations"] = "kong/dao/schemas/plugins_configurations.lua",
+    ["kong.dao.schemas.plugins"] = "kong/dao/schemas/plugins.lua",
     ["kong.dao.cassandra.factory"] = "kong/dao/cassandra/factory.lua",
     ["kong.dao.cassandra.query_builder"] = "kong/dao/cassandra/query_builder.lua",
     ["kong.dao.cassandra.base_dao"] = "kong/dao/cassandra/base_dao.lua",
     ["kong.dao.cassandra.migrations"] = "kong/dao/cassandra/migrations.lua",
     ["kong.dao.cassandra.apis"] = "kong/dao/cassandra/apis.lua",
     ["kong.dao.cassandra.consumers"] = "kong/dao/cassandra/consumers.lua",
-    ["kong.dao.cassandra.plugins_configurations"] = "kong/dao/cassandra/plugins_configurations.lua",
+    ["kong.dao.cassandra.plugins"] = "kong/dao/cassandra/plugins.lua",
 
     ["kong.plugins.base_plugin"] = "kong/plugins/base_plugin.lua",
 
@@ -189,7 +189,7 @@ build = {
     ["kong.api.routes.apis"] = "kong/api/routes/apis.lua",
     ["kong.api.routes.consumers"] = "kong/api/routes/consumers.lua",
     ["kong.api.routes.plugins"] = "kong/api/routes/plugins.lua",
-    ["kong.api.routes.plugins_configurations"] = "kong/api/routes/plugins_configurations.lua",
+    ["kong.api.routes.plugins"] = "kong/api/routes/plugins.lua",
   },
   install = {
     conf = { "kong.yml" },

kong.yml

@@ -36,7 +36,7 @@ database: cassandra
 databases_available:
   cassandra:
     properties:
-      hosts:
+      contact_points:
         - "localhost:9042"
       timeout: 1000
       keyspace: kong

kong/api/app.lua

@@ -140,7 +140,7 @@ local function attach_routes(routes)
 end
 
 -- Load core routes
-for _, v in ipairs({"kong", "apis", "consumers", "plugins", "plugins_configurations"}) do
+for _, v in ipairs({"kong", "apis", "consumers", "plugins"}) do
   local routes = require("kong.api.routes."..v)
   attach_routes(routes)
 end

kong/api/routes/apis.lua

@@ -40,11 +40,11 @@ return {
     end,
 
     GET = function(self, dao_factory)
-      crud.paginated_set(self, dao_factory.plugins_configurations)
+      crud.paginated_set(self, dao_factory.plugins)
     end,
 
     POST = function(self, dao_factory, helpers)
-      crud.post(self.params, dao_factory.plugins_configurations, function(data)
+      crud.post(self.params, dao_factory.plugins, function(data)
         if configuration.send_anonymous_reports then
           data.signal = constants.SYSLOG.API
           syslog.log(syslog.format_entity(data))
@@ -53,7 +53,7 @@ return {
     end,
 
     PUT = function(self, dao_factory, helpers)
-      crud.put(self.params, dao_factory.plugins_configurations)
+      crud.put(self.params, dao_factory.plugins)
     end
   },
 
@@ -68,7 +68,7 @@ return {
       }
       self.params.plugin_id = nil
 
-      local data, err = dao_factory.plugins_configurations:find_by_keys(fetch_keys)
+      local data, err = dao_factory.plugins:find_by_keys(fetch_keys)
       if err then
         return helpers.yield_error(err)
       end
@@ -84,11 +84,11 @@ return {
     end,
 
     PATCH = function(self, dao_factory, helpers)
-      crud.patch(self.params, self.plugin, dao_factory.plugins_configurations)
+      crud.patch(self.params, self.plugin, dao_factory.plugins)
     end,
 
     DELETE = function(self, dao_factory)
-      crud.delete(self.plugin, dao_factory.plugins_configurations)
+      crud.delete(self.plugin, dao_factory.plugins)
     end
   }
 }

kong/api/routes/kong.lua

@@ -4,7 +4,7 @@ local route_helpers = require "kong.api.route_helpers"
 return {
   ["/"] = {
     GET = function(self, dao, helpers)
-      local db_plugins, err = dao.plugins_configurations:find_distinct()
+      local db_plugins, err = dao.plugins:find_distinct()
       if err then
         return helpers.responses.send_HTTP_INTERNAL_SERVER_ERROR(err)
       end

kong/api/routes/plugins.lua

@@ -1,4 +1,7 @@
+local crud = require "kong.api.crud_helpers"
 local utils = require "kong.tools.utils"
+local syslog = require "kong.tools.syslog"
+local constants = require "kong.constants"
 
 -- Remove functions from a schema definition so that
 -- cjson can encode the schema.
@@ -15,13 +18,27 @@ end
 
 return {
   ["/plugins"] = {
-    GET = function(self, dao_factory, helpers)
-      return helpers.responses.send_HTTP_OK {
-        enabled_plugins = configuration.plugins_available
-      }
+    GET = function(self, dao_factory)
+      crud.paginated_set(self, dao_factory.plugins)
+    end,
+
+    PUT = function(self, dao_factory)
+      crud.put(self.params, dao_factory.plugins)
+    end,
+
+    POST = function(self, dao_factory)
+      crud.post(self.params, dao_factory.plugins, function(data)
+        if configuration.send_anonymous_reports then
+          data.signal = constants.SYSLOG.API
+          syslog.log(syslog.format_entity(data))
+        end
+      end)
     end
   },
-  ["/plugins/:name/schema"] = {
+
+
+
+  ["/plugins/schema/:name"] = {
     GET = function(self, dao_factory, helpers)
       local ok, plugin_schema = utils.load_module_if_exists("kong.plugins."..self.params.name..".schema")
       if not ok then
@@ -32,5 +49,35 @@ return {
 
       return helpers.responses.send_HTTP_OK(plugin_schema)
     end
-  }
+  },
+
+  ["/plugins/:id"] = {
+    before = function(self, dao_factory, helpers)
+      local err
+      self.plugin_conf, err = dao_factory.plugins:find_by_primary_key({ id = self.params.id })
+      if err then
+        return helpers.yield_error(err)
+      elseif not self.plugin_conf then
+        return helpers.responses.send_HTTP_NOT_FOUND()
+      end
+    end,
+
+    GET = function(self, dao_factory, helpers)
+      return helpers.responses.send_HTTP_OK(self.plugin_conf)
+    end,
+
+    PATCH = function(self, dao_factory)
+      crud.patch(self.params, self.plugin_conf, dao_factory.plugins)
+    end,
+
+    DELETE = function(self, dao_factory)
+      crud.delete(self.plugin_conf, dao_factory.plugins)
+    end
+  },  ["/plugins/enabled"] = {
+    GET = function(self, dao_factory, helpers)
+      return helpers.responses.send_HTTP_OK {
+        enabled_plugins = configuration.plugins_available
+      }
+    end
+  },
 }