scytale.yaml

# SPDX-FileCopyrightText: 2019 Comcast Cable Communications Management, LLC
# SPDX-License-Identifier: Apache-2.0
---

# wrpValidators defines the wrp validators used to validate incoming wrp messages.
# (Optional)
# Available validator types: always_invalid, always_valid, utf8, msg_type, source, destination, simple_res_req, simple_event, spans
# Available validator levels: info, warning, error
# Validators can be disabled with `disable: true`, it is false by default
wrpValidators:
  - type: utf8
    level: warning
    disable: true
  - type: source
    level: error

# The unique fully-qualified-domain-name of the server.  It is provided to
# the X-Scytale-Server header for showing what server fulfilled the request
# sent.
# (Optional)
server: "scytale"

########################################
#   Labeling/Tracing via HTTP Headers Configuration
########################################

# Provides this build number to the X-Scytale-Build header for
# showing machine version information.  The build number SHOULD
# match the scheme `version-build` but there is not a strict requirement.
# (Optional)
build: "0.1.4"

# Provides the region information to the X-Scytale-Region header
# for showing what region this machine is located in.  The region
# is arbitrary and optional.
# (Optional)
region: "east"

# Provides the flavor information to the X-Scytale-Flavor header
# for showing what flavor this machine is associated with.  The flavor
# is arbitrary and optional.
# (Optional)
flavor: "mint"

##############################################################################
# WebPA Service configuration
##############################################################################

# For a complete view of the service config structure,
# checkout https://godoc.org/github.com/xmidt-org/webpa-common/server#WebPA

########################################
#   primary endpoint Configuration
########################################

# primary defines the details needed for the primary endpoint.  The
# primary endpoint accepts the events from scytale (typically).
# define https://godoc.org/github.com/xmidt-org/webpa-common/server#Basic
primary:
  # address provides the port number for the endpoint to bind to.
  # ":443" is ideal, but may require some special handling due to it being
  # a reserved (by the kernel) port.
  address: ":6300"
  # HTTPS/TLS
  #
  # certificateFile provides the public key and CA chain in PEM format if
  # TLS is used.  Note: the certificate needs to match the fqdn for clients
  # to accept without issue.
  #
  # keyFile provides the private key that matches the certificateFile
  # (Optional)
  # certificateFile: "/etc/scytale/public.pem"
  # keyFile: "/etc/scytale/private.pem"

########################################
#   health endpoint Configuration
########################################

# health defines the details needed for the health check endpoint.  The
# health check endpoint is generally used by services (like AWS Route53
# or consul) to determine if this particular machine is healthy or not.
# define https://godoc.org/github.com/xmidt-org/webpa-common/server#Health
health:
  # address provides the port number for the endpoint to bind to.
  # ":80" is ideal, but may require some special handling due to it being
  # a reserved (by the kernel) port.
  address: ":6301"

  # logInterval appears to be present from before we had formal metrics
  # (Deprecated)
  # logInterval: "60s"
  # options appears to be present from before we had formal metrics
  # (Deprecated)
  # options:
  #  - "PayloadsOverZero"
  #  - "PayloadsOverHundred"
  #  - "PayloadsOverThousand"
  #  - "PayloadsOverTenThousand"

########################################
#   Debugging/pprof Configuration
########################################

# pprof defines the details needed for the pprof debug endpoint.
# define https://godoc.org/github.com/xmidt-org/webpa-common/server#Basic
# (Optional)
pprof:
  # address provides the port number for the endpoint to bind to.
  address: ":6302"

########################################
#   Metrics Configuration
########################################

