reference.asciidoc

API Reference

Packages

• marin3r.3scale.net/v1alpha1

• operator.marin3r.3scale.net/v1alpha1

marin3r.3scale.net/v1alpha1

Package v1alpha1 contains API Schema definitions for the envoy v1alpha1 API group

Resource Types

• EnvoyConfig

• EnvoyConfigList

• EnvoyConfigRevision

• EnvoyConfigRevisionList

Blueprint

Underlying type: string

Blueprint is an enum of the supported blueprints for generated resources

Appears In:

• Resource

ConfigRevisionRef

ConfigRevisionRef holds a reference to EnvoyConfigRevision object

Appears In:

• EnvoyConfigStatus

Field	Description	Default	Validation
version string	Version is a hash of the EnvoyResources field
ref ObjectReference	Ref is a reference to the EnvoyConfigRevision object that holds the configuration matching the Version field.

EnvoyConfig

EnvoyConfig holds the configuration for a given envoy nodeID. The spec of an EnvoyConfig object holds the Envoy resources that conform the desired configuration for the given nodeID and that the discovery service will send to any envoy client that identifies itself with that nodeID.

Appears In:

• EnvoyConfigList

Field	Description	Default	Validation
apiVersion string	marin3r.3scale.net/v1alpha1
kind string	EnvoyConfig
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec EnvoyConfigSpec
status EnvoyConfigStatus

EnvoyConfigList

EnvoyConfigList contains a list of EnvoyConfig

Field	Description	Default	Validation
apiVersion string	marin3r.3scale.net/v1alpha1
kind string	EnvoyConfigList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items EnvoyConfig array

EnvoyConfigRevision

EnvoyConfigRevision is an internal resource that stores a specific version of an EnvoyConfig resource. EnvoyConfigRevisions are automatically created and deleted by the EnvoyConfig controller and are not intended to be directly used. Use EnvoyConfig objects instead.

Appears In:

• EnvoyConfigRevisionList

Field	Description	Default	Validation
apiVersion string	marin3r.3scale.net/v1alpha1
kind string	EnvoyConfigRevision
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec EnvoyConfigRevisionSpec
status EnvoyConfigRevisionStatus

EnvoyConfigRevisionList

EnvoyConfigRevisionList contains a list of EnvoyConfigRevision

Field	Description	Default	Validation
apiVersion string	marin3r.3scale.net/v1alpha1
kind string	EnvoyConfigRevisionList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items EnvoyConfigRevision array

EnvoyConfigRevisionSpec

EnvoyConfigRevisionSpec defines the desired state of EnvoyConfigRevision

Appears In:

• EnvoyConfigRevision

Field	Description	Default	Validation
nodeID string	NodeID holds the envoy identifier for the discovery service to know which set of resources to send to each of the envoy clients that connect to it.
version string	Version is a hash of the EnvoyResources field
envoyAPI APIVersion	EnvoyAPI is the version of envoy’s API to use. Defaults to v3.		Enum: [v3]
serialization Serialization	Serialization specicifies the serialization format used to describe the resources. "json" and "yaml" are supported. "json" is used if unset.		Enum: [json b64json yaml]
envoyResources EnvoyResources	EnvoyResources holds the different types of resources suported by the envoy discovery service
resources Resource array	Resources holds the different types of resources suported by the envoy discovery service

EnvoyConfigRevisionStatus

EnvoyConfigRevisionStatus defines the observed state of EnvoyConfigRevision

Appears In:

• EnvoyConfigRevision

Field	Description	Default	Validation
published boolean	Published signals if the EnvoyConfigRevision is the one currently published in the xds server cache
providesVersions VersionTracker	ProvidesVersions keeps track of the version that this revision publishes in the xDS server for each resource type
lastPublishedAt Time	LastPublishedAt indicates the last time this config review transitioned to published
tainted boolean	Tainted indicates whether the EnvoyConfigRevision is eligible for publishing or not
conditions Condition array	Conditions represent the latest available observations of an object’s state

EnvoyConfigSpec

EnvoyConfigSpec defines the desired state of EnvoyConfig

Appears In:

• EnvoyConfig

Field	Description	Default	Validation
nodeID string	NodeID holds the envoy identifier for the discovery service to know which set of resources to send to each of the envoy clients that connect to it.
serialization Serialization	Serialization specicifies the serialization format used to describe the resources. "json" and "yaml" are supported. "json" is used if unset.		Enum: [json yaml]
envoyAPI APIVersion	EnvoyAPI is the version of envoy’s API to use. Defaults to v3.		Enum: [v3]
envoyResources EnvoyResources	EnvoyResources holds the different types of resources suported by the envoy discovery service DEPRECATED. Use the resources field instead.
resources Resource array	Resources holds the different types of resources suported by the envoy discovery service

