{"id":23648245,"url":"https://github.com/amireh/kong_schema","last_synced_at":"2025-08-31T23:32:47.536Z","repository":{"id":56880415,"uuid":"103273320","full_name":"amireh/kong_schema","owner":"amireh","description":"Configure Kong using YAML or JSON.","archived":false,"fork":false,"pushed_at":"2018-11-12T18:05:53.000Z","size":39,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-25T20:03:24.342Z","etag":null,"topics":["configuration","json","kong","yaml"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amireh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-12T13:19:55.000Z","updated_at":"2019-06-27T08:26:05.000Z","dependencies_parsed_at":"2022-08-20T23:40:18.901Z","dependency_job_id":null,"html_url":"https://github.com/amireh/kong_schema","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amireh%2Fkong_schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amireh%2Fkong_schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amireh%2Fkong_schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amireh%2Fkong_schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amireh","download_url":"https://codeload.github.com/amireh/kong_schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231639031,"owners_count":18404266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","json","kong","yaml"],"created_at":"2024-12-28T14:52:34.921Z","updated_at":"2024-12-28T14:52:35.408Z","avatar_url":"https://github.com/amireh.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kong_schema\n\nConfigure [Kong](https://getkong.org) using YAML or JSON source files.\n\nThis package is intended for use by programmers in development environments and\nmay not be optimal for admins since it does not attempt to expose the full\npower of Kong's REST API.\n\nUse of this package requires no knowledge of [Kong's REST\nAPI](https://getkong.org/docs/0.11.x/admin-api/) - it is meant to abstract it\naway from the user.\n\n## Installation\n\nThe package requires a recent version of Ruby.\n\n```shell\ngem install kong_schema\n```\n\nIf you're using Bundler, add it to your Gemfile instead:\n\n```ruby\ngroup :development do\n  gem 'kong_schema'\nend\n```\n\n## Usage\n\nWrite your desired configuration for Kong in a file using either YAML or JSON.\nThe supported \"directives\" are described later in this document. Then you can\nuse the `kong_schema` binary to perform various actions.\n\nRun `kong_schema --help` to see the available commands.\n\n```shell\n# apply configuration\nkong_schema up [path/to/config.yml]\n\n# reset configuration\nkong_schema down [path/to/config.yml]\n```\n\n## Example\n\nLet's assume we have such a config file:\n\n```yaml\n# file: config/kong.yml\nkong:\n  admin_host: localhost:8001\n  apis:\n    - name: application-api\n      hosts:\n        - api.application.dev\n      preserve_host: true\n      strip_uri: false\n      upstream_url: http://application-api-lb\n      uris:\n        - /api/.+\n        - /auth/.+\n  upstreams:\n    - name: application-api-lb\n  targets:\n    - upstream_id: application-api-lb\n      target:      127.0.0.1:3000\n```\n\nThen if we run the following command:\n\n```shell\nkong_schema up config/kong.yml\n```\n\nkong_schema will read the directives (\"schema\") found in the `kong` dictionary\nand prompt you with a list of changes it will apply to Kong through the REST\nAPI.\n\n```shell\n+-----------------+------------------------------------------------+\n| Change          | Parameters                                     |\n+-----------------+------------------------------------------------+\n| Create Api      | {                                              |\n|                 |   \"name\": \"application-api\",                   |\n|                 |   \"hosts\": [                                   |\n|                 |     \"api.application.dev\"                      |\n|                 |   ],                                           |\n|                 |   \"upstream_url\": \"http://application-api-lb\", |\n|                 |   \"uris\": [                                    |\n|                 |     \"/api/.+\",                                 |\n|                 |     \"/auth/.+\"                                 |\n|                 |   ],                                           |\n|                 |   \"preserve_host\": true                        |\n|                 | }                                              |\n| Create Upstream | {                                              |\n|                 |   \"name\": \"application-api-lb\"                 |\n|                 | }                                              |\n| Create Target   | {                                              |\n|                 |   \"upstream_id\": \"application-api-lb\",         |\n|                 |   \"target\": \"127.0.0.1:3000\"                   |\n|                 | }                                              |\n+-----------------+------------------------------------------------+\nCommit the changes to Kong? (y/N) \n```\n\nIf you agree and everything goes well, you should see an affirmative message:\n\n```\n✓ Kong has been reconfigured!\n```\n\nRunning the command again should report that there are no changes to reflect:\n\n```\n✓ Nothing to update.\n```\n\nBut if you _do_ change something it will result in an \"update\" operation and present you with the changes it perceives to have been made.\n\nLet's add another `uri` to our API:\n\n```yaml\n# file: config/kong.yml\n# ...\n  apis:\n    - name: application-api\n      hosts:\n        - api.application.dev\n      upstream_url: http://application-api-lb\n      uris:\n        - /api/.+\n        - /auth/.+\n        - /oauth2/.+\n```\n\nAnd re-run `kong_schema up` as we did before:\n\n```shell\n+------------+-------------------------------------------------+\n| Change     | Parameters                                      |\n+------------+-------------------------------------------------+\n| Update Api |  {                                              |\n|            |    \"name\": \"application-api\",                   |\n|            |    \"hosts\": [                                   |\n|            |      \"api.application.dev\"                      |\n|            |    ],                                           |\n|            |    \"upstream_url\": \"http://application-api-lb\", |\n|            |    \"uris\": [                                    |\n|            |      \"/api/.+\",                                 |\n|            | -    \"/auth/.+\"                                 |\n|            | +    \"/auth/.+\",                                |\n|            | +    \"/oauth2/.+\"                               |\n|            |    ],                                           |\n|            |    \"preserve_host\": true                        |\n|            |  }                                              |\n+------------+-------------------------------------------------+\n```\n\nNice and easy!\n\n## Configuration\n\nAs mentioned before, you can either use YAML or JSON to write your\nconfiguration files. YAML tends to be more readable and easier to edit.\n`kong_schema` will know which parser to use based on the file extension; they\nhave to end with either `.yml` or `.json` respectively.\n\nFor further convenience, the CLIs support reading the schema from a specific\n\"key\" in that configuration file, which by default is set to `\"kong\"`. This\nallows you to keep your Kong schema alongside other configuration items for\nyour application(s) in a single file.\n\nIf your Kong schema is the root property, just pass `--key \"\"` to CLI commands\nto make them read the whole file as the schema.\n\n### `admin_host: String`\n\nAddress at which Kong Admin is listening, like `127.0.0.1:9712`. This is the\nvalue you specify in `admin_listen` of `kong.conf`.\n\n### `apis: Array\u003cKong::Api\u003e`\n\n[Kong::Api](https://getkong.org/docs/0.11.x/admin-api/#add-api) configuration.\n\n**Properties**\n\n- name: String\n- host: String\n- methods: Array\u003cString\u003e\n- preserve_host: Boolean\n- strip_uri: Boolean\n- upstream_url: String\n- uris: Array\u003cString\u003e\n\n### `plugins: Array\u003cKong::Plugin\u003e`\n\n[Kong::Plugin](https://getkong.org/docs/0.11.x/admin-api/#add-plugin) configuration.\n\nSetting `enabled: false` will delete the plugin.\n\n**Properties**\n\n- name: String\n- enabled: Boolean\n- api_id: String\n- config: Object\n- consumer_id: String\n\n### `upstreams: Array\u003cKong::Upstream\u003e`\n\n[Kong::Upstream](https://getkong.org/docs/0.11.x/admin-api/#add-upstream)\nconfiguration.\n\n**Properties**\n\n- name: String\n- slots: Number\n- orderlist: Array\u003cNumber\u003e\n\n### `targets: Array\u003cKong::Target\u003e`\n\n[Kong::Target](https://getkong.org/docs/0.11.x/admin-api/#add-target)\nconfiguration.\n\n**Properties**\n\n- upstream_id: String\n- target: String\n- weight: Number\n\n## TODO\n\nAdd support for the remaining Kong API objects:\n\n- [consumers](https://getkong.org/docs/0.11.x/admin-api/#create-consumer)\n- [certificates](https://getkong.org/docs/0.11.x/admin-api/#add-certificate)\n- [snis](https://getkong.org/docs/0.11.x/admin-api/#add-sni)\n\n## Gotchas\n\nBeware of removing keys that were previously defined in your configuration.\n`kong_schema` does not know the default values of options nor does it attempt\nto assign them, so when you omit an option that was previously defined, it can\nnot detect that change and it will not be reflected in the API.\n\nThis symptom may be addressed in the future by changing the implementation so\nthat it wipes out Kong's configuration before each application (e.g.\n`kong_schema up`) but for now you have two options to deal with this:\n\n1) Reset the database prior to applying the schema:\n\n```shell\nkong_schema down [file] # database reset\nkong_schema up [file]   # database now 100% reflecting config file\n```\n\n2) Set the values to `null` or an empty property. For example, if we were to no\n   longer use the `hosts` property of an Api object, we'd just clear it instead\n   of omitting it:\n\n```yaml\nkong:\n  apis:\n    - name: some-api\n      # just clear this, don't omit it\n      hosts:\n```\n\n## Tests\n\n**WARNING: RUNNING THE TESTS WILL CLEAR THE KONG DATABASE!!!**\n\nA running Kong instance is required to run the tests. By default the admin API\nis expected to be running on `127.0.0.1:9712` but you can change that by \nsetting the environment variable `KONG_URI`.\n\nThen running the tests is as simple as:\n\n    COVERAGE=1 bundle exec rspec\n\n## License\n\nCopyright (C) 2017 Instructure, INC.\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famireh%2Fkong_schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famireh%2Fkong_schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famireh%2Fkong_schema/lists"}