Improving the Istio Glossary

Over the past several weeks, we have been identifying terms that need to be
defined for our documentation to be as clear and accessible as possible.

To help us add clarity for newcomers without cluttering our docs for those who
are already familiar with Istio, @geeknoid enabled the {{< gloss >}}
shortcode to add a optional click-able message to specific terms. You can see
the shortcode in action providing the definition of TLS origination in a task.

A consistent implementation of the glossary in our docs will provide the
following advantages:

  • Defines a common terminology for the Istio community.
  • Provides a set of metadata tags to use on the content.
    • Improves site SEO.
    • Improves “See also” suggestions.
  • Helps establish an industry-wide standard terminology.

To achieve these goals, we must not only add entries to the glossary, but mark
up the first instance of every entry with the shortcode across the docs.

To track, plan, and execute this change, I have created Epic #3573
on the website’s repo, but …

We need your help!

If there is a term you want us to include in the
glossary, please create an Issue with the following format on GitHub:

Brief description:
Gloss: Add

Long description:

You can review the example
Issue created to add “Mesh Configuration Protocol”.

Please take the following actions when creating the Issue:

  • Take a look at the Epic and the Issues linked to it before adding a new issue
    to help us avoid duplicates.
  • Assign the Issue to rcaballeromx.
  • Apply the following labels to the Issue:
    • area/user experience
    • kind/docs
    • kind/enhancement
  • Link the issue to the Epic #3573
  • [Optional] Set the milestone to 1.2
  • [Optional] Set the estimate to 3, 8, or 21 depending on how complex the term
    is to define and how much discussion you believe there needs to be for the
    community to agree on a definition.

My ambitious goal is to complete these changes for Istio 1.2. If you have any
questions please reply to this post, or ping me (rcaballeromx@)
on Slack.

Mainly I think there is confusion about Istio Ingress Gateway and the gateway that configures the Istio Ingress Gateway. Clear separation of terminology for the gateways is important. Load balancer, gateway, istio gateway and what are the differences. Which does what. The other issue I have encountered with Istio and Envoy documentation is not much coverage if you are running Kubernetes on docker. I am running booklist demo on Docker for Mac Edge edition. And the docs only cover running booklist from Docker Consul. Generally where Docker needs to be covered more in-depth is are there any special things that need to be done to expose a service externally when you are in docker. I have spent the last 24 hours trying to get the booklist demo working end to end on the Docker Edge/Kubernetes environment. I have followed the documentation as best I could but I have not been able to reach any services from the outside on a browser or with curl. A demo only is working if you can reach the service end to end, and that last mile I think there needs to be more coverage of any docker issues. I am guessing I am not alone in running the demos getting everything internally working and then I cannot curl the service from the outside. This last mile is really really important. It might be as simple as opening a port on Docker but what I am seeing is not failure to connect but no response. There also is not really a lot of documentation of how to troubleshoot these very common issues. I mean do you think everyone is successful in getting to reach the service after deploying the app on Istio? Where are the logs for this type of thing that would show a user why a connection “from the outside” did not reach a service?

How did you determine the ingress IP and port you are using. Did you follow these instructions?

I believe you should be using a nodeport with the Docker for Desktop command to get the INGRESS_HOST. You can look at the istio-ingressgateway logs to see if your request is even hitting the gateway.