EnvoyConfigStatus

EnvoyConfigStatus defines the observed state of EnvoyConfig

Appears In:

• EnvoyConfig

Field	Description	Default	Validation
cacheState string	CacheState summarizes all the observations about the EnvoyConfig to give the user a concrete idea on the general status of the discovery servie cache. It is intended only for human consumption. Other controllers should relly on conditions to determine the status of the discovery server cache.
publishedVersion string	PublishedVersion is the config version currently served by the envoy discovery service for the give nodeID
desiredVersion string	DesiredVersion represents the resources version described in the spec of the EnvoyConfig object
conditions Condition array	Conditions represent the latest available observations of an object’s state
revisions ConfigRevisionRef array	ConfigRevisions is an ordered list of references to EnvoyConfigRevision objects

EnvoyResource

EnvoyResource holds serialized representation of an envoy resource

Appears In:

• EnvoyResources

Field	Description	Default	Validation
name string	Name of the envoy resource. DEPRECATED: this field has no effect and will be removed in an upcoming release. The name of the resources for discovery purposes is included in the resource itself. Refer to the envoy API reference to check how the name is specified for each resource type.
value string	Value is the serialized representation of the envoy resource

EnvoyResources

EnvoyResources holds each envoy api resource type

Appears In:

• EnvoyConfigRevisionSpec

• EnvoyConfigSpec

Field	Description	Default	Validation
endpoints EnvoyResource array	Endpoints is a list of the envoy ClusterLoadAssignment resource type. API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/endpoint/v3/endpoint.proto
clusters EnvoyResource array	Clusters is a list of the envoy Cluster resource type. API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto
routes EnvoyResource array	Routes is a list of the envoy Route resource type. API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route.proto
scopedRoutes EnvoyResource array	ScopedRoutes is a list of the envoy ScopeRoute resource type. API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/scoped_route.proto
listeners EnvoyResource array	Listeners is a list of the envoy Listener resource type. API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto
runtimes EnvoyResource array	Runtimes is a list of the envoy Runtime resource type. API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/runtime/v3/rtds.proto
secrets EnvoySecretResource array	Secrets is a list of references to Kubernetes Secret objects.
extensionConfigs EnvoyResource array	ExtensionConfigs is a list of the envoy ExtensionConfig resource type API V3 reference: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/extension.proto

EnvoySecretResource

EnvoySecretResource holds a reference to a k8s Secret from where to take a secret from. Only Secrets within the same namespace can be referred.

Appears In:

• EnvoyResources

Field	Description	Default	Validation
name string	Name of the envoy tslCerticate secret resource. The certificate will be fetched from a Kubernetes Secrets of type 'kubernetes.io/tls' with this same name.
ref SecretReference	DEPRECATED: this field is deprecated and it’s value will be ignored. The 'name' of the Kubernetes Secret must match the 'name' field.

GenerateFromEndpointSlices

Appears In:

• Resource

Field	Description	Default	Validation
selector LabelSelector
clusterName string
targetPort string

Resource

Resource holds serialized representation of an envoy resource

Appears In:

• EnvoyConfigRevisionSpec

• EnvoyConfigSpec

