Telemetry
microgateway.airlock.com/v1alpha1
Telemetry defines the telemetry configuration (logging, metrics & tracing).
Telemetry
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| metadata | defines the resource’s metadata | ObjectMeta | yes | ||
| spec | defines the desired telemetry configuration. | object | no |
Telemetry.spec
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| correlation | configures behaviors which allow the downstream client to provide correlation identifiers. | object | no | ||
| logging | configures the logging behavior. | object | no | ||
| tracing | configures trace sampling and exporting. If not specified, tracing is disabled. | object | no |
Telemetry.spec.correlation
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| idSource | specifies how an external correlation ID should be obtained for a request. If not specified, no correlation ID will be logged. | object | no |
Telemetry.spec.correlation.idSource
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| header | specifies to extract the correlation ID from a request header. If the header is absent from a request, no correlation ID will be logged. | object | yes |
Telemetry.spec.correlation.idSource.header
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| name | of the header (case-insensitive) from which to extract the correlation ID. | string | no | X-Correlation-Id |
Telemetry.spec.logging
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| accessLog | defines the access log settings of Telemetry. | object | no |
Telemetry.spec.logging.accessLog
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| format | defines the Microgateway Engine access log format. | object | no |
Telemetry.spec.logging.accessLog.format
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| json | defines the Access Log format as JSON. | unstructured | no |
Telemetry.spec.tracing
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| provider | configures the tracing provider. | object | yes | openTelemetry{} |
Telemetry.spec.tracing.provider
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| openTelemetry | configures tracing using the OpenTelemetry provider. | object | no |
Telemetry.spec.tracing.provider.openTelemetry
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| exporter | configures how spans are exported. | object | yes | grpcEndpoint{}, httpEndpoint{} |
|
| sampling | configures the sampling rules. | object | yes | ||
| serviceName | defines the name for the service attribute defined in https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/. This will be populated in the ResourceSpan Resource attributes. If it is not provided, it will default to <name>.<namespace> from the Gateway CR. |
string | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| grpcEndpoint | configures exporting spans over gRPC. | object | no | ||
| httpEndpoint | configures exporting spans over HTTP. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| timeouts | specifies the timeouts when interacting with the Token endpoint. | object | no | ||
| tls | defines TLS settings. | object | no | ||
| uri | specifies the endpoint address. | string | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| certificateVerification | specifies how the certificate presented by the server is verified. | object | no | publicCAs{...} |
custom{}, disabled{}, publicCAs{} |
| ciphers | defines a list of the supported TLS cipher suites. For details on cipher list refer to the envoy documentation on cipher_suites in common tls configuration. | string[] | no | ||
| protocol | defines the supported TLS protocol versions. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| custom | explicitly specifies how the server certificate should be verified. Typical use cases include specifying a custom CA and SAN match when working with self-signed certificates or pinning a specific public key. |
object | no | ||
| disabled | specifies to trust any certificate without verification. THIS IS INSECURE AND SHOULD ONLY BE USED FOR TESTING. |
object | no | {} |
|
| publicCAs | specifies to only accept certificates with a SAN matching “uri” and which are signed by a CA which is either directly or indirectly trusted by any of the root CA certificates shipped with the Airlock Microgateway Engine’s base image. | object | no | {} |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| allowedSANs | is a list of matchers to verify the Subject Alternative name. If specified, it will verify that the Subject Alternative Name of the presented certificate matches one of the specified matchers. The matching uses “any” semantics, that is to say, the SAN is verified if at least one matcher is matched. AllowedSANs requires trustedCA to be set. |
object[] | no | ||
| certificatePinning | defines constraints the presented certificate must fulfill. If more than one constraint is configured only one must be satisfied. At least one of allowedSPKIs and allowedHashes must be set. |
object | no | ||
| crl | defines the Certificate Revocation List (CRL) settings. | object | no | ||
| trustedCA | defines which CA certificates are trusted. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.allowedSANs[]
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| matcher | defines the string matcher for the SAN value. | object | yes | contains{}, exact{}, prefix{}, regex{}, suffix{} |
|
| sanType | defines the type of SAN matcher. | enum | yes | DNS, Email, IPAddress, URI |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.allowedSANs[].matcher
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| contains | defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| exact | defines an explicit match on the string specified here. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| ignoreCase | indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). |
bool | no | false |
true, false |
| prefix | defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| regex | defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used. The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| suffix | defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.crl
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| lists | defines the list of secretRefs containing Certificate Revocation Lists. | object[] | no | ||
| validationMode | defines whether only the leaf certificate or also the CA certs should be checked. | enum | no | VerifyChain |
VerifyChain, VerifyLeafCertOnly |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.crl.lists[]
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| secretRef | defines the reference to a secret containing one or more CRL’s (in PEM format) under the key ‘ca.crl’. | object | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.crl.lists[].secretRef
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| name | of the resource | string | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.certificatePinning
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| allowedHashes | is a list of hex-encoded SHA-256 hashes. If specified, it will verify that the SHA-256 of the DER-encoded presented certificate matches one of the specified values. |
string[] | no | ||
| allowedSPKIs | is a list of base64-encoded SHA-256 hashes. If specified, it will verify that the SHA-256 of the DER-encoded Subject Public Key Information (SPKI) of the presented certificate matches one of the specified values. |
string[] | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.trustedCA
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| certificates | defines the list of secretRefs containing trusted CA certificates. | object[] | yes | ||
| verificationDepth | specifies the hops in the certificate chain at which validation is performed. 1 means that either the leaf or the signing CA must be in the set of trusted certificates. |
int32 | no | 1 |
[0, 2147483647] |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.trustedCA.certificates[]
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| secretRef | defines the reference to a secret containing one or more CA certificates under the key ‘ca.crt’. | object | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.certificateVerification.custom.trustedCA.certificates[].secretRef
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| name | of the resource | string | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.tls.protocol
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| maximum | supported TLS version. | enum | no | TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 |
|
| minimum | supported TLS version. | enum | no | TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 |
Telemetry.spec.tracing.provider.openTelemetry.exporter.grpcEndpoint.timeouts
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| connect | specifies the timeout for establishing a connection. | string (duration) | no | 5s |
See link |
| maxDuration | specifies the response timeout. | string (duration) | no | 15s |
See link |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| timeouts | specifies the timeouts when interacting with the Token endpoint. | object | no | ||
| tls | defines TLS settings. | object | no | ||
| uri | specifies the endpoint address. | string | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| certificateVerification | specifies how the certificate presented by the server is verified. | object | no | publicCAs{...} |
custom{}, disabled{}, publicCAs{} |
| ciphers | defines a list of the supported TLS cipher suites. For details on cipher list refer to the envoy documentation on cipher_suites in common tls configuration. | string[] | no | ||
| protocol | defines the supported TLS protocol versions. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| custom | explicitly specifies how the server certificate should be verified. Typical use cases include specifying a custom CA and SAN match when working with self-signed certificates or pinning a specific public key. |
object | no | ||
| disabled | specifies to trust any certificate without verification. THIS IS INSECURE AND SHOULD ONLY BE USED FOR TESTING. |
object | no | {} |
|
| publicCAs | specifies to only accept certificates with a SAN matching “uri” and which are signed by a CA which is either directly or indirectly trusted by any of the root CA certificates shipped with the Airlock Microgateway Engine’s base image. | object | no | {} |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| allowedSANs | is a list of matchers to verify the Subject Alternative name. If specified, it will verify that the Subject Alternative Name of the presented certificate matches one of the specified matchers. The matching uses “any” semantics, that is to say, the SAN is verified if at least one matcher is matched. AllowedSANs requires trustedCA to be set. |
object[] | no | ||
| certificatePinning | defines constraints the presented certificate must fulfill. If more than one constraint is configured only one must be satisfied. At least one of allowedSPKIs and allowedHashes must be set. |
object | no | ||
| crl | defines the Certificate Revocation List (CRL) settings. | object | no | ||
| trustedCA | defines which CA certificates are trusted. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.allowedSANs[]
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| matcher | defines the string matcher for the SAN value. | object | yes | contains{}, exact{}, prefix{}, regex{}, suffix{} |
|
| sanType | defines the type of SAN matcher. | enum | yes | DNS, Email, IPAddress, URI |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.allowedSANs[].matcher
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| contains | defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| exact | defines an explicit match on the string specified here. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| ignoreCase | indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). |
bool | no | false |
true, false |
| prefix | defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| regex | defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used. The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no | ||
| suffix | defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set. |
string | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.crl
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| lists | defines the list of secretRefs containing Certificate Revocation Lists. | object[] | no | ||
| validationMode | defines whether only the leaf certificate or also the CA certs should be checked. | enum | no | VerifyChain |
VerifyChain, VerifyLeafCertOnly |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.crl.lists[]
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| secretRef | defines the reference to a secret containing one or more CRL’s (in PEM format) under the key ‘ca.crl’. | object | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.crl.lists[].secretRef
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| name | of the resource | string | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.certificatePinning
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| allowedHashes | is a list of hex-encoded SHA-256 hashes. If specified, it will verify that the SHA-256 of the DER-encoded presented certificate matches one of the specified values. |
string[] | no | ||
| allowedSPKIs | is a list of base64-encoded SHA-256 hashes. If specified, it will verify that the SHA-256 of the DER-encoded Subject Public Key Information (SPKI) of the presented certificate matches one of the specified values. |
string[] | no |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.trustedCA
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| certificates | defines the list of secretRefs containing trusted CA certificates. | object[] | yes | ||
| verificationDepth | specifies the hops in the certificate chain at which validation is performed. 1 means that either the leaf or the signing CA must be in the set of trusted certificates. |
int32 | no | 1 |
[0, 2147483647] |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.trustedCA.certificates[]
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| secretRef | defines the reference to a secret containing one or more CA certificates under the key ‘ca.crt’. | object | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.certificateVerification.custom.trustedCA.certificates[].secretRef
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| name | of the resource | string | yes |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.tls.protocol
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| maximum | supported TLS version. | enum | no | TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 |
|
| minimum | supported TLS version. | enum | no | TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 |
Telemetry.spec.tracing.provider.openTelemetry.exporter.httpEndpoint.timeouts
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| connect | specifies the timeout for establishing a connection. | string (duration) | no | 5s |
See link |
| maxDuration | specifies the response timeout. | string (duration) | no | 15s |
See link |
Telemetry.spec.tracing.provider.openTelemetry.sampling
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| strategy | for when to sample. | object | yes | always{}, inheritParentDecision{}, random{} |
Telemetry.spec.tracing.provider.openTelemetry.sampling.strategy
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| always | will sample a span on every request. | object | no | {} |
|
| inheritParentDecision | strategy will inherit the sampling decision from the parent span. If there is none, the span will be sampled with the configured fallback strategy. | object | no | ||
| random | will sample a span with the configured probability. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.sampling.strategy.inheritParentDecision
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| fallbackStrategy | for when to sample requests if there is no parent span. | object | yes | always{}, never{}, random{} |
Telemetry.spec.tracing.provider.openTelemetry.sampling.strategy.inheritParentDecision.fallbackStrategy
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| always | will sample a span on every request. | object | no | {} |
|
| never | disables sampling. | object | no | {} |
|
| random | will sample a span with the configured probability. | object | no |
Telemetry.spec.tracing.provider.openTelemetry.sampling.strategy.inheritParentDecision.fallbackStrategy.random
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| probability | in % that a span is sampled. A valid value for probability must be from the range: [ 0.01%,99.99%] |
string | yes |
Telemetry.spec.tracing.provider.openTelemetry.sampling.strategy.random
| Field | Description | Type | Required | Default | Allowed Values |
|---|---|---|---|---|---|
| probability | in % that a span is sampled. A valid value for probability must be from the range: [ 0.01%,99.99%] |
string | yes |