# metric defines the details needed for the prometheus metrics endpoint
# define https://godoc.org/github.com/xmidt-org/webpa-common/server#Metric
# (Optional)
metric:
  # address provides the port number for the endpoint to bind to.  Port 6204
  # was chosen because it does not conflict with any of the other prometheus
  # metrics or other machines in the xmidt cluster.  You may use any port you
  # wish.
  address: ":6303"

  # metricsOptions provides the details needed to configure the prometheus
  # metric data.  Metrics generally have the form:
  #
  # {namespace}_{subsystem}_{metric}
  #
  # so if you use the suggested value below, your metrics are prefixed like
  # this:
  #
  # xmidt_scytale_{metric}
  #
  # (Optional)
  metricsOptions:
    # namespace is the namespace of the metrics provided
    # (Optional)
    namespace: "xmidt"
    # subsystem is the subsystem of the metrics provided
    # (Optional)
    subsystem: "scytale"

touchstone:
  # DefaultNamespace is the prometheus namespace to apply when a metric has no namespace
  defaultNamespace: "xmidt"
  # DefaultSubsystem is the prometheus subsystem to apply when a metric has no subsystem
  defaultSubsystem: "scytale"

########################################
#   Logging Related Configuration
########################################

# log configures the logging subsystem details
log:
  # file is the name of the most recent log file.  If set to "stdout" this
  # will log to os.Stdout.
  # (Optional) defaults to os.TempDir()
  # file: "/var/log/scytale/scytale.log"
  file: "stdout"

  # level is the logging level to use - INFO, DEBUG, WARN, ERROR
  # (Optional) defaults to ERROR
  level: "DEBUG"

  # maxsize is the maximum file size in MB
  # (Optional) defaults to max 100MB
  maxsize: 50

  # maxage is the maximum number of days to retain old log files
  # (Optional) defaults to ignore age limit (0)
  maxage: 30

  # maxbackups is the maximum number of old log files to retain
  # (Optional) defaults to retain all (0)
  maxbackups: 10

  # json is a flag indicating whether JSON logging output should be used.
  # (Optional) defaults to false
  json: true

zap:
  # OutputPaths is a list of URLs or file paths to write logging output to.
  outputPaths:
    - stdout
    # - /var/log/scytale/scytale.log

  # Level is the minimum enabled logging level. Note that this is a dynamic
  # level, so calling Config.Level.SetLevel will atomically change the log
  # level of all loggers descended from this config.
  level: DEBUG

  # DisableCaller stops annotating logs with the calling function's file
	# name and line number. By default, all logs are annotated.
  disableCaller: true

  # EncoderConfig sets options for the chosen encoder. See
  # zapcore.EncoderConfig for details.
  errorOutputPaths:
    - stderr
    # - /var/log/scytale/scytale.log

  # EncoderConfig sets options for the chosen encoder. See
  # zapcore.EncoderConfig for details.
  encoderConfig:
    messageKey: message
    levelKey: key
    callerKey: caller
    levelEncoder: lowercase

  # Encoding sets the logger's encoding. Valid values are "json" and
  # "console", as well as any third-party encodings registered via
  # RegisterEncoder.
  encoding: json

########################################
#   Fanout Related Configuration
########################################

# fanout describes the endpoints to fanout to and the http configuration to use for each fanout connection.
# defined https://godoc.org/github.com/xmidt-org/webpa-common/xhttp/fanout#Configuration
fanout:
#  # endpoints are the URLs for each endpoint to fan out to.
#  # if this is set, it overrides the service.fixed values.
#  # (Optional) if empty, endpoints are driven by service discovery
#  endpoints: ["http://petasos:6400/api/v2/device/send"]

  # pathPrefix is a string prepended to the beginning of the path being used for
  # fanout.
  pathPrefix: "/api/v3"

  # Authorization is the Basic Auth token to use for each request.
  # (Optional) defaults to no auth token
  # WARNING: This is an example auth token. DO NOT use this in production.
  authorization: YXV0aEhlYWRlcg==

  # transport is a way to overwrite the default golang http.Transport configuration.
  # defined  https://golang.org/pkg/net/http/#Transport
  # (Optional) defaults described below
  transport:
    # (Optional) defaults to 0, aka do not limit it
    maxIdleConns: 0
    # (Optional) defaults to 100
    maxIdleConnsPerHost: 100
    # (Optional) defaults to 0s, aka do not timeout while in idle
    idleConnTimeout: "120s"

  # fanoutTimeout is the timeout for the entire fanout operation.
  # fanoutTimeout should be the same or greater than the clientTimeout.
  # fanoutTimeout includes multiple http requests.
  # (Optional) defaults to 45s
  fanoutTimeout: "127s"

  # clientTimeout is the http.Client Timeout.
  # (Optional) defaults to 30s
  clientTimeout: "127s"

  # concurrency is the maximum number of concurrent fanouts allowed.
  # concurrency is managed by a semaphore described https://godoc.org/github.com/xmidt-org/webpa-common/xhttp#Busy.
  # (Optional) defaults to 1000
  concurrency: 10

  # maxRedirects defines the maximum number of redirects each fanout will allow.
  # (Optional) default to unlimited
  maxRedirects: 3

  # redirectExcludeHeaders are the headers that will *not* be copied on a redirect.
  # (Optional) defaults to copying all headers over.
  redirectExcludeHeaders:
    - X-Xmidt-Log-Level


