Emissary Configuration

1: Emissary Ingress
2: v3.0.0
3: v3.3.0
4: v3.9.1

Emissary Ingress is an open-source Kubernetes-native API Gateway + Layer 7 load balancer + Kubernetes Ingress built on Envoy Proxy.

Best Practice

Any supported EKS Anywhere curated package should be modified through package yaml files (with kind: Package) and applied through the command kubectl apply -f packageFileName. Modifying objects outside of package yaml files may lead to unpredictable behaviors.

For automatic namespace (targetNamespace) creation, see createNamespace field: PackagebundleController.spec

Configuration options for Emissary

1 - Emissary Ingress

Install/upgrade/uninstall Emissary Ingress

If you have not already done so, make sure your cluster meets the package prerequisites. Be sure to refer to the troubleshooting guide in the event of a problem.

Important

Starting at eksctl anywhere version v0.12.0, packages on workload clusters are remotely managed by the management cluster.
While following this guide to install packages on a workload cluster, please make sure the kubeconfig is pointing to the management cluster that was used to create the workload cluster. The only exception is the kubectl create namespace command below, which should be run with kubeconfig pointing to the workload cluster.
The emissary-apiext service has a known issue where its TLS certificate expires after one year and does not auto-renew. To resolve this, manually renew the certificate by running kubectl delete --all secrets --namespace=emissary-system followed by kubectl rollout restart deploy/emissary-apiext -n emissary-system prior to certificate expiry.

Install

Generate the package configuration

eksctl anywhere generate package emissary --cluster <cluster-name> > emissary.yaml

Add the desired configuration to emissary.yaml

Please see complete configuration options for all configuration options and their default values.

Example package file with standard configuration.

apiVersion: packages.eks.amazonaws.com/v1alpha1
kind: Package
metadata:
  name: emissary
  namespace: eksa-packages-<cluster-name>
spec:
  packageName: emissary

Install Emissary

eksctl anywhere create packages -f emissary.yaml

Validate the installation

eksctl anywhere get packages --cluster <cluster-name>

Example command output

NAMESPACE     NAME       PACKAGE    AGE     STATE       CURRENTVERSION                                   TARGETVERSION                                              DETAIL
eksa-packages emissary   emissary   2m57s   installed   3.0.0-a507e09c2a92c83d65737835f6bac03b9b341467   3.0.0-a507e09c2a92c83d65737835f6bac03b9b341467 (latest)

Update

To update package configuration, update emissary.yaml file, and run the following command:

eksctl anywhere apply package -f emissary.yaml

Upgrade

Emissary will automatically be upgraded when a new bundle is activated.

Uninstall

To uninstall Emissary, simply delete the package

eksctl anywhere delete package --cluster <cluster-name> emissary

2 - v3.0.0

Configuring Emissary Ingress in EKS Anywhere package spec

Parameter	Description	Default
General
hostNetwork	Whether Emissary will use the host network, useful for on-premise setup . Example: hostNetwork: false	false
createDefaultListeners	Whether Emissary should be created with default listeners, HTTP on port 8080 and HTTPS on port 8443. Example: createDefaultListeners: false	false
replicaCount	Replica count for Emissary to deploy. Example: replicaCount: 2	2
daemonSet	Whether to create Emissary as a Daemonset instead of a deployment Example: daemonSet: false	false

3 - v3.3.0

Emissary version 0.3.3 has decoupled the CRD portion of the package, and now supports installing multiple instances of the emissary package in the same cluster.

Configuring Emissary Ingress in EKS Anywhere package spec

Parameter	Description	Default
General
hostNetwork	Whether Emissary will use the host network, useful for on-premise setup . Example: hostNetwork: false	false
createDefaultListeners	Whether Emissary should be created with default listeners, HTTP on port 8080 and HTTPS on port 8443. Example: createDefaultListeners: false	false
replicaCount	Replica count for Emissary to deploy. Example: replicaCount: 2	2
daemonSet	Whether to create Emissary as a Daemonset instead of a deployment Example: daemonSet: false	false

4 - v3.9.1

Emissary version 3.9.1 has decoupled the CRD portion of the package, and now supports installing multiple instances of the emissary package in the same cluster.

Configuring Emissary Ingress in EKS Anywhere package spec

Parameter	Description	Default
General
hostNetwork	Whether Emissary will use the host network, useful for on-premise setup . Example: hostNetwork: false	false
createDefaultListeners	Whether Emissary should be created with default listeners, HTTP on port 8080 and HTTPS on port 8443. Example: createDefaultListeners: false	false
replicaCount	Replica count for Emissary to deploy. Example: replicaCount: 2	2
daemonSet	Whether to create Emissary as a Daemonset instead of a deployment Example: daemonSet: false	false