# This is an example configuration file that can be used with the # knitgateway command in this repo (in ./cmd/knitgateway). # # This configuration works with the demo server program defined in # github.com/bufbuild/knit-demo/go/cmd/swapi-server. # # You can try it out like so: # # go install github.com/bufbuild/knit-go/cmd/knitgateway # go install github.com/bufbuild/knit-demo/go/cmd/swapi-server # swapi-server & # knitgateway -conf ./knitgateway.example.yaml & # # With the above, you can point a Knit client that is configured for # the [Knit demo service](https://buf.build/bufbuild/knit-demo) at # http://localhost:30480. listen: # By default, the server binds to all interfaces. You can set # this to 127.0.0.1 to accept requests only on the loopback # interface. #bind_address: 0.0.0.0 # A port is required in order to listen on TCP socket. If not # specified then a unix_socket must be specified. port: 30480 # If specified, the server will listen on a unix domain socket. # This is in addition to listening on TCP socket if port is also # specified. #unix_socket: /path/to/domain/socket # If the "tls" section is present, clients must use TLS (aka SSL) # to connect to the server. #tls: # These are paths to certificate and key files. The files must be # PEM-encoded X509 files. Both of these properties must be # specified. #cert: /path/to/cert #key: /path/to/private-key # This minimum version of TLS to accept. Defaults to 1.0. Other # allowed values are 1.1, 1.2, and 1.3. #min_version: 1.0 # The ciphers to allow or disallow for TLS 1.2 and below. * # Below are the supported cipher suites and which ones are allowed # by default. # # Allowed TLS_RSA_WITH_AES_128_CBC_SHA # Allowed TLS_RSA_WITH_AES_256_CBC_SHA # Allowed TLS_RSA_WITH_AES_128_GCM_SHA256 (TLS 1.2 only) # Allowed TLS_RSA_WITH_AES_256_GCM_SHA384 (TLS 1.2 only) # Allowed TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA # Allowed TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA # Allowed TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA # Allowed TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA # Allowed TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (TLS 1.2 only) # Allowed TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 (TLS 1.2 only) # Allowed TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (TLS 1.2 only) # Allowed TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (TLS 1.2 only) # Allowed TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (TLS 1.2 only) # Allowed TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 (TLS 1.2 only) # Disallowed TLS_RSA_WITH_RC4_128_SHA # Disallowed TLS_RSA_WITH_3DES_EDE_CBC_SHA # Disallowed TLS_RSA_WITH_AES_128_CBC_SHA256 (TLS 1.2 only) # Disallowed TLS_ECDHE_ECDSA_WITH_RC4_128_SHA # Disallowed TLS_ECDHE_RSA_WITH_RC4_128_SHA # Disallowed TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA # Disallowed TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 (TLS 1.2 only) # Disallowed TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (TLS 1.2 only) # # * For TLS 1.3, supported cipher suites are the following and are not configurable: # TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256 # #ciphers: # Only one of the following may be present. If 'allow' is present, # it enumerates ALL allowed cipher suites. Any cipher not named is # not allowed. #allow: [] # If 'disallow' is present, it enumerates ALL disallowed cipher # suites. Any cipher not named but present in the table above is # allowed. #disallow: [] # If the 'client_certs' section is present, TLS certificates will # be requested from clients during the handshake. #client_certs: # If false or absent, client certs are verified if given, but are # not required. If true, connections will be terminated if the # client does not provide a valid cert. # # When a client cert is present and valid, the authenticated # identity ("subject" field of the cert) will be added to HTTP # headers for all requests to backends. #require: true # This is the path to PEM-encoded X509 certificate pool file that # contains certs for CAs (certificate authorities/issuers). These # are used to verify client certs. #cacert: /path/to/ca-cert admin: # By default, admin endpoints are available. Note that admin endpoints are # NOT secured, other than by being served on a potentially different network # interface and port and using the same TLS config (if any) as the main # traffic port. If these measures are insufficient to adequately protect # these endpoints in your environment, you can disable them with the # following setting. #enabled: true # Configures a port from which admin endpoints are served. If not # configured, defaults to 0, which instructs the operating system to # select an ephemeral port. An ephemeral port means that basically every # instance of the gateway will be using a different high-numbered port. # The admin endpoints are nearly inaccessible this way. (Requires either # probing the host for which ports have listeners or access to the logs # where the gateway prints the actual port used.) port: 30481 # Configures which network interfaces are used for serving admin endpoints. # The default is 127.0.0.1, so that only the loopback interface is allowed. #bind_address: 127.0.0.1 # By default, the admin endpoints will use the same TLS config as the main # traffic port. If the main traffic port uses TLS, but the admin endpoints # can use plaintext (generally okay if they aren't exposed externally, such # as if only allowed over loopback interface). #use_tls: false # Instead of having the admin endpoints exposed on a different interface or # port, they can instead be exposed via the same listeners as for other # Knit application traffic. If this flag is set to true, use caution in # ingress or service mesh configuration to prevent unauthorized clients # from accessing "/admin/" URI paths. #use_main_listeners: false limits: # As of now, there is only one supported limit: the maximum parallelism # per request. This is the maximum number of concurrent RPCs that can be # made on behalf of a single Knit query. If not specified, there is no # limit, and all RPCs needed to evaluate a query will all be made in parallel. per_request_parallelism: 10 backends: # You can define any number of backends. For this example, there is # only one, which is the swapi-server program defined in the # github.com/bufbuild/knit-demo repo: - route_to: http://127.0.0.1:30485 # 30485 is the default port used by swapi-server. # If specified, the gateway will use the named unix domain socket # to connect to the backend. #unix_socket: /path/to/domain/socket # A 'tls' section may be present (but is not required) for # backends that use "https". Any property that is NOT present # will use the value present in the 'default_tls' top-level # config stanza, if present. If that top-level stanza is not # present, then the defaults described below apply. #tls: # This minimum version of TLS to accept. Defaults to 1.2. Other # allowed values are 1.1, 1.2, and 1.3. # NOTE: this is a different default than for the listener config. # This listener default is more lenient, to support external # clients that use older browser or mobile OS software. #min_version: 1.2 # The ciphers to allow or disallow for TLS 1.2 and below. See the # info above (under 'listener.tls' config) for more details on # configuring cipher suites. #ciphers: #allow: [] #disallow: [] # This is the path to PEM-encoded X509 certificate pool file that # contains certs for CAs (certificate authorities/issuers). These # are used to verify server certs of the backend. #cacert: /path/to/ca-cert # This flag DISABLES verification of server certs. Its use is # strongly discouraged. It is present primarily to aid with # testing. #skip_verify: false # These are paths to certificate and key files to use as a client # cert, when connecting to the backend. The files must be # PEM-encoded X509 files. Both must be present together, to enable # client certs, or both must be absent, to connect to the backend # without a client cert. #cert: /path/to/cert #key: /path/to/private-key # By default, the gateway will use the Connect protocol to send # RPCs to the backend. It can be configured to use gRPC or # gRPC-Web instead, via "grpc" or "grpcweb" values: #protocol: connect # By default, the gateway will use the Protobuf binary format to # send RPCs. The other option allowed is "json": #encoding: proto # All the services that swapi-server exposes: services: - buf.knit.demo.swapi.film.v1.FilmService - buf.knit.demo.swapi.person.v1.PersonService - buf.knit.demo.swapi.planet.v1.PlanetService - buf.knit.demo.swapi.species.v1.SpeciesService - buf.knit.demo.swapi.starship.v1.StarshipService - buf.knit.demo.swapi.vehicle.v1.VehicleService # These services define relation resolvers: - buf.knit.demo.swapi.relations.v1.FilmResolverService - buf.knit.demo.swapi.relations.v1.PersonResolverService - buf.knit.demo.swapi.relations.v1.PlanetResolverService - buf.knit.demo.swapi.relations.v1.SpeciesResolverService - buf.knit.demo.swapi.relations.v1.StarshipResolverService - buf.knit.demo.swapi.relations.v1.VehicleResolverService # We have to tell the gateway how to find the service # definitions for all the services listed above for # this backend. If the server supports reflection, # that's the "easy button" for this step. descriptors: grpc_reflection: true # These particular services are also available in the # BSR. So the following configuration also works: # #buf_module: buf.build/bufbuild/knit-demo # # Note that this requires a BUF_TOKEN environment variable # for authenticating with the BSR. # If your servers do not support gRPC reflection and # your schema is not in the BSR, you can also provide # them via file descriptor sets. These can be produced # with the Buf CLI using the "build" command: # buf build buf.build/bufbuild/knit-demo -o swapi.protoset # They can also be produced by "protoc" using a '-o' # flag. Don't forget to use '--include_imports' so that # the file is self-contained: # protoc --include_imports -o swapi.protoset ... # # Once you have a file, you can use configuration like so: # #descriptor_set_file: path/to/swapi.protoset # Since gRPC reflection uses a full-duplex bidi stream, we must # use HTTP/2. Usually, HTTP/2 is negotiated during the TLS # handshake. But since we are using plaintext to talk to the # server (i.e. the scheme in 'route_to' above is "http", not # "https"), we must enable H2C. H2C simply means HTTP/2 over # plain-text. # # NOTE: NOT all HTTP servers support this! It usually requires # special server configuration. For this case, swapi-server DOES # support it, so this setting will work. h2c: true # If many or all backends use the same TLS configuration, then # specify it here instead of repeating it in the 'tls' stanza for # each backend. #backend_tls: # This section supports all of the same properties as the 'tls' # section under 'backends' above, EXCEPT for 'server_name'. That # property, if used, must be provided on a per-backend basis. #min_version: 1.2 #ciphers: #allow: [] #disallow: [] #cacert: /path/to/ca-cert #skip_verify: false #cert: /path/to/cert #key: /path/to/private-key # There are other configuration settings related to retrieval # of descriptors that are not on a per-backend basis. descriptors: # The maximum time to wait at startup for schemas to be resolved. # If startup takes longer than this, the process will exit instead # continuing to wait. If unset or zero, then a default value of # 15 seconds is used. #startup_max_wait_seconds: 15 # The time to wait in between attempts to re-download a schema. # The gateway continually re-downloads schemas in case they change # over time. If unset or set to zero, a default value of 15 minutes # is used (which is 900 seconds). #polling_period_seconds: 900 # A value between zero and one for the amount of random jitter to use # when scheduling a polling attempt. This is used to prevent multiple # processes from inadvertently self-synchonizing and turning into a # thundering herd. A typical value for this purpose is 0.1 to 0.3. # A value of zero means no jitter. A value of 1 means 100% jitter, # which means the polling period can be perturbed up to 100% (so # it could be as low as zero as high as double). The default is 0.25. #polling_jitter: 0.25 # The number of seconds to wait after a schema update to "debounce" # updates from multiple sources. A smaller value means the gateway's # internals are re-created more frequently when updates are frequent. # A higher value can be more efficient (re-create the internals only # once for a sequence of rapid updates) but slow down the response # time from receiving a new schema and serving the new configuration. # The default is zero, which is appropriate for development. But # production deployments with multiple schema sources should set it # a reasonable value (like between 5 and 30 seconds). #polling_debounce_seconds: 0 # This section configures a cache for resolved schemas. For Buf BSR # modules and gRPC reflection as descriptor sources, there is a # possibility that a network partition could prevent the gateway # from downloading a schema at startup. For this, the cache can be # used to fetch a last-known-good schema. The cache is updated # whenever a new schema is downloaded. It is used for loading the # schemas if polling a backend source fails. This improves resilience # of the gateway. # # Note: when loading schemas from local files, caching is not used. # It is assumed that the local file will is at least as reliable as # a cache source, so it's unnecessary. #cache: # Only one of the three keys, file_system, redis, or memcache, # can be used. # This caches the results on the file system. This is not a # particularly good fit if the gateway is deployed as a workload # where the storage is ephemeral (such that the cache will # disappear when the workload restarts). But if it is deployed # with a persistent disk or has a network filesystem mounted # this can work well. If the gateway workload will be auto-scaled # horizontally (e.g. more replicas created on demand), then a # network filesystem (where all replicas can share the files) # works better and is typically easier to configure than a # persistent disk. #file_system: # This first property is required and has no default. You must # tell the gateway where to store cached data on the filesystem. #directory: /var/cache/knitgateway # This is a prefix used in names of files that represent cache # entries in the configured directory. The rest of the filename # is a cache key. The default prefix is "cache_". The trailing # underscore is optional and will be automatically added if # needed. #file_name_prefix: "cache" # This is the extension of cache files created. The default is # ".bin". The leading dot is optional and will be automatically # added if needed. #file_extension: "bin" # The mode used to create the files. This will be combined with the # process's umask to determine the actual permissions of created # files. If unspecified or zero, defaults to 0600 (readable and # writable by owner). This value must be in octal; the leading # zero is optional. #file_mode: 0600 # This caches the results in a Redis server. Redis servers typically # are fast and have high up-time, making them suitable for use as a # distributed/shared cache. #redis: # The only required property is the address of the Redis host. #host: knit-gateway-redis:6379 # If auth is required by the Redis server, set this to true and # also set REDIS_USER (optional) and REDIS_PASSWORD environment # variables. If only a REDIS_PASSWORD is provided, the gateway # will issue the "auth" command with only a password, for servers # using the "requirepass" option. For servers using the Redis # ACL system (as of Redis 6.0), both should be supplied. This # defaults to false. #require_auth: false # The idle timeout is used to close idle connections before they # are closed by the server. To that end, this should be a value # that is less than the server's timeout. If unspecified or zero, # idle connections will not be closed. #idle_timeout_seconds: 900 # If the gateway should store cache entries in a numbered database, # indicate the database number here. The default is zero. #database: 0 # The key prefix can be used to namespace keys, in case other # workloads use the same Redis server to store data. The default # value is empty. #key_prefix: "knit-schema:" # An expiry may be applied to each cache entry. The entry will be # auto-removed after this number of seconds elapses. By default, # entries will be created without expiry (and never be deleted). #expiry_seconds: 864000 # This last option is for using memcached as a distributed/shared # cache. This is similar in many regards to using Redis. #memcache: # This first value is the only required value. One or more hosts # must be provided. If multiple hosts are provided, the cache # entries will be distributed across them. This allows some cache # entries surviving, even if a single memcached server instance # becomes unavailable or is reset. #hosts: #- mc-a:11211 #- mc-b:11211 #- mc-c:11211 #- mc-d:11211 # The key prefix can be used to namespace keys, in case other # workloads use the same memcached servers to store data. The # default value is empty. #key_prefix: "knit-schema:" # An expiry may be applied to each cache entry. The entry will be # auto-removed after this number of seconds elapses. By default, # entries will be created without expiry (and never be deleted). #expiry_seconds: 864000 # If your server will be handling cross-origin requests from # browsers, you need to configure CORS. If this section is absent # then CORS preflight requests will always get a negative response # (i.e. origin not allowed). cors: # This is a list of allowed origins. Specifying a single wildcard # means all origins are allowed. An entry in the list can include # a single wildcard as a domain component, for example # "https://*.foo.com" is an allowed value that allows all # immediate sub-domains of foo.com. # The default value is empty, which does not allow any origins. allowed_origins: ['*'] # This is a list of allowed headers. The special entry '*' means # all headers are allowed. # The default value is empty, which does not allow any headers. allowed_headers: ['*'] # When true, the browser will be allowed to use credentials (such # as client TLS certs or cookies) with cross-origin requests. # The default value is false. allow_credentials: true # When true, the browser will be allowed to send cross-origin # requests using a private network. # The default value is false. #allow_private_networks: false # This value allows the browser to cache the results of a # pre-flight request, resulting in potentially fewer pre-flight # requests to authorize future cross-origin requests. If this # field is omitted or zero, no such header is sent to the browser. # If not specified in a response header, the default for browsers # is 5 seconds. #max_age_seconds: 600