########################################
#   Authorization Related Configuration
########################################

# Any combination of these configurations may be used for authorization.
# If ANY match, the request goes onwards.  If none are provided, no requests
# will be accepted.

# authHeader provides the list of basic auth headers that scytale will accept
# as authorization. Note: This is an example authHeader. Do not use this in production.
# (Optional)
authHeader: ["dXNlcjpwYXNz"]

# jwtValidator provides the details about where to get the keys for JWT
# kid values and their associated information (expiration, etc) for JWTs
# used as authorization
# (Optional)
jwtValidator:
  Config:
    Resolve:
      # Template is a URI template used to fetch keys.  This template may
	    # use a single parameter named keyID, e.g. http://keys.com/{keyID}.
      # This field is required and has no default.
      Template: "http://localhost/{keyID}"
    Refresh:
      Sources:
        # URI is the location where keys are served.  By default, clortho supports
        # file://, http://, and https:// URIs, as well as standard file system paths
        # such as /etc/foo/bar.jwk.
        #
        # This field is required and has no default.
        - URI: "http://localhost"

# capabilityCheck provides the details needed for checking an incoming JWT's
# capabilities.  If the type of check isn't provided, no checking is done.  The 
# type can be "monitor" or "enforce".  If it is empty or a different value, no 
# checking is done.  If "monitor" is provided, the capabilities are checked but 
# the request isn't rejected when there isn't a valid capability for the 
# request. Instead, a message is logged.  When "enforce" is provided, a request 
# that doesn't have the needed capability is rejected.
#
# The capability is expected to have the format:
#
# {prefix}{endpoint}:{method}
#
# The prefix can be a regular expression.  If it's empty, no capability check 
# is done.  The endpoint is a regular expression that should match the endpoint
# the request was sent to. The method is usually the method of the request, such as 
# GET.  The accept all method is a catchall string that indicates the capability 
# is approved for all methods.
# (Optional)
# capabilityCheck:
#   # type provides the mode for capability checking.
#   type: "enforce"
#   # prefix provides the regex to match the capability before the endpoint.
#   prefix: "prefix Here"
#   # acceptAllMethod provides a way to have a capability that allows all 
#   # methods for a specific endpoint.
#   acceptAllMethod: "all"
#   # endpointBuckets provides regular expressions to use against the request 
#   # endpoint in order to group requests for a metric label.
#   endpointBuckets:
#     - "hook\\b"
#     - "hooks\\b"
#     - "device/.*/stat\\b"
#     - "device/.*/config\\b"


# WRPCheck provides the details needed to authorize incoming WRP message
# requests from partners against their credentials. The type can be "monitor" or "enforce".
# If "monitor" is provided, requests are authorized even when the WRP message has invalid
# credentials. If "enforce" is provided, such requests are rejected. For either type, transaction
# metrics are collected. If no valid type is provided, no checks are provided.
# Note: Enabling this check requires that only JWT Authentication is enabled as the source of
# truth for the authorization comes from the JWT claims allowedResources.allowedPartners
# (Optional)
# WRPCheck:
#   type: "enforce"

