knitgateway.example.yaml

# 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