Please Provide Examples directory with examples

[darkn3rd]

Please describe your use case / problem.

I would like to know how to take what knowledge I have with ingress resources (networking.k8s.io/v1) and convert this to the equivalent that uses Host, Listener, and Mapping. This comparative analysis approach would be the shortest path to help people learn how to use this, and from here, we could drop other examples.

There is a lack of examples that illustrate the core functionality of emissary-ingress making it hard to get started. The documentation is difficult to navigate and discern and is often a source of complaints in the community (example)

Should there be examples in the projects, people could get started regardless of the shape of the documentation.

Describe the solution you'd like

I would like to know how to take what knowledge I have with standard ingress resources (networking.k8s.io/v1) and convert this to the equivalent that uses Host, Listener, and Mapping. This comparative analysis approach would be the shortest path to help people learn how to use this, and from here, we could drop other examples in an examples directory organized by use cases related to core functionality, features, and integrations.

Describe alternatives you've considered

I have spent several days going through the documentation and I having difficulty getting started. My next option would be to start code diving to elicit out the functionality, or just abandon efforts with emissary-ingress and explore other solutions.

Additional context

Many other OSS projects are documentation-challenged as well and do provide examples for use cases and integrations. Some of these include ingress-nginx, external-dns

This would also encourage other people to drop examples for unique use cases or how-tos that have not yet been covered sufficiently.

[cindymullins-dw]

HI @darkn3rd , thanks for the suggestions! Emissary is built on Envoy and we appreciate there are challenges with getting familiar with using separately defined CRDs. Just to confirm, how did you find the Emissary quick start? It's meant to provide you with the essential CRDs (applied via either yaml or Helm). Did it give you a basic working configuration to start with?

I've heard from other users that building a mental model around how a Host, Mapping, and Listener work together is challenging. Did you also find that to be the case?

We do have a number of yaml examples in our docs - in particular the cookbook and also grpc and rewrites, etc. But a structure that allows for community-contributed examples is a great suggestion.