apicast-crd-reference.md

APIcast Custom Resource reference

json/yaml field	Type	Required	Default value	Description
spec	APIcastSpec	Yes	See APIcastSpec	The specfication for Apicast custom resource
status	APIcastStatus	No	See APIcastStatus	The status for the custom resource

APIcastSpec

json/yaml field	Type	Required	Default value	Description
replicas	integer	No	1	Number of replica pods
adminPortalCredentialsRef	LocalObjectReference	No	N/A	Secret with the portal endpoint URL information. See AdminPortalSecret for required format
embeddedConfigurationSecretRef	LocalObjectReference	No	N/A	Secret containing the gateway configuration. See EmbeddedConfSecret for required format
serviceAccount	string	No	default service account	Service account associated to the gateway
image	string	No	Official apicast image	Apicast gateway container image. Only for devtesting purposes
exposedHost	APIcastExposedHost	No	No external access	Domain name used for external access
deploymentEnvironment	string	No	N/A	Environment for which the configuration (see docs)
dnsResolverAddress	string	No	N/A	DNS resolver (see docs)
enabledServices	[]string	No	N/A	List of service IDs used to filter the services configured (see docs)
configurationLoadMode	string	No	N/A	Defines how to load the configuration (see docs)
logLevel	string	No	N/A	Log level for the OpenResty logs (see docs)
pathRoutingEnabled	bool	No	N/A	When this parameter is set to true, the gateway will use path-based routing in addition to the default host-based routing (see docs)
responseCodesIncluded	bool	No	N/A	When set to true, APIcast will log the response code of the response returned by the API backend in 3scale (see docs)
cacheConfigurationSeconds	integer	No	N/A	Specifies the period (in seconds) that the configuration will be stored in the cache (see docs)
managementAPIScope	string	No	N/A	Apicast management API configuration control (see docs)
openSSLPeerVerificationEnabled	bool	No	N/A	Controls the OpenSSL Peer Verification (see docs)
resources	v1.ResourceRequirements	No	CPU [Request: 500m, Limit: 1], Memory [Request: 64Mi, Limit: 128Mi]	Resources describes the compute resource requirements
upstreamRetryCases	string	No	N/A	Specifies in which cases a request to the upstream API should be retried (see docs)
cacheMaxTime	string	No	1m	When the response is selected to be cached in the system, the value of this variable indicates the maximum time to be cached. If cache-control header is not set, the time to be cached will be the defined one. (see docs)
cacheStatusCodes	string	No	200 302	When the response code from upstream matches one of the status codes defined in this environment variable, the response content will be cached (see docs)
oidcLogLevel	string	No	err	Allows to set the log level for the logs related to OpenID Connect integration (see docs)
loadServicesWhenNeeded	bool	No	false	The configurations are loaded lazily (see docs)
servicesFilterByURL	string	No	N/A	Used to filter the service configured in the 3scale API Manager, the filter matches with the public base URL (Staging or production) (see docs)
serviceConfigurationVersionOverride	Service Configuration Version Override object	No	N/A	Service configuration version map to prevent it from auto-updating (see docs)
httpsPort	int	No	8443 only when httpsCertificateSecretRef is provided	Controls on which port APIcast should start listening for HTTPS connections. Do not use 8080 as HTTPS port (see docs)
httpsVerifyDepth	int	No	N/A	Defines the maximum length of the client certificate chain. (see docs)
httpsCertificateSecretRef	LocalObjectReference	No	APIcast has a default certificate used when httpsPort is provided	References secret containing the X.509 certificate in the PEM format and the X.509 certificate secret key
workers	integer	No	Automatically computed. Check apicast doc for further info.	Defines the number of worker processes
timezone	string	No	N/A	The local timezone of the APIcast deployment pods. Its value must be a compatible value with the tz database
customPolicies	[]CustomPolicySpec	No	N/A	List of custom policies
extendedMetrics	bool	No	false	Enables additional information on Prometheus metrics (see docs)
customEnvironments	[]CustomEnvironmentSpec	No	N/A	List of custom environments
openTracing	OpenTracingSpec	No	N/A	[DEPRECATED] Use openTelementry instead. Contains the OpenTracing integration configuration
allProxy	string	No	N/A	Specifies a HTTP(S) proxy to be used for connecting to services if a protocol-specific proxy is not specified. Authentication is not supported. Format is: <scheme>://<host>:<port> (see docs)
httpProxy	string	No	N/A	Specifies a HTTP(S) Proxy to be used for connecting to HTTP services. Authentication is not supported. Format is: <scheme>://<host>:<port> (see docs)
httpsProxy	string	No	N/A	Specifies a HTTP(S) Proxy to be used for connecting to HTTPS services. Authentication is not supported. Format is: <scheme>://<host>:<port> (see docs)
noProxy	string	No	N/A	Specifies a comma-separated list of hostnames and domain names for which the requests should not be proxied. Setting to a single * character, which matches all hosts, effectively disables the proxy (see docs)
serviceCacheSize	int	No	N/A	Specifies the number of services that APICast can store in the internal cache (see docs)
openTelemetry	OpenTelemetrySpec	No	N/A	contains the OpenTelemetry integration configuration
hpa	bool	No	N/A	When this parameter is set to true, Horizontal Pod Autoscaling will be enabled with default values, spec.replicas and resources limits and requests will be ignored

