Skip to content

Commit f91a5a6

Browse files
kevholditchloafoe
kevholditch
and
loafoe
authored
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 <andy.loafoe@gmail.com>
1 parent f86940b commit f91a5a6

21 files changed

+558
-811
lines changed

‎README.md

Lines changed: 3 additions & 354 deletions
Large diffs are not rendered by default.

‎docs/index.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Terraform Provider Kong
2+
=======================
3+
The Kong Terraform Provider tested against real Kong (using Docker)!
4+
5+
Terraform provider tested to work against Kong 2.X.
6+
7+
Usage
8+
-----
9+
10+
To configure the provider:
11+
```hcl
12+
provider "kong" {
13+
kong_admin_uri = "http://localhost:8001"
14+
}
15+
```
16+
17+
Optionally you can configure Username and Password for BasicAuth:
18+
```hcl
19+
provider "kong" {
20+
kong_admin_uri = "http://localhost:8001"
21+
kong_admin_username = "youruser"
22+
kong_admin_password = "yourpass"
23+
}
24+
```
25+
26+
## Argument Reference
27+
28+
In addition to generic provider arguments (e.g. alias and version), the following arguments are supported in the Kong provider block:
29+
30+
* `kong_admin_uri` - (Required) The URI of the Kong admin API, can be sourced from the `KONG_ADMIN_ADDR` environment variable
31+
* `kong_admin_username` - (Optional) The username for the Kong admin API if set, can be sourced from the `KONG_ADMIN_USERNAME` environment variable
32+
* `kong_admin_password` - (Optional) The password for the Kong admin API if set, can be sourced from the `KONG_ADMIN_PASSWORD` environment variable
33+
* `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
34+
* `kong_api_key` - (Optional) API key used to secure the kong admin API, can be sourced from the `KONG_API_KEY` environment variable
35+
* `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
36+
* `kong_workspace` - (Optional) Workspace context (Enterprise Edition)
37+
* `strict_plugins_match` - (Optional) Should plugins `config_json` field strictly match plugin configuration
38+

‎docs/resources/certificate.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# kong_certificate
2+
3+
For more information on creating certificates in Kong [see their documentation](https://docs.konghq.com/gateway-oss/2.5.x/admin-api/#certificate-object)
4+
5+
## Example Usage
6+
7+
```hcl
8+
resource "kong_certificate" "certificate" {
9+
certificate = "public key --- 123 ----"
10+
private_key = "private key --- 456 ----"
11+
snis = ["foo.com", "bar.com"]
12+
}
13+
```
14+
15+
## Argument Reference
16+
17+
* `certificate` - (Required) should be the public key of your certificate it is mapped to the `Cert` parameter on the Kong API.
18+
* `private_key` - (Required) should be the private key of your certificate it is mapped to the `Key` parameter on the Kong API.
19+
* `snis` - (Optional) a list of SNIs (alternative hosts on the certificate), under the bonnet this will create an SNI object in kong
20+
21+
## Import
22+
23+
To import a certificate:
24+
25+
```shell
26+
terraform import kong_certificate.<certifcate_identifier> <certificate_id>
27+
```

‎docs/resources/consumer.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# kong_consumer
2+
3+
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).
4+
5+
## Example Usage
6+
7+
```hcl
8+
resource "kong_consumer" "consumer" {
9+
username = "User1"
10+
custom_id = "123"
11+
}
12+
```
13+
14+
## Argument Reference
15+
16+
* `username` - (Semi-optional) The username to use, you must set either the username or custom_id
17+
* `custom_id` - (Semi-optional) A custom id for the consumer, you must set either the username or custom_id
18+
19+
## Import
20+
21+
To import a consumer:
22+
23+
```shell
24+
terraform import kong_consumer.<consumer_identifier> <consumer_id>
25+
```

