-
Notifications
You must be signed in to change notification settings - Fork 4.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add a 'Getting Started' section to README #99
Conversation
First paragraphs need some rework, explain responses so people understand what
|
Thanks |
|
Note to self: example of what |
New version then, a little bit verbose: diff between first proposed version and this one Copy-paste: Getting startedKong will look by default for a configuration file at cp /usr/local/lib/luarocks/rocks/kong/<kong_version>/conf/kong.yml /etc/kong/kong.yml Edit the configuration to let Kong access your Cassandra cluster. Let's start Kong: $ kong start This should have run the migrations to prepare your Cassandra keyspace, and you should see a success message if Kong has started. Kong listens on these ports:
Hello World: Proxying your first APILet's add mockbin as an API: $ curl -i -X POST \
--url http://localhost:8001/apis/ \
--data 'name=mockbin&target_url=http://mockbin.com/&public_dns=mockbin.com'
HTTP/1.1 201 Created We used the And query it through Kong, by using the $ curl -i -X GET \
--url http://localhost:8000/ \
--header 'Host: mockbin.com'
HTTP/1.1 200 OK Kong just forwareded our request to Accounts and pluginsOne of Kong's core principle is its extensibility through plugins, which allow you to add features to your APIs. Let's configure the headerauth plugin to add authentication to your API. 1. Enable the pluginMake sure it is in the plugins_available:
- headerauth This will make Kong load the plugin. If the plugin was not previously marked as available, restart Kong: $ kong restart Repeat this step for every node in your cluster. 2. Configure the plugin for an APITo enable this plugin on an API, retrieve the API
$ curl -i -X POST \
--url http://localhost:8001/plugins/ \
--data 'name=headerauth&api_id=<api_id>&value.header_names=apikey'
HTTP/1.1 201 Created
...
{
"api_id": "<api_id>",
"value": { "header_names":["apikey"], "hide_credentials":false },
"id": "<id>",
"enabled": true,
"name": "headerauth"
} Here, the plugin has been successfully created and enabled. If you make the same request against the mockbin API again: $ curl -i -X GET \
--url http://localhost:8000/ \
--header 'Host: mockbin.com'
HTTP/1.1 403 Forbidden
...
{ "message": "Your authentication credentials are invalid" } This request did not provide a header named To authenticate against your API, you now need to create an account associated with an application. An application links an account and a plugin, this way, an account can consume different APIs with different applications (and different keys). $ curl -i -X POST \
--url http://localhost:8001/accounts/
--data ''
HTTP/1.1 201 Created
# Make sure the given account_id matches the freshly created account
$ curl -i -X POST \
--url http://localhost:8001/applications/
--data 'public_key=123456&account_id=<account_id>'
HTTP/1.1 201 Created That application (which has $ curl -i -X GET \
--url http://localhost:8000/ \
--header 'Host: mockbin.com' \
--header 'apikey: 123456'
HTTP/1.1 200 OK Your user can now consume this API. To go further into mastering Kong and its plugins, refer to the complete documentation. |
The README could probably still contain the 1st part (adding an API and querying it) with a link to the website and the full Getting Started. Again, feel free to improve. |
The section "Accounts and plugins" is the most complicated and confusing because it doesn't mention applications in the header and starts off with enabling a plugin. How APIs, accounts, applications and plugins interact with each other could be better explained in this section. Actually I think it should be broken into three sections:
|
I find it weird that we have applications / accounts in the core if they are required for the auth plugins, maybe I'm not seeing the bigger picture use for them? Like will all plugins will have access to them and you can enable plugins on a per account or application basis? |
Yep, I was wondering wether or not I should use that order instead.
Valid point, to discuss in meeting |
- accounts -> consumers - headerauth -> keyauth - plugins -> plugins_configuration
docs: add a 'Getting Started' section to README
docs: add a 'Getting Started' section to README
* test(k8s-sidecar) make test setup more flexible to allow k8s sidecar injector to utilize this repository * pin dependencies
### Summary * Feature: Added support for https_sni [#49](Kong/lua-resty-healthcheck#49) (backport) * Fix: Use OpenResty API for mTLS [#99](Kong/lua-resty-healthcheck#99) (backport) Signed-off-by: Aapo Talvensaari <aapo.talvensaari@gmail.com>
### Summary * Feature: Added support for https_sni [#49](Kong/lua-resty-healthcheck#49) (backport) * Fix: Use OpenResty API for mTLS [#99](Kong/lua-resty-healthcheck#99) (backport) Signed-off-by: Aapo Talvensaari <aapo.talvensaari@gmail.com>
Add a "Getting Started" section to the README (could later be moved to getkong.org). It describes adding an API, querying it, adding a plugin (authentication), and re-querying the API.
Writing this raised some concerns:
@thefosk @montanaflynn @nijikokun @sinzone Feel free to comment or checkout and improve. Here is a copy-pasta:
Getting started
Kong will look by default for a configuration file at
/etc/kong/kong.yml
. Make sure to copy the providedkong.yml
there and edit it to let Kong access your Cassandra cluster.Let's start Kong:
This should have run the migrations to prepare your Cassandra keyspace, and you should see a success message if Kong has started.
Kong listens on these ports:
:8000
: requests proxying:8001
: Kong's configuration API by which you can add APIs and accountsHello World: Proxying your first API
Let's add mockbin as an API:
$ curl -i -X POST \ --url http://localhost:8001/apis/ \ --data 'name=mockbin&target_url=http://mockbin.com/&public_dns=mockbin.com' HTTP/1.1 201 Created ...
And query it through Kong:
$ curl -i -X GET \ --url http://localhost:8000/ \ --header 'Host: mockbin.com' HTTP/1.1 200 OK ...
Accounts and plugins
One of Kong's core principle is its extensibility through plugins, which allow you to add features to your APIs.
Let's configure the headerauth plugin to add authentication to your API. Make sure it is in the
plugins_available
property of your configuration.If we make the same request again:
To authenticate against your API, you now need to create an account associated with an application. An application links an account and an API.
That application (which has "123456" as an API key) can now consume authenticated APIs such as the previously configured mockbin:
To go further into mastering Kong, refer to the complete documentation.