Field	Description	Default	Validation
type Type	Type is the type url for the protobuf message		Enum: [listener route scopedRoute cluster endpoint secret runtime extensionConfig]
value RawExtension	Value is the protobufer message that configures the resource. The proto must match the envoy configuration API v3 specification for the given resource type (https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol#resource-types)
generateFromTlsSecret string	The name of a Kubernetes Secret of type "kubernetes.io/tls"
generateFromOpaqueSecret SecretKeySelector	The name of a Kubernetes Secret of type "Opaque". It will generate an envoy "generic secret" proto.
generateFromEndpointSlices GenerateFromEndpointSlices	Specifies a label selector to watch for EndpointSlices that will be used to generate the endpoint resource
blueprint Blueprint	Blueprint specifies a template to generate a configuration proto. It is currently only supported to generate secret configuration resources from k8s Secrets		Enum: [tlsCertificate validationContext]

SecretKeySelector

Appears In:

• Resource

Field	Description	Default	Validation
name string	The name of the secret in the pod’s namespace to select from.
key string	The key of the secret to select from. Must be a valid secret key.
alias string	A unique name to refer to the name:key combination

VersionTracker

VersionTracker tracks the versions of the resources that this revision publishes in the xDS server cache

Appears In:

• EnvoyConfigRevisionStatus

Field	Description	Default	Validation
endpoints string
clusters string
routes string
scopedRoutes string
listeners string
secrets string
runtimes string
extensionConfigs string

operator.marin3r.3scale.net/v1alpha1

Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group

Resource Types

• DiscoveryService

• DiscoveryServiceCertificate

• DiscoveryServiceCertificateList

• DiscoveryServiceList

• EnvoyDeployment

• EnvoyDeploymentList

CASignedConfig

CASignedConfig is used ti generate certificates signed by a CA contained in a Secret

Appears In:

• DiscoveryServiceCertificateSigner

Field	Description	Default	Validation
caSecretRef SecretReference	A reference to a Secret containing the CA

CertificateOptions

CertificateOptions specifies options to generate the server certificate used both for the xDS server and the mutating webhook server.

Appears In:

• PKIConfig

Field	Description	Default	Validation
secretName string
duration Duration

CertificateRenewalConfig

CertificateRenewalConfig configures the certificate renewal process.

Appears In:

• DiscoveryServiceCertificateSpec

Field	Description	Default	Validation
enabled boolean	Enabled is a flag to enable or disable renewal of the certificate

ContainerPort

ContainerPort defines port for the Marin3r sidecar container

Appears In:

• EnvoyDeploymentSpec

Field	Description	Default	Validation
name string	Port name
port integer	Port value
protocol Protocol	Protocol. Defaults to TCP.

DiscoveryService

DiscoveryService represents an envoy discovery service server. Only one instance per namespace is currently supported.

Appears In:

• DiscoveryServiceList

Field	Description	Default	Validation
apiVersion string	operator.marin3r.3scale.net/v1alpha1
kind string	DiscoveryService
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec DiscoveryServiceSpec
status DiscoveryServiceStatus

DiscoveryServiceCertificate

DiscoveryServiceCertificate is an internal resource used to create certificates. This resource is used by the DiscoveryService controller to create the required certificates for the different components. Direct use of DiscoveryServiceCertificate objects is discouraged.

Appears In:

• DiscoveryServiceCertificateList

Field	Description	Default	Validation
apiVersion string	operator.marin3r.3scale.net/v1alpha1
kind string	DiscoveryServiceCertificate
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec DiscoveryServiceCertificateSpec
status DiscoveryServiceCertificateStatus

DiscoveryServiceCertificateList

DiscoveryServiceCertificateList contains a list of DiscoveryServiceCertificate

Field	Description	Default	Validation
apiVersion string	operator.marin3r.3scale.net/v1alpha1
kind string	DiscoveryServiceCertificateList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items DiscoveryServiceCertificate array

DiscoveryServiceCertificateSigner

DiscoveryServiceCertificateSigner specifies the signer to use to provision the certificate

Appears In:

• DiscoveryServiceCertificateSpec

Field	Description	Default	Validation
selfSigned SelfSignedConfig	SelfSigned holds specific configuration for the SelfSigned signer		Optional: {}
caSigned CASignedConfig	CASigned holds specific configuration for the CASigned signer		Optional: {}

DiscoveryServiceCertificateSpec

DiscoveryServiceCertificateSpec defines the desired state of DiscoveryServiceCertificate

Appears In:

• DiscoveryServiceCertificate

Field	Description	Default	Validation
commonName string	CommonName is the CommonName of the certificate
server boolean	IsServerCertificate is a boolean specifying if the certificate should be issued with server auth usage enabled
isCA boolean	IsCA is a boolean specifying that the certificate is a CA
validFor integer	ValidFor specifies the validity of the certificate in seconds
hosts string array	Hosts is the list of hosts the certificate is valid for. Only use when 'IsServerCertificate' is true. If unset, the CommonName field will be used to populate the valid hosts of the certificate.
signer DiscoveryServiceCertificateSigner	Signer specifies the signer to use to create this certificate. Supported signers are CertManager and SelfSigned.
secretRef SecretReference	SecretRef is a reference to the secret that will hold the certificate and the private key.
certificateRenewal CertificateRenewalConfig	CertificateRenewalConfig configures the certificate renewal process. If unset default behavior is to renew the certificate but not notify of renewals.

DiscoveryServiceCertificateStatus

DiscoveryServiceCertificateStatus defines the observed state of DiscoveryServiceCertificate

Appears In:

• DiscoveryServiceCertificate

Field	Description	Default	Validation
ready boolean	Ready is a boolean that specifies if the certificate is ready to be used
notBefore Time	NotBefore is the time at which the certificate starts being valid
notAfter Time	NotAfter is the time at which the certificate expires
certificateHash string	CertificateHash stores the current hash of the certificate. It is used for other controllers to validate if a certificate has been re-issued.
conditions Condition array	Conditions represent the latest available observations of an object’s state

DiscoveryServiceList

DiscoveryServiceList contains a list of DiscoveryService

Field	Description	Default	Validation
apiVersion string	operator.marin3r.3scale.net/v1alpha1
kind string	DiscoveryServiceList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items DiscoveryService array

DiscoveryServiceSpec

DiscoveryServiceSpec defines the desired state of DiscoveryService

Appears In:

• DiscoveryService

Field	Description	Default	Validation
image string	Image holds the image to use for the discovery service Deployment
debug boolean	Debug enables debugging log level for the discovery service controllers. It is safe to use since secret data is never shown in the logs.
resources ResourceRequirements	Resources holds the Resource Requirements to use for the discovery service Deployment. When not set it defaults to no resource requests nor limits. CPU and Memory resources are supported.
pkiConfg PKIConfig	PKIConfig has configuration for the PKI that marin3r manages for the different certificates it requires
xdsServerPort integer	XdsServerPort is the port where the xDS server listens. Defaults to 18000.
metricsPort integer	MetricsPort is the port where metrics are served. Defaults to 8383.
probePort integer	ProbePort is the port where healthz endpoint is served. Defaults to 8384.
serviceConfig ServiceConfig	ServiceConfig configures the way the DiscoveryService endpoints are exposed
podPriorityClass string	PriorityClass to assign the discovery service Pod to
affinity Affinity	Affinity configuration for the discovery service pods

DiscoveryServiceStatus

DiscoveryServiceStatus defines the observed state of DiscoveryService

Appears In:

• DiscoveryService

Field	Description	Default	Validation
deploymentName string
deploymentStatus DeploymentStatus

DynamicReplicasSpec

Appears In:

• ReplicasSpec

Field	Description	Default	Validation
minReplicas integer	minReplicas is the lower limit for the number of replicas to which the autoscaler can scale down. It defaults to 1 pod. minReplicas is allowed to be 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available.
maxReplicas integer	maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up. It cannot be less that minReplicas.
metrics MetricSpec array	metrics contains the specifications for which to use to calculate the desired replica count (the maximum replica count across all metrics will be used). The desired replica count is calculated multiplying the ratio between the target value and the current value by the current number of pods. Ergo, metrics used must decrease as the pod count is increased, and vice-versa. See the individual metric source types for more information about how each type of metric must respond. If not set, the default metric will be set to 80% average CPU utilization.
behavior HorizontalPodAutoscalerBehavior	behavior configures the scaling behavior of the target in both Up and Down directions (scaleUp and scaleDown fields respectively). If not set, the default HPAScalingRules for scale up and scale down are used.

EnvoyDeployment

EnvoyDeployment is a resource to deploy and manage a Kubernetes Deployment of Envoy Pods.

Appears In:

• EnvoyDeploymentList

Field	Description	Default	Validation
apiVersion string	operator.marin3r.3scale.net/v1alpha1
kind string	EnvoyDeployment
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec EnvoyDeploymentSpec
status EnvoyDeploymentStatus

EnvoyDeploymentList

EnvoyDeploymentList contains a list of EnvoyDeployment

Field	Description	Default	Validation
apiVersion string	operator.marin3r.3scale.net/v1alpha1
kind string	EnvoyDeploymentList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items EnvoyDeployment array

EnvoyDeploymentSpec

EnvoyDeploymentSpec defines the desired state of EnvoyDeployment

Appears In:

• EnvoyDeployment

Field	Description	Default	Validation
envoyConfigRef string	EnvoyConfigRef points to an EnvoyConfig in the same namespace that holds the envoy resources for this Deployment
discoveryServiceRef string	DiscoveryServiceRef points to a DiscoveryService in the same namespace
clusterID string	Defines the local service cluster name where Envoy is running. Defaults to the NodeID in the EnvoyConfig if unset
ports ContainerPort array	Ports exposed by the Envoy container
image string	Image is the envoy image and tag to use
resources ResourceRequirements	Resources holds the resource requirements to use for the Envoy Deployment. Defaults to no resource requests nor limits.
duration Duration	Defines the duration of the client certificate that is used to authenticate with the DiscoveryService
extraArgs string array	Allows the user to define extra command line arguments for the Envoy process
adminPort integer	Configures envoy’s admin port. Defaults to 9901.
adminAccessLogPath string	Configures envoy’s admin access log path. Defaults to /dev/null.
replicas ReplicasSpec	Replicas configures the number of replicas in the Deployment. One of 'static', 'dynamic' can be set. If both are set, static has precedence.
livenessProbe ProbeSpec	Liveness probe for the envoy pods
readinessProbe ProbeSpec	Readiness probe for the envoy pods
affinity Affinity	Affinity configuration for the envoy pods
podDisruptionBudget PodDisruptionBudgetSpec	Configures PodDisruptionBudget for the envoy Pods
shutdownManager ShutdownManager	ShutdownManager defines configuration for Envoy’s shutdown manager, which handles graceful termination of Envoy pods
initManager InitManager	InitManager defines configuration for Envoy’s init manager, which handles initialization for Envoy pods

EnvoyDeploymentStatus

EnvoyDeploymentStatus defines the observed state of EnvoyDeployment

Appears In:

• EnvoyDeployment

Field	Description	Default	Validation
deploymentName string
deploymentStatus DeploymentStatus

InitManager

InitManager defines configuration for Envoy’s shutdown manager, which handles initialization for Envoy pods

Appears In:

• EnvoyDeploymentSpec

Field	Description	Default	Validation
image string	Image is the init manager image and tag to use

PKIConfig

PKIConfig has configuration for the PKI that marin3r manages for the different certificates it requires

Appears In:

• DiscoveryServiceSpec

Field	Description	Default	Validation
rootCertificateAuthority CertificateOptions
serverCertificate CertificateOptions

PodDisruptionBudgetSpec

PodDisruptionBudgetSpec defines the PDB for the component

Appears In:

• EnvoyDeploymentSpec

Field	Description	Default	Validation
minAvailable IntOrString	An eviction is allowed if at least "minAvailable" pods selected by "selector" will still be available after the eviction, i.e. even in the absence of the evicted pod. So for example you can prevent all voluntary evictions by specifying "100%".
maxUnavailable IntOrString	An eviction is allowed if at most "maxUnavailable" pods selected by "selector" are unavailable after the eviction, i.e. even in absence of the evicted pod. For example, one can prevent all voluntary evictions by specifying 0. This is a mutually exclusive setting with "minAvailable".

ProbeSpec

ProbeSpec specifies configuration for a probe

Appears In:

• EnvoyDeploymentSpec

Field	Description	Default	Validation
initialDelaySeconds integer	Number of seconds after the container has started before liveness probes are initiated
timeoutSeconds integer	Number of seconds after which the probe times out
periodSeconds integer	How often (in seconds) to perform the probe
successThreshold integer	Minimum consecutive successes for the probe to be considered successful after having failed
failureThreshold integer	Minimum consecutive failures for the probe to be considered failed after having succeeded

ReplicasSpec

ReplicasSpec configures the number of replicas of the Deployment

Appears In:

• EnvoyDeploymentSpec

Field	Description	Default	Validation
static integer	Configure a static number of replicas. Defaults to 1.
dynamic DynamicReplicasSpec	Configure a min and max value for the number of pods to autoscale dynamically.

SelfSignedConfig

SelfSignedConfig is an empty struct to refer to the selfsiged certificates provisioner

Appears In:

• DiscoveryServiceCertificateSigner

ServiceConfig

ServiceConfig has options to configure the way the Service is deployed

Appears In:

• DiscoveryServiceSpec

Field	Description	Default	Validation
name string
type ServiceType

ServiceType

Underlying type: string

ServiceType is an enum with the available discovery service Service types

Appears In:

• ServiceConfig

ShutdownManager

ShutdownManager defines configuration for Envoy’s shutdown manager, which handles graceful termination of Envoy Pods

Appears In:

• EnvoyDeploymentSpec

Field	Description	Default	Validation
image string	Image is the shutdown manager image and tag to use
serverPort integer	Configures the sutdown manager’s server port. Defaults to 8090.
drainTime integer	The time in seconds that Envoy will drain connections during shutdown. It also affects drain behaviour when listeners are modified or removed via LDS.
drainStrategy DrainStrategy	The drain strategy for the graceful shutdown. It also affects drain when listeners are modified or removed via LDS.		Enum: [gradual immediate]