########################################
#   Service Discovery Configuration
########################################

# service configures the server for service discovery.
# defined https://godoc.org/github.com/xmidt-org/webpa-common/service/servicecfg#Options
# (Optional) defaults to not set.
# If set consul or fixed must be used. Using fixed is the same as setting fanout.endpoints.
service:
  # defaultScheme, used for the registered servers for communication.
  # (Optional) defaults to https
  defaultScheme: http

  # vnodeCount used for consistent hash calculation github.com/billhathaway/consistentHash.
  # number of virtual nodes. should be a prime number
  # it is a tradeoff of memory and ~ log(N) speed versus how well the hash spreads
  # (Optional) defaults to 211
  vnodeCount: 211

  # disableFilter disables filtering.
  # (Deprecated) does not do anything
  # disableFilter: false

  # fixed is the list of servers in the datacenter.
  # (Optional) default to empty list
  fixed:
    - http://localhost:6400
  # # consul configures consul for service discovery.
  # # defined https://godoc.org/github.com/xmidt-org/webpa-common/service/consul#Options
  # # (Optional) defaults define https://sourcegraph.com/github.com/hashicorp/consul/-/blob/api/api.go#L347
  # consul:
  #   # client is the configuration needed to connect to consul.
  #   # defined https://godoc.org/github.com/hashicorp/consul/api#Config
  #   client:
  #     # address is the address of the consul client or cluster.
  #     # (Optional) defaults to 127.0.0.1:8500
  #     address: "consul0:8500"
  #
  #     # scheme is the scheme to use for api calls to the consul agent.
  #     # (Optional) defaults to http
  #     scheme: "http"
  #
  #     # waitTime limits how long a Watch will block.
  #     # (Optional) defaults to 0s, aka wait forever before update
  #     waitTime: 30s
  #
  #   chrysom:
  #     listen:
  #       # pullInterval is how often to call argus to update the list of 
  #       # inactive datacenters.
  #       pullInterval: "5s"
  #
  #     # bucket to store and retrieve inactive datacenters.
  #     bucket: "inactive-dcs"
  #
  #     # address is the location to talk to argus.
  #     address: "http://localhost:6600"
  #
  #     # auth the authentication method for argus.
  #     auth:
  #       # basic configures basic authentication for argus.
  #       # Must be of form: 'Basic xyz=='
  #       basic: ""
  #
  #       # jwt configures jwt style authentication for argus.
  #       jwt:
  #         # requestHeaders are added to the request for the token.
  #         # (Optional)
  #         # requestHeaders:
  #         #   "": ""
  #
  #         # authURL is the URL to access for the token.
  #         authURL: 
  #
  #         # timeout is how long the request to get the token will take before
  #         # timing out.
  #         timeout: "1m"
  #
  #         # buffer is the length of time before a token expires to get a new token.
  #         buffer: "2m"
  #   # DisableGenerateID disables consul from generating the id.
  #   # (Optional) defaults to false
  #   disableGenerateID: true
  #
  #   # DatacenterRetries is the number of attempts to get the datacenters
  #   # (Optional) defaults to 10
  #   datacenterRetries: 3
  #
  #   # DatacenterWatchInterval is the interval at which scytale checks for a change 
  #   # in active datacenters.
  #   datacenterWatchInterval: 10s
  #
  #   # Registrations is a list of service(s) to register with consul.
  #   # defined https://godoc.org/github.com/hashicorp/consul/api#AgentServiceRegistration
  #   # (Optional) defaults to empty list
  #   registrations:
  #     - # id is the unique id for the service registration.
  #       id: "scytale-1"
  #
  #       # name is the service name.
  #       name: "scytale"
  #
  #       # tags are a list of strings that others talking to consul can use to
  #       # filter services.  These are meant to help in grouping similar
  #       # services in consul.
  #       # (Optional) defaults to empty list
  #       tags:
  #         - "dev"
  #         - "docker"
  #         - "stage=dev"
  #         - "flavor=docker"
  #
  #       # address tells consul where to contact the service.
  #       address: "https://scytale"
  #
  #       # scheme tells consul what scheme to use to contact the service.
  #       # This is used with the address for calls to this server.
  #       scheme: "http"
  #
  #       # port tells consul what port to use to contact the service.  This is
  #       # used with the address for calls to this server.
  #       port: 6300
  #
  #       # checks is a list of checks to see if the service is healthy.
  #       # defined https://godoc.org/github.com/hashicorp/consul/api#AgentServiceCheck
  #       # (Optional) defaults to empty list
  #       # Warning: if there are no checks, this service will stay around even
  #       # when it is in a bad state.  This will cause other healthy servers
  #       # to send requests that will fail.
  #       checks:
  #         - # CheckID is a unique id for the check.
  #           checkID: "scytlae-1:http"
  #
  #           # http tells consul to check via http rest request at the url
  #           # provided.
  #           http: "http://scytale:6301/health"
  #
  #           # interval is how often to check.
  #           interval: "30s"
  #
  #           # deregisterCriticalServiceAfter is how long to wait before this
  #           # service is considered bad.
  #           deregisterCriticalServiceAfter: "70s"
  #
  #   # Watches is a list of service(s) to watch from consul. The address of the
  #   # of the services are stored in memory. Upon update, the internal memory is
  #   # updated.
  #   # defined https://godoc.org/github.com/xmidt-org/webpa-common/service/consul#Watch
  #   # (Optional) defaults to empty list
  #   watches:
  #     - # service name to watch for updates.
  #       service: "talaria"
  #
  #       # tags is a list of strings that must be attached to the services
  #       # being watched.
  #       # (Optional) defaults to empty list
  #       tags:
  #         - "dev"
  #         - "docker"
  #
  #       # passingOnly determines if only services passing the consul check are returned.
  #       # (Optional) defaults to false
  #       passingOnly: true
  #
  #       # crossDatacenter determines if a watch should be created for each known datacenter which allows
  #       # scytale's fannout hash to work across all datacenters.
  #       # (Optional) defaults to false meaning a single watch is setup with the current datacenter.
  #       crossDatacenter: true
  #
  #       # queryOptions are options for the consul query, used in conjunction
  #       # with passingOnly.
  #       # defined by https://godoc.org/github.com/hashicorp/consul/api#QueryOptions
  #       # (Optional) defaults to empty struct
  #       # queryOptions:
  #       #   useCache: true

