User guide documentation issues

[derrickburns]

For a newbie looking at the Gloo documentation, there are a few things that make it difficult to follow. Here are some examples:

1. glooctl get upstream default-petstore-8080 --output yaml also shows some output deduced from Swagger. I would love to see the Swagger source. A simple google search did not yield the Swagger data. I know (from other experience) that it is served by the application. Where is the source to the example, listed in https://raw.githubusercontent.com/solo-io/gloo/master/example/petstore/petstore.yaml.

2. glooctl get virtualservice --output yaml also shows output defining a virtual service, but where is the name? You list the name in text Since we skipped creating a virtual service for this route, *my-virtual-service* will be created automatically for us. It would be easier to follow if you showed the name in the output.

3. Are these Kubernetes manifests? If so, where is the kind field. I look for that.

4. Where is the output of

glooctl add route \
    --path-exact /sample-route-1 \
    --dest-name default-petstore-8080 \
    --prefix-rewrite /api/pets

From https://gloo.solo.io/user_guides/function_routing/:

5. kubectl logs -l gloo=discovery does not work. You need the namespace: kubectl logs -n gloo-system -l gloo=discovery

6. This is the output I get from kubectl logs -n gloo-system -l gloo=discovery. Is this as intended?

$ kubectl logs -n gloo-system -l gloo=discovery
parsing doc as json failed, falling back to yaml

"Fri, 17 May 2019 00:15:40 UTC: github.com/solo-io/gloo/projects/discovery/pkg/fds/discoveries/swagger/swagger.go:310"	WARNING:
parsing doc as json failed, falling back to yaml

{"level":"info","ts":1558052154.0902479,"logger":"fds.v1.event_loop.fds.function-discovery-updater","caller":"grpc/grpc.go:117","msg":"tcp://gloo.gloo-system.svc.cluster.local:9977 discovered as a gRPC service"}
{"level":"info","ts":1558052193.1668105,"logger":"fds.v1.event_loop.fds.function-discovery-updater","caller":"grpc/grpc.go:117","msg":"tcp://gloo.gloo-system.svc.cluster.local:9977 discovered as a gRPC service"}
{"level":"info","ts":1558052271.1076057,"logger":"fds.v1.event_loop.fds.function-discovery-updater","caller":"grpc/grpc.go:117","msg":"tcp://gloo.gloo-system.svc.cluster.local:9977 discovered as a gRPC service"}
{"level":"info","ts":1558052378.5292346,"logger":"fds.v1.event_loop.fds.function-discovery-updater","caller":"grpc/grpc.go:117","msg":"tcp://gloo.gloo-system.svc.cluster.local:9977 discovered as a gRPC service"}
{"level":"info","ts":1558052548.0377233,"logger":"fds.v1.event_loop.fds.function-discovery-updater","caller":"grpc/grpc.go:117","msg":"tcp://gloo.gloo-system.svc.cluster.local:9977 discovered as a gRPC service"}

7. Editing issue: to perform transform requests to the structure

8. request/response transformation Envoy filter links to a GitHub site with no README.

9. (documented in the plugin spec is missing a closing parenthesis.

10. The function spec you see on the functions listed above belongs to the transformation plugin. . What does belongs to mean?

11. It would help to describe what you are trying to do with the transformation plugin in this example. In this case, you are pulling parameters that are passed in the body and creating a URL with those value embedded. This allows you to remap on way of passing a query, i.e. with parameters in json in a body, to another way of passing a query, i.e. with parameters in the URL.

From https://gloo.solo.io/user_guides/external_api_routing/:

12. In your text you say glooctl get upstream -n gloo-system, which is correct, but in the text box, you say glooctl get upstream.

13. Note that we explicitly specified the namespace otherwise glooctl would default to the gloo-system namespace. I think that you mean that it would default to the default namespace.

14. creating virtualservice default with default domain * is not the output I get. I get selected virtualservice default for route. Perhaps the code has changed? I am running

 glooctl --version
glooctl community edition version 0.13.28

Also, I see the route I added from the previous lesson.

From https://gloo.solo.io/user_guides/advanced_routing_action/:

15. The matcher provides conditional rules to select requests should be handled by a given route ?

16. The --dry-run option tells glooctl to NOT actually create the custom resource and instead output the custom resource manifest. This is a great way to get an initial manifest template that you can edit and then kubectl apply later. State this MUCH earlier in the user guide.

17. upstream_group: similar to a MultiDestination that can be shared across multiple routes and virtual services is confusing

18. The destinationSpec is an optional plugin definition based on the upstream. This make no sense.

19. additional rest desinationSpec like as follows. spelling error

20. This previous would be like execution the following glooctl command Grammar.

21. Your description of subsets is awkward. If people are using Kubernetes, you may assume that they already understand how labels and label selectors are used with Deployments and Services. Refer to that, since you usage is identical.

22. The weight is the percentage of request traffic forwarded to that destination where the percentage is: weight divided by sum of all weights in MultiDestination Say the The probability of selection instead of The weight is.

From https://gloo.solo.io/user_guides/advanced_route_plugins/:

23. You introduce retries in the timeout example. Flip the order.

From https://gloo.solo.io/operator_guide/cert-manager/

24. There are numerous obvious grammatical errors in this guide. It should be proof-read.

[christian-posta]

Thanks @derrickburns will have a look and get this corrected

[rickducott]

This is stale, but leaving open because I'd like to audit current docs against the suggestions.