APIcastStatus

Used by the Operator/Kubernetes to control the state of the Apicast custom resource. It should never be modified by the user.

json/yaml field	Type	Description
image	string	The image being used in the APIcast deployment

APIcastExposedHost

json/yaml field	Type	Required	Default value	Description
host	string	Yes	N/A	Domain name being routed to the gateway
tls	[]networkv1.IngressTLS	No	N/A	Array of ingress TLS objects (see doc)

AdminPortalSecret

Field	Description
AdminPortalURL	URI that includes your password and 3scale Porta portal endpoint. See format

EmbeddedConfSecret

Field	Description
config.json	JSON file with the configuration for the gateway. See docs

Service Configuration Version Override Map

Field	Value
Service ID (string type)	The configuration version you can see in the configuration history on the Admin Portal (string type)

For example, fix service "2555417833738" to version "5" and service "2555417836536" to version "7":

spec:
  serviceConfigurationVersionOverride:
    "2555417833738": "5"
    "2555417836536": "7"

CustomPolicySpec

json/yaml field	Type	Required	Default value	Description
name	string	Yes	N/A	Name
version	string	Yes	N/A	Version
secretRef	LocalObjectReference	Yes	N/A	Secret reference with the policy content. See CustomPolicySecret for more information.

CustomPolicySecret

Contains custom policy specific content. Two files, init.lua and apicast-policy.json, are required, but more can be added optionally.

Some examples are available here

Field	Description
init.lua	Custom policy lua code entry point
apicast-policy.json	Custom policy metadata

CustomEnvironmentSpec

json/yaml field	Type	Required	Default value	Description
secretRef	LocalObjectReference	Yes	N/A	Secret reference with the custom environment content. See CustomEnvironmentSecret for more information.

CustomEnvironmentSecret

Generic (opaque) type secret holding one or more custom environments. The operator will load in the APIcast container all the files (keys) found in the secret.

Some examples are available here

Field	Description
filename	Custom environment lua code

OpenTracingSpec

json/yaml field	Type	Required	Default value	Description
enabled	bool	No	false	Controls whether OpenTracing integration with APIcast is enabled. By default it is not enabled
tracingLibrary	string	No	jaeger	Controls which OpenTracing library is loaded. At the moment the supported values are: jaeger. If not set, jaeger will be used
tracingConfigSecretRef	LocalObjectReference	No	tracing library-specific default	Secret reference with the tracing library-specific configuration. Each supported tracing library provides a default configuration file which is used if tracingConfigSecretRef is not specified. See TracingConfigSecret for more information.

TracingConfigSecret

Field	Description
config	Tracing library-specific configuration

Watch for secret changes

By default, content changes in the secret will not be noticed by the apicast operator. The apicast operator allows monitoring the secret for changes adding the apicast.apps.3scale.net/watched-by=apicast label. With that label in place, when the content of the secret is changed, the operator will get notified. Then, the operator will rollout apicast deployment to make the changes effective. The operator will not take ownership of the secret in any way.

kubectl label secret ${SOME_SECRET_NAME} apicast.apps.3scale.net/watched-by=apicast

OpenTelemetrySpec

json/yaml field	Type	Required	Default value	Description
enabled	bool	No	false	Controls whether opentelemetry based gateway instrumentation is enabled or not. By default it is disabled
tracingConfigSecretRef	LocalObjectReference	No	None	Secret reference with the opentelemetry tracing configuration.
tracingConfigSecretKey	string	No	If unspecified, the first secret key in lexicographical order will be referenced as tracing configuration	The secret key used as tracing configuration

Watch for secret changes

By default, content changes in the secret will not be noticed by the apicast operator. The apicast operator allows monitoring the secret for changes adding the apicast.apps.3scale.net/watched-by=apicast label. With that label in place, when the content of the secret is changed, the operator will get notified. Then, the operator will rollout apicast deployment to make the changes effective. The operator will not take ownership of the secret in any way.