‎docs/resources/consumer_acl.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# kong_consumer_acl
2+
3+
Consumer ACL is a resource that allows you to configure the acl plugin for a consumer.
4+
5+
## Example Usage
6+
7+
```hcl
8+
resource "kong_consumer" "my_consumer" {
9+
username = "User1"
10+
custom_id = "123"
11+
}
12+
13+
resource "kong_plugin" "acl_plugin" {
14+
name = "acl"
15+
config_json = <<EOT
16+
{
17+
"allow": ["group1", "group2"]
18+
}
19+
EOT
20+
}
21+
22+
resource "kong_consumer_acl" "consumer_acl" {
23+
consumer_id = "${kong_consumer.my_consumer.id}"
24+
group = "group2"
25+
tags = ["myTag", "otherTag"]
26+
}
27+
```
28+
29+
## Argument Reference
30+
31+
* `consumer_id` - (Required) the id of the consumer to be configured
32+
* `group` - (Required) the acl group
33+
* `tags` - (Optional) A list of strings associated with the consumer acl for grouping and filtering.

‎docs/resources/consumer_basic_auth.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# kong_consumer_basic_auth
2+
3+
Consumer basic auth is a resource that allows you to configure the basic auth plugin for a consumer.
4+
5+
## Example Usage
6+
7+
```hcl
8+
resource "kong_consumer" "my_consumer" {
9+
username = "User1"
10+
custom_id = "123"
11+
}
12+
13+
resource "kong_plugin" "basic_auth_plugin" {
14+
name = "basic-auth"
15+
}
16+
17+
resource "kong_consumer_basic_auth" "consumer_basic_auth" {
18+
consumer_id = "${kong_consumer.my_consumer.id}"
19+
username = "foo_updated"
20+
password = "bar_updated"
21+
tags = ["myTag", "anotherTag"]
22+
}
23+
```
24+
25+
## Argument Reference
26+
27+
* `consumer_id` - (Required) the id of the consumer to be configured with basic auth
28+
* `username` - (Required) username to be used for basic auth
29+
* `password` - (Required) password to be used for basic auth
30+
* `tags` - (Optional) A list of strings associated with the consumer basic auth for grouping and filtering.

‎docs/resources/consumer_jwt_auth.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# kong_consumer_jwt_auth
2+
3+
Consumer jwt auth is a resource that allows you to configure the jwt auth plugin for a consumer.
4+
5+
## Example Usage
6+
7+
```hcl
8+
resource "kong_consumer" "my_consumer" {
9+
username = "User1"
10+
custom_id = "123"
11+
}
12+
13+
resource "kong_plugin" "jwt_plugin" {
14+
name = "jwt"
15+
config_json = <<EOT
16+
{
17+
"claims_to_verify": ["exp"]
18+
}
19+
EOT
20+
}
21+
22+
resource "kong_consumer_jwt_auth" "consumer_jwt_config" {
23+
consumer_id = "${kong_consumer.my_consumer.id}"
24+
algorithm = "HS256"
25+
key = "my_key"
26+
rsa_public_key = "foo"
27+
secret = "my_secret"
28+
}
29+
```
30+
31+
## Argument Reference
32+
33+
* `consumer_id` - (Required) the id of the consumer to be configured with jwt auth
34+
* `algorithm` - (Optional) The algorithm used to verify the token’s signature. Can be HS256, HS384, HS512, RS256, or ES256, Default is `HS256`.
35+
* `key` - (Optional) A unique string identifying the credential. If left out, it will be auto-generated.
36+
* `rsa_public_key` - (Optional) If algorithm is `RS256` or `ES256`, the public key (in PEM format) to use to verify the token’s signature.
37+
* `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

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# kong_plugin
2+
3+
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).
4+
The `config_json` is passed through to the plugin to configure it as is.
5+
6+
## Example Usage
7+
8+
```hcl
9+
resource "kong_plugin" "rate_limit" {
10+
name = "rate-limiting"
11+
config_json = <<EOT
12+
{
13+
"second": 5,
14+
"hour" : 1000
15+
}
16+
EOT
17+
}
18+
```
19+
To apply a plugin to a consumer use the `consumer_id` property, for example:
20+
21+
```hcl
22+
resource "kong_consumer" "plugin_consumer" {
23+
username = "PluginUser"
24+
custom_id = "567"
25+
}
26+
27+
resource "kong_plugin" "rate_limit" {
28+
name = "rate-limiting"
29+
consumer_id = "${kong_consumer.plugin_consumer.id}"
30+
config_json = <<EOT
31+
{
32+
"second": 5,
33+
"hour" : 1000
34+
}
35+
EOT
36+
}
37+
```
38+
39+
To apply a plugin to a service use the `service_id` property, for example:
40+
41+
```hcl
42+
resource "kong_service" "service" {
43+
name = "test"
44+
protocol = "http"
45+
host = "test.org"
46+
}
47+
48+
resource "kong_plugin" "rate_limit" {
49+
name = "rate-limiting"
50+
service_id = "${kong_service.service.id}"
51+
config_json = <<EOT
52+
{
53+
"second": 10,
54+
"hour" : 2000
55+
}
56+
EOT
57+
}
58+
```
59+
60+
To apply a plugin to a route use the `route_id` property, for example:
61+
62+
```hcl
63+
resource "kong_service" "service" {
64+
name = "test"
65+
protocol = "http"
66+
host = "test.org"
67+
}
68+
69+
resource "kong_plugin" "rate_limit" {
70+
name = "rate-limiting"
71+
enabled = true
72+
service_id = "${kong_service.service.id}"
73+
config_json = <<EOT
74+
{
75+
"second": 11,
76+
"hour" : 4000
77+
}
78+
EOT
79+
}
80+
```
81+
82+
## Argument reference
83+
84+
`plugin_name` - (Required) the name of the plugin you want to configure
85+
`consumer_id` - (Optional) the consumer id you want to configure the plugin for
86+
`service_id` - (Optional) the service id that you want to configure the plugin for
87+
`route_id` - (Optional) the route id that you want to configure the plugin for
88+
`enabled` - (Optional) whether the plugin is enabled or not, use if you want to keep the plugin installed but disable it
89+
`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
90+
page of the plugin you are configuring
91+
92+
## Import
93+
94+
To import a plugin:
95+
96+
```shell
97+
terraform import kong_plugin.<plugin_identifier> <plugin_id>
98+
```

