command module
Version: v0.8.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jul 30, 2021 License: Apache-2.0 Imports: 1 Imported by: 0



Go Report Card codecov build license

Lighweight, CRD based Envoy control plane for Kubernetes:

  • Implemented as a Kubernetes Operator
  • Deploy and manage an Envoy xDS server using the DiscoveryService custom resource
  • Inject Envoy sidecar containers based on Pod annotations
  • Deploy Envoy as a Kubernetes Deployment using the EnvoyDeployment custom resource
  • Dynamic Envoy configuration using the EnvoyConfig custom resource
  • Use any secret of type as a certificate source
  • Syntactic validation of Envoy configurations
  • Self-healing
  • Controls Envoy connnection draining and graceful shutdown whenever pods are terminated

Table of Contents


MARIN3R is a Kubernetes operator to manage a fleet of Envoy proxies within a Kubernetes cluster. It takes care of the deployment of the proxies and manages their configuration, feeding it to them through a discovery service using Envoy's xDS protocol. This allows for dynamic reconfiguration of the proxies without any reloads or restarts, favoring the ability to perform configuration changes in a non-disruptive way.

Users can write their Envoy configurations by making use of Kubernetes Custom Resources that the operator will watch and make available to the proxies through the discovery service. Configurations are defined making direct use of Envoy's v2/v3 APIs so anything supported in the Envoy APIs is available in MARIN3R. See the configuration section or the API reference for more details.

A great way to use this project is to have your own operator generating the Envoy configurations that your platform/service requires by making use of MARIN3R APIs. This way you can just focus on developing the Envoy configurations you need and let MARIN3R take care of the rest.

Getting started


MARIN3R can be installed either by using kustomize or by using Operator Lifecycle Manager (OLM). We recommend using OLM installation whenever possible.

Install using OLM

OLM is installed by default in Openshift 4.x clusters. For any other Kubernetes flavor, check if it is already installed in your cluster. If not, you can easily do so by following the OLM install guide.

Once OLM is installed in your cluster, you can proceed with the operator installation by applying the install manifests. This will create a namespaced install of MARIN3R that will only watch for resources in the default namespace, with the operator deployed in the marin3r-system namespace. Modify the field spec.targetNamespaces of the OperatorGroup resource in examples/quickstart/olm-install.yaml to modify the namespaces that MARIN3R will watch. A cluster scoped installation through OLM is currently not supported (check the kustomize based installation for cluster scope installation of the operator).

kubectl apply -f examples/quickstart/olm-install.yaml

Wait until you see the following Pods running:

▶ kubectl -n marin3r-system get pods | grep Running
marin3r-catalog-qsx9t                                             1/1     Running     0          103s
marin3r-controller-manager-5f97f86fc5-qbp6d                       2/2     Running     0          42s
marin3r-controller-webhook-5d4d855859-67zr6                       1/1     Running     0          42s
marin3r-controller-webhook-5d4d855859-6972h                       1/1     Running     0          42s
Install using kustomize

This method will install MARIN3R with cluster scope permissions in your cluster. It requires cert-manager to be present in the cluster.

To install cert-manager you can execute the following command in the root directory of this repository:

make deploy-cert-manager

You can also refer to the cert-manager install documentation.

Once cert-manager is available in the cluster, you can install MARIN3R by issuing the following command:

kustomize build config/default | kubectl apply -f -

After a while you should see the following Pods running:

▶ kubectl -n marin3r-system get pods
NAME                                          READY   STATUS    RESTARTS   AGE
marin3r-controller-manager-6c45f7675f-cs6dq   2/2     Running   0          31s
marin3r-controller-webhook-684bf5bbfd-cp2x4   1/1     Running   0          31s
marin3r-controller-webhook-684bf5bbfd-zdvrk   1/1     Running   0          31s

Deploy a discovery service

A discovery service is a Pod that users need to deploy in their namespaces to provide such namespaces with the ability to configure Envoy proxies dynamically using configurations loaded from Kubernetes Custom Resources. This Pod runs a couple of Kubernetes controllers as well as an Envoy xDS server. To deploy a discovery service users make use of the DiscoveryService custom resource that MARIN3R provides. The DiscoveryService is a namespace scoped resource, so one is required for each namespace where Envoy proxies are going to be deployed.

Continuing with our example, we are going to deploy a DiscoveryService resource in the default namespace of our cluster:

cat <<'EOF' | kubectl apply -f -
kind: DiscoveryService
  name: discoveryservice
  namespace: default

After a while you should see the discovery service Pod running:

▶ kubectl -n default get pods
NAME                                READY   STATUS    RESTARTS   AGE
marin3r-discoveryservice-676b5cd7db-xk9rt   1/1     Running   0          4s

Next steps

After installing the operator and deploying a DiscoveryService into a namespace, you are ready to start deploying and configuring Envoy proxies within the namespace. You can review the different walkthroughs within this repo to learn more about MARIN3R and its capabilities.


API reference

The full MARIN3R API reference can be found here

EnvoyConfig custom resource

MARIN3R most core functionality is to feed the Envoy configurations defined in EnvoyConfig custom resources to an Envoy discovery service. The discovery service then sends the resources contained in those configurations to the Envoy proxies that identify themselves with the same nodeID defined in the EnvoyConfig resource.

Commented example of an EnvoyConfig resource:

