ocket8888 commented on code in PR #6754: URL: https://github.com/apache/trafficcontrol/pull/6754#discussion_r863161299
########## docs/source/admin/traffic_ops.rst: ########## @@ -586,6 +590,34 @@ This file sets authentication options for connections to Riak when used as the T .. impl-detail:: The name of this file is derived from the current database used in the implementation of Traffic Vault - `Riak KV <https://riak.com/products/riak-kv/index.html>`_. +.. _backends.conf: + +backends.conf +""""""""""""" +This file deals with the configuration parameters of running Traffic Ops as a reverse proxy for certain endpoints that need to be served externally by other backend services. It is a JSON-format set of options and their respective values. `traffic_ops_golang`_ will use whatever file is specified (if any) by its :option:`--backendcfg` option. The keys of the file are described below. + +:routes: This is an array of options to configure Traffic Ops to forward requests of specified types to the appropriate backends. + + :path: The regex matching the endpoint that will be served by the backend, for example, `^api/4.0/foo?$`. + :method: The HTTP method for the above mentioned path, for example, `GET` or `PUT`. Review Comment: same as above RE: double vs single grave accents ########## docs/source/admin/traffic_ops.rst: ########## @@ -586,6 +590,34 @@ This file sets authentication options for connections to Riak when used as the T .. impl-detail:: The name of this file is derived from the current database used in the implementation of Traffic Vault - `Riak KV <https://riak.com/products/riak-kv/index.html>`_. +.. _backends.conf: + +backends.conf +""""""""""""" +This file deals with the configuration parameters of running Traffic Ops as a reverse proxy for certain endpoints that need to be served externally by other backend services. It is a JSON-format set of options and their respective values. `traffic_ops_golang`_ will use whatever file is specified (if any) by its :option:`--backendcfg` option. The keys of the file are described below. + +:routes: This is an array of options to configure Traffic Ops to forward requests of specified types to the appropriate backends. + + :path: The regex matching the endpoint that will be served by the backend, for example, `^api/4.0/foo?$`. + :method: The HTTP method for the above mentioned path, for example, `GET` or `PUT`. + :routeId: The integral identifier for the new route being added. + :hosts: An array of the host object, which specifies the protocol, hostname and port where the request (if matched) needs to be forwarded to. + + :protocol: The protocol/scheme to be followed while forwarding the requests to the backend service. + :hostname: The hostname of the server where the backend service is running. + :port: The port (integer) on the backend server where the service is running. + + :insecure: A boolean specifying whether or not TO should verify the backend server's certificate chain and host name. This is not recommended for production use. This is an optional parameter, defaulting to `false` when not present. Review Comment: same as above RE: double vs single grave accents ########## docs/source/admin/traffic_ops.rst: ########## @@ -586,6 +590,34 @@ This file sets authentication options for connections to Riak when used as the T .. impl-detail:: The name of this file is derived from the current database used in the implementation of Traffic Vault - `Riak KV <https://riak.com/products/riak-kv/index.html>`_. +.. _backends.conf: + +backends.conf +""""""""""""" +This file deals with the configuration parameters of running Traffic Ops as a reverse proxy for certain endpoints that need to be served externally by other backend services. It is a JSON-format set of options and their respective values. `traffic_ops_golang`_ will use whatever file is specified (if any) by its :option:`--backendcfg` option. The keys of the file are described below. + +:routes: This is an array of options to configure Traffic Ops to forward requests of specified types to the appropriate backends. + + :path: The regex matching the endpoint that will be served by the backend, for example, `^api/4.0/foo?$`. + :method: The HTTP method for the above mentioned path, for example, `GET` or `PUT`. + :routeId: The integral identifier for the new route being added. + :hosts: An array of the host object, which specifies the protocol, hostname and port where the request (if matched) needs to be forwarded to. + + :protocol: The protocol/scheme to be followed while forwarding the requests to the backend service. + :hostname: The hostname of the server where the backend service is running. + :port: The port (integer) on the backend server where the service is running. + + :insecure: A boolean specifying whether or not TO should verify the backend server's certificate chain and host name. This is not recommended for production use. This is an optional parameter, defaulting to `false` when not present. + :permissions: An array of permissions (strings) specifying the permissions required by the user to use this API route. + :opts: A collection of key value pairs to control how the requests should be forwarded/ handled, for example, `"alg": "roundrobin"`. Currently, only `roundrobin` is supported (which is also the default if nothing is specified) by Traffic Ops. Review Comment: same as above RE: double vs single grave accents ########## docs/source/admin/traffic_ops.rst: ########## @@ -586,6 +590,34 @@ This file sets authentication options for connections to Riak when used as the T .. impl-detail:: The name of this file is derived from the current database used in the implementation of Traffic Vault - `Riak KV <https://riak.com/products/riak-kv/index.html>`_. +.. _backends.conf: Review Comment: it's not hurting anything but this label is unused. ```rst backends.conf_ ``` is a link to a section titled `backends.conf` on the current page, not a link to a label. `:ref:` is used to refer to arbitrary labels from any page/section. ########## docs/source/admin/traffic_ops.rst: ########## @@ -586,6 +590,34 @@ This file sets authentication options for connections to Riak when used as the T .. impl-detail:: The name of this file is derived from the current database used in the implementation of Traffic Vault - `Riak KV <https://riak.com/products/riak-kv/index.html>`_. +.. _backends.conf: + +backends.conf +""""""""""""" +This file deals with the configuration parameters of running Traffic Ops as a reverse proxy for certain endpoints that need to be served externally by other backend services. It is a JSON-format set of options and their respective values. `traffic_ops_golang`_ will use whatever file is specified (if any) by its :option:`--backendcfg` option. The keys of the file are described below. + +:routes: This is an array of options to configure Traffic Ops to forward requests of specified types to the appropriate backends. + + :path: The regex matching the endpoint that will be served by the backend, for example, `^api/4.0/foo?$`. Review Comment: fyi there's a specific [Sphinx text role for regular expressions](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-regexp) - I think you meant for this to be monospace font e.g. using the `<code>` HTML element, but actually single grave accents (<kbd>\`</kbd>) uses the "default" role which is emphasis, so you're trying to render `^api/4.0/foo?$` but you're getting *^api/4.0/foo?$* tl;dr: use `:regexp:` for regular expressions, use double grave accents (<kbd>\`</kbd>) for code. ########## traffic_ops/app/conf/production/backends.conf: ########## @@ -0,0 +1,48 @@ +{ + "routes": [ Review Comment: Ah, it seems your editor somehow has become misconfigured to insert spaces instead of indentation. That happens sometimes, but it's usually easy to fix, so you can go back to indenting things instead of spacing them. Also: shouldn't `routes` be empty in a default configuration? Based on the values below, I'm not sure exactly what I'd expect the configuration to do. In particular it's a bit concerning that the docs strongly recommend that `insecure` not be set to `true` in production, but this production configuration does exactly that. ########## traffic_ops/traffic_ops_golang/config/config.go: ########## @@ -36,6 +36,31 @@ import ( "github.com/apache/trafficcontrol/lib/go-util" ) +type Options struct { + Algorithm string `json:"alg"` +} + +type Host struct { + Protocol string `json:"protocol"` + Hostname string `json:"hostname"` + Port int `json:"port"` +} + +type BackendRoute struct { + Path string `json:"path"` + Method string `json:"method"` + Hosts []Host `json:"hosts"` + Opts Options `json:"opts"` + ID int `json:"routeId"` + Insecure bool `json:"insecure"` + Permissions []string `json:"permissions"` + Index int +} + +type BackendConfig struct { Review Comment: GoDocs pls -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
