Feature/registry docs (#127)

* Prepare documention for Terraform Registry. Fixes #115

* Improve hcl example

* Fix upstream resource doc

* Remove old docs location

* Fix formatting

* updating registry docs

* starting to update docs

* udating docs

* updating docs

Co-authored-by: Andy Lo-A-Foe <[email protected]>

docs/index.md

@@ -0,0 +1,38 @@
+Terraform Provider Kong
+=======================
+The Kong Terraform Provider tested against real Kong (using Docker)!
+
+Terraform provider tested to work against Kong 2.X.
+
+Usage
+-----
+
+To configure the provider:
+```hcl
+provider "kong" {
+    kong_admin_uri = "http://localhost:8001"
+}
+```
+
+Optionally you can configure Username and Password for BasicAuth:
+```hcl
+provider "kong" {
+    kong_admin_uri  = "http://localhost:8001"
+    kong_admin_username = "youruser"
+    kong_admin_password = "yourpass"
+}
+```
+
+## Argument Reference
+
+In addition to generic provider arguments (e.g. alias and version), the following arguments are supported in the Kong provider block:
+
+* `kong_admin_uri` - (Required) The URI of the Kong admin API, can be sourced from the `KONG_ADMIN_ADDR` environment variable
+* `kong_admin_username` - (Optional) The username for the Kong admin API if set, can be sourced from the `KONG_ADMIN_USERNAME` environment variable
+* `kong_admin_password` - (Optional) The password for the Kong admin API if set, can be sourced from the `KONG_ADMIN_PASSWORD` environment variable
+* `tls_skip_verify` - (Optional) Whether to skip TLS certificate verification for the kong api when using https, can be sourced from the `TLS_SKIP_VERIFY` environment variable
+* `kong_api_key` - (Optional) API key used to secure the kong admin API, can be sourced from the `KONG_API_KEY` environment variable
+* `kong_admin_token` - (Optional) API key used to secure the kong admin API in the Enterprise Edition, can be sourced from the `KONG_ADMIN_TOKEN` environment variable
+* `kong_workspace` - (Optional) Workspace context (Enterprise Edition)
+* `strict_plugins_match` - (Optional) Should plugins `config_json` field strictly match plugin configuration                               
+

docs/resources/certificate.md

@@ -0,0 +1,27 @@
+# kong_certificate
+
+For more information on creating certificates in Kong [see their documentation](https://docs.konghq.com/gateway-oss/2.5.x/admin-api/#certificate-object)
+
+## Example Usage
+
+```hcl
+resource "kong_certificate" "certificate" {
+    certificate  = "public key --- 123 ----"
+    private_key  = "private key --- 456 ----"
+    snis         = ["foo.com", "bar.com"]
+}
+```
+
+## Argument Reference
+
+* `certificate` - (Required) should be the public key of your certificate it is mapped to the `Cert` parameter on the Kong API.
+* `private_key` - (Required) should be the private key of your certificate it is mapped to the `Key` parameter on the Kong API.
+* `snis` - (Optional) a list of SNIs (alternative hosts on the certificate), under the bonnet this will create an SNI object in kong
+
+## Import
+
+To import a certificate:
+
+```shell
+terraform import kong_certificate.<certifcate_identifier> <certificate_id>
+```

docs/resources/consumer.md

@@ -0,0 +1,25 @@
+# kong_consumer
+
+The consumer resource maps directly onto the json for creating a Consumer in Kong.  For more information on the parameters [see the Kong Consumer create documentation](https://docs.konghq.com/gateway-oss/2.5.x/admin-api/#consumer-object).
+
+## Example Usage
+
+```hcl
+resource "kong_consumer" "consumer" {
+    username  = "User1"
+    custom_id = "123"
+}
+```
+
+## Argument Reference
+
+* `username` - (Semi-optional) The username to use, you must set either the username or custom_id
+* `custom_id` - (Semi-optional) A custom id for the consumer, you must set either the username or custom_id
+
+## Import
+
+To import a consumer:
+
+```shell
+terraform import kong_consumer.<consumer_identifier> <consumer_id>
+```

docs/resources/consumer_acl.md

@@ -0,0 +1,33 @@
+# kong_consumer_acl
+
+Consumer ACL is a resource that allows you to configure the acl plugin for a consumer.
+
+## Example Usage
+
+```hcl
+resource "kong_consumer" "my_consumer" {
+	username  = "User1"
+	custom_id = "123"
+}
+
+resource "kong_plugin" "acl_plugin" {
+	name        = "acl"
+	config_json = <<EOT
+	{
+		"allow": ["group1", "group2"]
+	}
+EOT
+}
+
+resource "kong_consumer_acl" "consumer_acl" {
+	consumer_id    = "${kong_consumer.my_consumer.id}"
+	group          = "group2"
+	tags           = ["myTag", "otherTag"]
+}
+```
+
+## Argument Reference
+
+* `consumer_id` - (Required) the id of the consumer to be configured
+* `group` - (Required) the acl group
+* `tags` - (Optional) A list of strings associated with the consumer acl for grouping and filtering.

docs/resources/consumer_basic_auth.md

@@ -0,0 +1,30 @@
+# kong_consumer_basic_auth
+
+Consumer basic auth is a resource that allows you to configure the basic auth plugin for a consumer.
+
+## Example Usage
+
+```hcl
+resource "kong_consumer" "my_consumer" {
+  username  = "User1"
+  custom_id = "123"
+}
+
+resource "kong_plugin" "basic_auth_plugin" {
+  name        = "basic-auth"
+}
+
+resource "kong_consumer_basic_auth" "consumer_basic_auth" {
+  consumer_id    = "${kong_consumer.my_consumer.id}"
+  username       = "foo_updated"
+  password       = "bar_updated"
+  tags           = ["myTag", "anotherTag"]
+}
+```
+
+## Argument Reference
+
+* `consumer_id` - (Required) the id of the consumer to be configured with basic auth
+* `username` - (Required) username to be used for basic auth
+* `password` - (Required) password to be used for basic auth
+* `tags` - (Optional) A list of strings associated with the consumer basic auth for grouping and filtering.

docs/resources/consumer_jwt_auth.md

@@ -0,0 +1,37 @@
+# kong_consumer_jwt_auth
+
+Consumer jwt auth is a resource that allows you to configure the jwt auth plugin for a consumer.
+
+## Example Usage
+
+```hcl
+resource "kong_consumer" "my_consumer" {
+  username  = "User1"
+  custom_id = "123"
+}
+
+resource "kong_plugin" "jwt_plugin" {
+  name        = "jwt"
+  config_json = <<EOT
+	{
+		"claims_to_verify": ["exp"]
+	}
+EOT
+}
+
+resource "kong_consumer_jwt_auth" "consumer_jwt_config" {
+  consumer_id    = "${kong_consumer.my_consumer.id}"
+  algorithm      = "HS256"
+  key            = "my_key"
+  rsa_public_key = "foo"
+  secret         = "my_secret"
+}
+```
+
+## Argument Reference
+
+* `consumer_id` - (Required) the id of the consumer to be configured with jwt auth
+* `algorithm` - (Optional) The algorithm used to verify the token’s signature. Can be HS256, HS384, HS512, RS256, or ES256, Default is `HS256`.
+* `key` - (Optional) A unique string identifying the credential. If left out, it will be auto-generated.
+* `rsa_public_key` - (Optional) If algorithm is `RS256` or `ES256`, the public key (in PEM format) to use to verify the token’s signature.
+* `secret` - (Optional) If algorithm is `HS256` or `ES256`, the secret used to sign JWTs for this credential. If left out, will be auto-generated.

docs/resources/plugin.md

@@ -0,0 +1,98 @@
+# kong_plugin
+
+The plugin resource maps directly onto the json for the API endpoint in Kong.  For more information on the parameters [see the Kong Api create documentation](https://docs.konghq.com/gateway-oss/2.5.x/admin-api/#plugin-object).
+The `config_json` is passed through to the plugin to configure it as is.  
+
+## Example Usage
+
+```hcl
+resource "kong_plugin" "rate_limit" {
+  name = "rate-limiting"
+  config_json = <<EOT
+	{
+		"second": 5,
+		"hour" : 1000
+	}
+EOT
+}
+```
+To apply a plugin to a consumer use the `consumer_id` property, for example:
+
+```hcl
+resource "kong_consumer" "plugin_consumer" {
+	username  = "PluginUser"
+	custom_id = "567"
+}
+
+resource "kong_plugin" "rate_limit" {
+	name        = "rate-limiting"
+	consumer_id = "${kong_consumer.plugin_consumer.id}"
+	config_json = <<EOT
+	{
+		"second": 5,
+		"hour" : 1000
+	}
+EOT
+}
+```
+
+To apply a plugin to a service use the `service_id` property, for example:
+
+```hcl
+resource "kong_service" "service" {
+	name     = "test"
+	protocol = "http"
+	host     = "test.org"
+}
+
+resource "kong_plugin" "rate_limit" {
+	name        = "rate-limiting"
+	service_id = "${kong_service.service.id}"
+	config_json = <<EOT
+	{
+		"second": 10,
+		"hour" : 2000
+	}
+EOT
+}
+```
+
+To apply a plugin to a route use the `route_id` property, for example:
+
+```hcl
+resource "kong_service" "service" {
+	name     = "test"
+	protocol = "http"
+	host     = "test.org"
+}
+
+resource "kong_plugin" "rate_limit" {
+	name        = "rate-limiting"
+	enabled     = true
+	service_id = "${kong_service.service.id}"
+	config_json = <<EOT
+	{
+		"second": 11,
+		"hour" : 4000
+	}
+EOT
+}
+```
+
+## Argument reference
+
+`plugin_name` - (Required) the name of the plugin you want to configure
+`consumer_id` - (Optional) the consumer id you want to configure the plugin for
+`service_id`  - (Optional) the service id that you want to configure the plugin for
+`route_id` - (Optional) the route id that you want to configure the plugin for
+`enabled` - (Optional) whether the plugin is enabled or not, use if you want to keep the plugin installed but disable it
+`config_json` - (Optional) this is the configuration json for how you want to configure the plugin.  The json is passed straight through to kong as is.  You can get the json config from the Kong documentation
+page of the plugin you are configuring
+
+## Import
+
+To import a plugin:
+
+```shell
+terraform import kong_plugin.<plugin_identifier> <plugin_id>
+```

docs/resources/route.md

@@ -0,0 +1,76 @@
+# kong_route
+
+The route resource maps directly onto the json for the route endpoint in Kong. For more information on the parameters [see the Kong Route create documentation](https://docs.konghq.com/gateway-oss/2.5.x/admin-api/#route-object).
+
+To create a tcp/tls route you set `sources` and `destinations` by repeating the corresponding element (`source` or `destination`) for each source or destination you want.
+
+## Example Usage
+
+```hcl
+resource "kong_route" "route" {
+    name            = "MyRoute"
+	protocols 	    = [ "http", "https" ]
+	methods 	    = [ "GET", "POST" ]
+	hosts 		    = [ "example2.com" ]
+	paths 		    = [ "/test" ]
+	strip_path 	    = false
+	preserve_host 	= true
+	regex_priority 	= 1
+	service_id 	     = kong_service.service.id
+}
+
+```
+
+To create a tcp/tls route you set `sources` and `destinations` by repeating the corresponding element (`source` or `destination`) for each source or destination you want, for example:
+
+```hcl
+
+resource "kong_route" "route" {
+	protocols 		= [ "tcp" ]
+	strip_path 		= true
+	preserve_host 	= false
+	source {
+		ip   = "192.168.1.1"
+		port = 80
+	}
+	source {
+		ip   = "192.168.1.2"
+	}
+	destination {
+		ip   = "172.10.1.1"
+		port = 81
+	}
+	snis		= ["foo.com"]
+	service_id  = kong_service.service.id
+}
+```
+
+## Argument Reference
+
+* `name` - (Optional) The name of the route
+* `protocols` - (Required) The list of protocols to use
+* `methods` - (Optional) A list of HTTP methods that match this Route
+* `hosts` - (Optional) A list of domain names that match this Route  
+* `paths` - (Optional) A list of paths that match this Route
+* `headers` - (Optional) One or more lists of values indexed by header name that will cause this Route to match if present in the request. The Host header cannot be used with this attribute: hosts should be specified using the hosts attribute.
+* `https_redirect_status_code` - (Optional) The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is HTTP instead of HTTPS. Location header is injected by Kong if the field is set to `301`, `302`, `307` or `308`. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`.  
+* `strip_path` - (Optional) When matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Default: true.
+* `regex_priority` - (Optional) A number used to choose which route resolves a given request when several routes match it using regexes simultaneously.
+* `path_handling` - (Optional) Controls how the Service path, Route path and requested path are combined when sending a request to the upstream.
+* `preserve_host` - (Optional) When matching a Route via one of the hosts domain names, use the request Host header in the upstream request headers. If set to false, the upstream Host header will be that of the Service’s host.
+* `request_buffering` - (Optional) Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true.
+* `response_buffering` - (Optional) Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: true.  
+* `source` - (Required) A list of source `ip` and `port`
+* `destination` - (Required) A list of destination `ip` and `port`
+* `snis` - (Optional) A list of SNIs that match this Route when using stream routing.
+* `service_id` - (Required) Service ID to map to
+* `tags` - (Optional) A list of strings associated with the Route for grouping and filtering.
+
+
+## Import
+
+To import a route:
+
+```shell
+terraform import kong_route.<route_identifier> <route_id>
+```