‎docs/resources/route.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# kong_route
2+
3+
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).
4+
5+
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.
6+
7+
## Example Usage
8+
9+
```hcl
10+
resource "kong_route" "route" {
11+
name = "MyRoute"
12+
protocols = [ "http", "https" ]
13+
methods = [ "GET", "POST" ]
14+
hosts = [ "example2.com" ]
15+
paths = [ "/test" ]
16+
strip_path = false
17+
preserve_host = true
18+
regex_priority = 1
19+
service_id = kong_service.service.id
20+
}
21+
22+
```
23+
24+
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:
25+
26+
```hcl
27+
28+
resource "kong_route" "route" {
29+
protocols = [ "tcp" ]
30+
strip_path = true
31+
preserve_host = false
32+
source {
33+
ip = "192.168.1.1"
34+
port = 80
35+
}
36+
source {
37+
ip = "192.168.1.2"
38+
}
39+
destination {
40+
ip = "172.10.1.1"
41+
port = 81
42+
}
43+
snis = ["foo.com"]
44+
service_id = kong_service.service.id
45+
}
46+
```
47+
48+
## Argument Reference
49+
50+
* `name` - (Optional) The name of the route
51+
* `protocols` - (Required) The list of protocols to use
52+
* `methods` - (Optional) A list of HTTP methods that match this Route
53+
* `hosts` - (Optional) A list of domain names that match this Route
54+
* `paths` - (Optional) A list of paths that match this Route
55+
* `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.
56+
* `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`.
57+
* `strip_path` - (Optional) When matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Default: true.
58+
* `regex_priority` - (Optional) A number used to choose which route resolves a given request when several routes match it using regexes simultaneously.
59+
* `path_handling` - (Optional) Controls how the Service path, Route path and requested path are combined when sending a request to the upstream.
60+
* `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.
61+
* `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.
62+
* `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.
63+
* `source` - (Required) A list of source `ip` and `port`
64+
* `destination` - (Required) A list of destination `ip` and `port`
65+
* `snis` - (Optional) A list of SNIs that match this Route when using stream routing.
66+
* `service_id` - (Required) Service ID to map to
67+
* `tags` - (Optional) A list of strings associated with the Route for grouping and filtering.
68+
69+
70+
## Import
71+
72+
To import a route:
73+
74+
```shell
75+
terraform import kong_route.<route_identifier> <route_id>
76+
```

0 commit comments

Comments
 (0)