# tracing provides configuration around traces using OpenTelemetry.
# (Optional). By default, a 'noop' tracer provider is used and tracing is disabled.
tracing:
  # provider is the name of the trace provider to use. Currently, otlp/grpc, otlp/http, stdout, jaeger and zipkin are supported.
  # 'noop' can also be used as provider to explicitly disable tracing.
  provider: "noop"

  # skipTraceExport only applies when provider is stdout. Set skipTraceExport to true
  # so that trace information is not written to stdout.
  # skipTraceExport: true

  # endpoint is where trace information should be routed. Applies to otlp, zipkin, and jaegar. OTLP/gRPC uses port 4317 by default.
  # OTLP/HTTP uses port 4318 by default.
  # endpoint: "localhost:4317"
  
  # ParentBased and NoParent dictate if and when new spans should be created.
  # ParentBased = "ignore" (default), tracing is effectively turned off and the "NoParent" value is ignored
  # ParentBased = "honor", the sampling decision is made by the parent of the span
  parentBased: ignore

  # NoParent decides if a root span should be initiated in the case where there is no existing parent
  # This value is ignored if ParentBased = "ignore"
  # NoParent = "never" (default), root spans are not initiated
  # NoParent = "always", roots spans are initiated
  noParent: never

# previousVersionSupport allows us to support two different major versions of
# the API at the same time from the same application.  When this is true,
# scytale will support both "/v2" and "/v3" endpoints.  When false, only "/v3"
# endpoints will be supported.
previousVersionSupport: true