= HTTP //// THIS FILE IS AUTOGENERATED! To make changes please edit the contents of: https://github.com/redpanda-data/connect/tree/main/cmd/tools/docs_gen/templates/http.adoc.tmpl //// // © 2024 Redpanda Data Inc. When {page-component-title} runs it kicks off an HTTP server that provides a few generally useful endpoints and is also where configured components such as the xref:components:inputs/http_server.adoc[`http_server` input] xref:components:outputs/http_server.adoc[and output] can register their own endpoints if they don't require their own host/port. The configuration for this server lives under the `http` namespace, with the following default values: [tabs] ====== Common:: + -- ```yaml # Common config fields, showing default values http: enabled: true address: 0.0.0.0:4195 root_path: /benthos debug_endpoints: false ``` -- Advanced:: + -- ```yaml # All config fields, showing default values http: enabled: true address: 0.0.0.0:4195 root_path: /benthos debug_endpoints: false cert_file: "" key_file: "" cors: enabled: false allowed_origins: [] basic_auth: enabled: false realm: restricted username: "" password_hash: "" algorithm: sha256 salt: "" ``` -- ====== The field `enabled` can be set to `false` in order to disable the server. The field `root_path` specifies a general prefix for all endpoints, this can help isolate the service endpoints when using a reverse proxy with other shared services. All endpoints will still be registered at the root as well as behind the prefix, e.g. with a `root_path` set to `/foo` the endpoint `/version` will be accessible from both `/version` and `/foo/version`. == Enabling HTTPS By default {page-component-title} will serve traffic over HTTP. In order to enforce TLS and serve traffic exclusively over HTTPS you must provide a `cert_file` and `key_file` path in your config, which point to a file containing a certificate and a matching private key for the server respectively. If the certificate is signed by a certificate authority, the `cert_file` should be the concatenation of the server's certificate, any intermediates, and the CA's certificate. == Enabling basic authentication By default {page-component-title} does not do any sort of authentication for the service-wide HTTP server. However, it's possible to configure basic authentication with the <> field. Passwords configured must be hashed according to the specified algorithm and base64 encoded, for some hashing algorithms you can do this using {page-component-title} itself: ```sh echo mynewpassword | rpk connect blobl 'root = content().hash("sha256").encode("base64")' ``` == Endpoints The following endpoints will be generally available when the HTTP server is enabled: - `/version` provides version info. - `/ping` can be used as a liveness probe as it always returns a 200. - `/ready` can be used as a readiness probe as it serves a 200 only when both the input and output are connected, otherwise a 503 is returned. - `/metrics`, `/stats` both provide metrics when the metrics type is either xref:components:metrics/json_api.adoc[`json_api`] or xref:components:metrics/prometheus.adoc[`prometheus`]. - `/endpoints` provides a JSON object containing a list of available endpoints, including those registered by configured components. == CORS In order to serve Cross-Origin Resource Sharing headers, which instruct browsers to allow CORS requests, set the subfield `cors.enabled` to `true`. === allowed_origins A list of allowed origins to connect from. The literal value `*` can be specified as a wildcard. Note `cors.enabled` must be set to `true` for this list to take effect. == Debug endpoints The field `debug_endpoints` when set to `true` prompts {page-component-title} to register a few extra endpoints that can be useful for debugging performance or behavioral problems: - `/debug/config/json` returns the loaded config as JSON. - `/debug/config/yaml` returns the loaded config as YAML. - `/debug/pprof/block` responds with a pprof-formatted block profile. - `/debug/pprof/heap` responds with a pprof-formatted heap profile. - `/debug/pprof/mutex` responds with a pprof-formatted mutex profile. - `/debug/pprof/profile` responds with a pprof-formatted cpu profile. - `/debug/pprof/goroutine` responds with a pprof-formatted goroutine profile. - `/debug/pprof/symbol` looks up the program counters listed in the request, responding with a table mapping program counters to function names. - `/debug/pprof/trace` responds with the execution trace in binary form. Tracing lasts for duration specified in seconds GET parameter, or for 1 second if not specified. - `/debug/stack` returns a snapshot of the current service stack trace. == Fields The schema of the `http` section is as follows: === `enabled` Whether to enable to HTTP server. *Type*: `bool` *Default*: `true` === `address` The address to bind to. *Type*: `string` *Default*: `"0.0.0.0:4195"` === `root_path` Specifies a general prefix for all endpoints, this can help isolate the service endpoints when using a reverse proxy with other shared services. All endpoints will still be registered at the root as well as behind the prefix, e.g. with a root_path set to `/foo` the endpoint `/version` will be accessible from both `/version` and `/foo/version`. *Type*: `string` *Default*: `"/benthos"` === `debug_endpoints` Whether to register a few extra endpoints that can be useful for debugging performance or behavioral problems. *Type*: `bool` *Default*: `false` === `cert_file` An optional certificate file for enabling TLS. *Type*: `string` *Default*: `""` === `key_file` An optional key file for enabling TLS. *Type*: `string` *Default*: `""` === `cors` Adds Cross-Origin Resource Sharing headers. *Type*: `object` Requires version 3.63.0 or newer === `cors.enabled` Whether to allow CORS requests. *Type*: `bool` *Default*: `false` === `cors.allowed_origins` An explicit list of origins that are allowed for CORS requests. *Type*: `array` *Default*: `[]` === `basic_auth` Allows you to enforce and customise basic authentication for requests to the HTTP server. *Type*: `object` === `basic_auth.enabled` Enable basic authentication *Type*: `bool` *Default*: `false` === `basic_auth.realm` Custom realm name *Type*: `string` *Default*: `"restricted"` === `basic_auth.username` Username required to authenticate. *Type*: `string` *Default*: `""` === `basic_auth.password_hash` Hashed password required to authenticate. (base64 encoded) *Type*: `string` *Default*: `""` === `basic_auth.algorithm` Encryption algorithm used to generate `password_hash`. *Type*: `string` *Default*: `"sha256"` ```yml # Examples algorithm: md5 algorithm: sha256 algorithm: bcrypt algorithm: scrypt ``` === `basic_auth.salt` Salt for scrypt algorithm. (base64 encoded) *Type*: `string` *Default*: `""`