cat <<'EOF' | kubectl apply -f -
kind: EnvoyConfig
  # name and namespace uniquelly identify an EnvoyConfig but are
  # not relevant in any other way
  name: config
  # nodeID indicates that the resources defined in this EnvoyConfig are relevant
  # to Envoy proxies that identify themselves to the discovery service with the same
  # nodeID. The nodeID of an Envoy proxy can be specified using the "--node-id" command
  # line flag
  nodeID: proxy
  # Resources can be written either in json or in yaml, being json the default if
  # not specified
  serialization: json
  # Resources can be written using either v2 Envoy API or v3 Envoy API. Mixing v2 and v3 resources
  # in the same EnvoyConfig is not allowed. Default is v2.
  envoyAPI: v3
  # envoyResources is where users can write the different type of resources supported by MARIN3R
    # the "secrets" field holds references to Kubernetes Secrets. Only Secrets of type
    # "" can be referenced. Any certificate referenced from another Envoy
    # resource (for example a listener or a cluster) needs to be present here so marin3r
    # knows where to get the certificate from.
        # name is the name of the kubernetes Secret that holds the certificate and by which it can be 
        # referenced to from other resources
      - name: certificate
    # Endpoints is a list of the Envoy ClusterLoadAssignment resource type.
    # V2 reference:
    # V3 reference:
      - name: endpoint1
        value: {"clusterName":"cluster1","endpoints":[{"lbEndpoints":[{"endpoint":{"address":{"socketAddress":{"address":"","portValue":8080}}}}]}]}
    # Clusters is a list of the Envoy Cluster resource type.
    # V2 reference:
    # V3 reference:
      - name: cluster1
        value: {"name":"cluster1","type":"STRICT_DNS","connectTimeout":"2s","loadAssignment":{"clusterName":"cluster1","endpoints":[]}}
    # Routes is a list of the Envoy Route resource type.
    # V2 reference:
    # V3 reference:
      - name: route1
        value: {"name":"route1","virtual_hosts":[{"name":"vhost","domains":["*"],"routes":[{"match":{"prefix":"/"},"direct_response":{"status":200}}]}]}
    # Listeners is a list of the Envoy Listener resource type.
    # V2 referece:
    # V3 reference:
      - name: listener1
        value: {"name":"listener1","address":{"socketAddress":{"address":"","portValue":8443}}}
    # Runtimes is a list of the Envoy Runtime resource type.
    # V2 reference:
    # V3 reference:
      - name: runtime1
        value: {"name":"runtime1","layer":{"static_layer_0":"value"}}


Secrets are treated in a special way by MARIN3R as they contain sensitive information. Instead of directly declaring an Envoy API secret resource in the EnvoyConfig CR, you have to reference a Kubernetes Secret, which should exists in the same namespace. MARIN3R expects this Secret to be of type and will load it into an Envoy secret resource. This way you avoid having to insert sensitive data into the EnvoyConfig resources and allows you to use your regular kubernetes Secret management workflow for sensitive data.

Other approach that can be used is to create certificates using cert-manager because cert-manager also uses Secrets to store the certificates it generates. You just need to point the references in your EnvoyConfig to the proper cert-manager generated Secret.

To use a certificate from a kubernetes Secret refer it like this from an EnvoyConfig:

      - name: certificate

This certificate can then be referenced in an Envoy cluster/listener with the following snippet (check the kuard example):

  name: envoy.transport_sockets.tls
    "@type": ""
        - name: certificate
            ads: {}

Sidecar injection configuration

The MARIN3R mutating admission webhook will inject Envoy containers in any Pod annotated with and labelled with The following annotations can be used in Pods to control the behavior of the sidecar injection:

annotations description default value Envoy's node-id N/A Envoy's cluster-id same as node-id Envoy's API version (v2/v3) v2 the name of the Envoy sidecar envoy-sidecar the exposed ports in the Envoy sidecar N/A Envoy sidecar ports that will be mapped to the host. This is used for local development, no recommended for production use. N/A the Envoy image to be used in the injected sidecar container envoyproxy/envoy:v1.14.1 the Pod volume where the ads-configmap will be mounted envoy-sidecar-bootstrap the Pod volume where the marin3r client certificate will be mounted. envoy-sidecar-tls the marin3r client certificate to use to authenticate to the marin3r control plane (marin3r uses mTLS)) envoy-sidecar-client-cert extra command line arguments to pass to the Envoy sidecar container "" Envoy's admin port 9901 Envoy sidecar container resource cpu limits. See syntax format to specify the resource quantity N/A Envoy's admin api port 9901 Envoy's admin api bind address Envoy's admin api access logs path /dev/null Envoy sidecar container resource memory limits. See syntax format to specify the resource quantity N/A Envoy sidecar container resource cpu requests. See syntax format to specify the resource quantity N/A Envoy sidecar container resource memory requests. See syntax format to specify the resource quantity N/A Enable or disables Envoy shutdown manager for graceful shutdown of the Envoy server (true/false) false Envoy's shutdown manager server port 8090 Envoy's shutdown manager image If unset, the operator will select the appropriate image Envoy's init manager image If unset, the operator will select the appropriate image Comma separated list of container names whose stop should be coordinated with the shutdown-manager. You usually would want to add containers that act as upstream clusters for the Envoy sidecar N/A syntax

The port syntax is a comma-separated list of name:port[:protocol] as in "envoy-http:1080,envoy-https:1443". syntax

The host-port-mappings syntax is a comma-separated list of container-port-name:host-port-number as in "envoy-http:1080,envoy-https:1443".

Use cases


Design docs

For an in-depth look at how MARIN3R works, check the design docs.

Discovery service

Sidecar injection



You can find development documentation here.


You can find release process documentation here.


The Go Gopher

There is no documentation for this package.

Source Files


Path Synopsis
Package v1alpha1 contains API Schema definitions for the envoy v1alpha1 API group +kubebuilder:object:generate=true
Package v1alpha1 contains API Schema definitions for the envoy v1alpha1 API group +kubebuilder:object:generate=true
Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group +kubebuilder:object:generate=true
Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group +kubebuilder:object:generate=true

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL