{"id":13677850,"url":"https://github.com/mybuilder/kongfig","last_synced_at":"2025-04-12T23:29:46.158Z","repository":{"id":1768759,"uuid":"44193541","full_name":"mybuilder/kongfig","owner":"mybuilder","description":"Declarative configuration for Kong","archived":false,"fork":false,"pushed_at":"2023-01-25T04:04:28.000Z","size":1011,"stargazers_count":373,"open_issues_count":69,"forks_count":75,"subscribers_count":32,"default_branch":"master","last_synced_at":"2024-10-29T21:21:37.711Z","etag":null,"topics":["kong"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mybuilder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-13T17:35:53.000Z","updated_at":"2024-08-25T04:25:34.000Z","dependencies_parsed_at":"2023-02-14T04:25:26.185Z","dependency_job_id":null,"html_url":"https://github.com/mybuilder/kongfig","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mybuilder%2Fkongfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mybuilder%2Fkongfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mybuilder%2Fkongfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mybuilder%2Fkongfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mybuilder","download_url":"https://codeload.github.com/mybuilder/kongfig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248646992,"owners_count":21139079,"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":["kong"],"created_at":"2024-08-02T13:00:47.940Z","updated_at":"2025-04-12T23:29:46.138Z","avatar_url":"https://github.com/mybuilder.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Tools"],"sub_categories":["Configuration"],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"logo.png\"\u003e\n\u003c/p\u003e\n\n# Kongfig\n\nA tool for [Kong](https://getkong.org/) to allow declarative configuration.\n\nSimply define your list of APIs and consumers in json and then run kongfig to ensure that your Kong is configured correctly.\n\n[![Build Status](https://travis-ci.org/mybuilder/kongfig.svg?branch=master)](https://travis-ci.org/mybuilder/kongfig)\n\n## Install\n\n### Manually\nWe recommend installing Kongfig globally\n\n```\nnpm install -g kongfig\n```\n\n### Puppet\nUse our [Puppet-Kongfig](https://forge.puppetlabs.com/mybuilder/kongfig) module to install and configure Kongfig\n\n```\npuppet module install mybuilder-kongfig\n```\n\n\n## Quick start\n\nYou can follow the [quick start](docs/guide.md) to get going in 5 minutes.\n\n\n## Apply config\n\nYou can have your config in [json](config.json.sample), [yaml](config.yml.sample), or [js](config.js.sample) if you need to support multiple environments.\n\n```\nkongfig apply --path config.yml --host localhost:8001\n```\n\n## Dump config\n\nYou can dump the existing configuration to a file or view it on a screen\n\n```\nkongfig dump --host localhost:8001 \u003e config.yml\n```\n\u003e You can omit the `--host` option if kong is on `localhost:8001` as this is the default value\n\nYou can specify the desired format by giving `--format` option with possible options of `json`, `yaml`, or `screen` that prints the config with colours.\n\n```bash\nkongfig dump --format screen\n```\n\nFor APIs which uses custom consumer credential plugins, specify plugin and id name in \u003cplugin\u003e:\u003cidValue\u003e format with `--credential-schema` option.\n\n```\nkongfig apply --path config.yml --host localhost:8001 --credential-schema custom_jwt:key\n```\n\nFor multiple plugins use --credential-schema as many as necessary\n\n```\nkongfig apply --path config.yml --host localhost:8001 --credential-schema \"custom_jwt:key\" --credential-schema \"custom_oauth2:client_id\"\n```\n\n## Schema\n\nNote: If you change the name of an API/Plugin/Consumer and want to ensure the old one is removed automatically, do not delete or modify the old API/Plugin/Consumer section, other than to add the `ensure: \"removed\"` flag. Examples shown below.\n\n\u003e Notice the `attributes.username` config parameter below, this is used to map given username to consumer uuid\n\nApi schema:\n\n```yaml\napis:\n  - name: mockbin # unique api name\n    ensure: \"present\" # Set to \"removed\" to have Kongfig ensure the API is removed. Default is present.\n    attributes:\n      upstream_url: string # (required)\n      hosts: [string]\n      uris: [string]\n      methods: [\"POST\", \"GET\"]\n      strip_uri: bool\n      preserve_host: bool\n      retries: int\n      upstream_connect_timeout: int\n      upstream_read_timeout: int\n      upstream_send_timeout: int\n      https_only: bool # (required)\n      http_if_terminated: bool\n\n```\n\nApi plugin schema:\n\n```yaml\napis:\n  - name: mockbin # unique api name\n    attributes: # ...\n    plugins:\n      - name: rate-limiting # kong plugin name\n        ensure: \"present\" # Set to \"removed\" to have Kongfig ensure the plugin is removed. Default is present.\n        attributes: # the plugin attributes\n          username: # optional, to reference a consumer, same as consumer_id in kong documentation\n          config:\n\n```\n\nGlobal plugin schema:\n\n```yaml\nplugins:\n  - name: cors\n    attributes:\n      username: # optional, to reference a consumer, same as consumer_id in kong documentation\n      enabled: true\n      config:\n        credentials: false\n        preflight_continue: false\n        max_age: 7000\n```\n\nAll of the kong plugins should be supported if you find one that doesn't work please [add an issue](https://github.com/mybuilder/kongfig/issues/new).\n\nConsumer schema:\n\n```yaml\nconsumers:\n  - username: iphone-app\n    custom_id: foobar-1234 # optional\n```\n\nConsumer credential schema:\n\n```yaml\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: key-auth\n        attributes: # credential config attributes\n```\n\nConsumer ACL schema:\n\n```yaml\nconsumers:\n  - username: iphone-app\n    acls:\n      - group: acl-group-name\n```\n\n### Supported consumer credentials\n\n\u003e Notice the `anonymous_username` config parameter below, this is used to map username to consumer uuid\n\n[Key Authentication](https://getkong.org/plugins/key-authentication/)\n\n```yaml\napis:\n  - name: mockbin # unique api name\n    attributes: # ...\n    plugins:\n      - name: key-auth\n        attributes:\n          config:\n            anonymous_username: # optional, same as just anonymous in kong api, maps given username to consumer uuid\n            key_names:\n            hide_credentials:\n\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: key-auth\n        attributes:\n          key: # required\n```\n\n[Basic Authentication](https://getkong.org/plugins/basic-authentication/)\n\n```yaml\napis:\n  - name: mockbin\n    attributes: # ...\n    plugins:\n      - name: basic-auth\n        attributes:\n          config:\n            hide_credentials:\n\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: basic-auth\n        attributes:\n          username: # required\n          password:\n```\n\n[OAuth 2.0 Authentication](https://getkong.org/plugins/oauth2-authentication/)\n\n```yaml\napis:\n  - name: mockbin\n    attributes: # ...\n    plugins:\n      - name: oauth2\n        attributes:\n          config:\n            scopes:\n            mandatory_scope:\n            token_expiration:\n            enable_authorization_code:\n            enable_client_credentials:\n            enable_implicit_grant:\n            enable_password_grant:\n            hide_credentials:\n\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: oauth2\n        attributes:\n          name:\n          client_id: # required\n          client_secret:\n          redirect_uri: string | [string] # required by kong\n```\n\n[HMAC Authentication](https://getkong.org/plugins/hmac-authentication/)\n\n```yaml\napis:\n  - name: mockbin\n    attributes: # ...\n    plugins:\n      - name: hmac-auth\n        attributes:\n          config:\n            hide_credentials:\n            clock_skew:\n\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: hmac-auth\n        attributes:\n          username: # required\n          secret:\n```\n\n[JWT](https://getkong.org/plugins/jwt/)\n\n```yaml\napis:\n  - name: mockbin\n    attributes: # ...\n    plugins:\n      - name: jwt\n        attributes:\n          config:\n            uri_param_names:\n            claims_to_verify:\n\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: jwt\n        attributes:\n          key: # required\n          secret:\n```\n\n### Custom Credential Schemas\n\nIt is possible to work with custom consumer credential plugins.\n\n```yaml\napis:\n  - name: mockbin\n    attributes: # ...\n    plugins:\n      - name: custom_jwt\n        attributes:\n          config:\n            uri_param_names:\n            claims_to_verify:\n\nconsumers:\n  - username: iphone-app\n    credentials:\n      - name: custom_jwt\n        attributes:\n          key: # required\n          secret:\n\ncredentialSchema:\n  custom_jwt:\n    id: \"key\" # credential id name\n```\n\n\n### ACL Support\n\n[Kong ACL documentation](https://getkong.org/plugins/acl/)\n\n```yaml\napis:\n  - name: mockbin\n    attributes: # ...\n    plugins:\n      - name: \"acl\"\n        ensure: \"present\"\n        attributes:\n          config.whitelist: \"foo-group\"\n\nconsumers:\n  - username: \"some-username\"\n    ensure: \"present\"\n    acls:\n      - group: \"foo-group\"\n        ensure: \"present\"\n\n      - group: \"bar-group\"\n        ensure: \"present\"\n```\n\n### Upstream/Target Schema\n\n[Kong Upstream Load Balancing Reference](https://getkong.org/docs/latest/loadbalancing/)\n\n```yaml\nupstreams:\n  - name: \"mockbinUpstream\"\n    ensure: \"present\"\n    targets:\n      - target: \"server1.mockbin:3001\"\n        attributes:\n          weight: 50\n      - target: \"server2.mockbin:3001\"\n        attributes:\n          weight: 50\n    attributes:\n      slots: 100\n```\n\n### Certificates \u0026 SNIs\n\n*A certificate object represents a public certificate/private key pair for an SSL certificate. These objects are used by Kong to handle SSL/TLS termination for encrypted requests. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.*\n\n[Kong Certificate Object Reference](https://getkong.org/docs/0.11.x/admin-api/#certificate-object)\n\n*An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.*\n\n[Kong SNI Objects Reference](https://getkong.org/docs/0.11.x/admin-api/#sni-objects)\n\n```yaml\ncertificates:\n  - ensure: present\n    cert: \u003e-\n      -----BEGIN CERTIFICATE-----\n      MIIDMjCCAhqgAwIBAgIJAPgRdnOdnX/SMA0GCSqGSIb3DQEBBQUAMBoxGDAWBgNV\n      ....\n    key: \u003e-\n      -----BEGIN RSA PRIVATE KEY-----\n      MIIEpAIBAAKCAQEAo5BpOQY2AV/1L2QEdSip75rHh3Khs2knNtMLIrP26MHyidtX\n      ....\n    snis:\n      - name: example.com\n        ensure: present\n      - name: www.example.com\n        ensure: present\n```\n\n\u003e Notice that SNIs are an list of object e.g. `{ name: example.com, ensure: present }` different Kong api itself where it is a list of hostnames\n\n\n## Migrating from Kong \u003c=0.9 to \u003e=0.10\n\nkongfig translates pre `\u003e=0.10` kong config files automatically when applying them.\n\nSo you can export your config from `\u003c=0.9` kong instance by running:\n\n```bash\nkongfig dump --host kong_9:8001 \u003e config.v9.yml\n```\n\nThen apply it to kong `0.10` instance\n\n```bash\nkongfig apply --path config.v9.yml --host kong_10:8001\n```\n\n`apis` endpoint changed between `\u003c=0.9` and `\u003e=0.10`:\n * `request_host: string` to `hosts: [string]`\n * `request_path: string` to `uris: [string]`\n * `strip_request_path: bool` -\u003e `strip_uri: bool`\n * Adds `methods`, `retries`, `upstream_connect_timeout`, `upstream_read_timeout`, `upstream_send_timeout`, `https_only`, `http_if_terminated`\n\n---\nCreated by [MyBuilder](http://www.mybuilder.com/) - Check out our [blog](http://tech.mybuilder.com/) for more information and our other open-source projects.\n\n## Contributing to Kongfig\n\nWe are very grateful for any contributions you can make to the project.\n\nVisit the [Contributing](CONTRIBUTING.md) documentation for submission guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmybuilder%2Fkongfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmybuilder%2Fkongfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmybuilder%2Fkongfig/lists"}