Unclear documentation

[padzikm]

Hi, I have troubles working with istio's documentation, so maybe here I can get answers:

1. In egress example https://istio.io/docs/tasks/traffic-management/egress/egress-gateway/#egress-gateway-for-https-traffic in http part there is empty subset field in destinationrule:

apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
  name: istio-egressgateway
spec:
  selector:
    istio: egressgateway
  servers:
  - port:
      number: 443
      name: tls
      protocol: TLS
    hosts:
    - edition.cnn.com
    tls:
      mode: PASSTHROUGH
---
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: egressgateway-for-cnn
spec:
  host: istio-egressgateway.istio-system.svc.cluster.local
  subsets:
  - name: cnn
---
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: direct-cnn-through-egress-gateway
spec:
  hosts:
  - edition.cnn.com
  gateways:
  - mesh
  - istio-egressgateway
  tls:
  - match:
    - gateways:
      - mesh
      port: 443
      sni_hosts:
      - edition.cnn.com
    route:
    - destination:
        host: istio-egressgateway.istio-system.svc.cluster.local
        subset: cnn
        port:
          number: 443
  - match:
    - gateways:
      - istio-egressgateway
      port: 443
      sni_hosts:
      - edition.cnn.com
    route:
    - destination:
        host: edition.cnn.com
        port:
          number: 443
      weight: 100

what is empty subset for? according to docs 'a subset without labels may be meaningful. In this case a traffic policy with TLSSettings can be used to identify a specific SNI host corresponding to the named subset', but there is no tlssettings and traffic is via http, not https, so there is no sni (which is part of https protocol) - can empty subset be ommited and therefore whole destinationrule can be ommited without any consequences in this example?

2. how egress crd resource is bound to egress gateway? in example https://istio.io/docs/tasks/traffic-management/egress/egress-gateway/#egress-gateway-for-https-traffic gateway resource is set in default namespace with selector for egressgateway label:

apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
  name: istio-egressgateway
spec:
  selector:
    istio: egressgateway
  servers:
  - port:
      number: 443
      name: tls
      protocol: TLS
    hosts:
    - edition.cnn.com
    tls:
      mode: PASSTHROUGH

how gateway crd resource finds istio's egress gateway, which is in istio-system namespace? according to docs selector is 'one or more labels that indicate a specific set of pods/VMs on which this gateway configuration should be applied. The scope of label search is restricted to the configuration namespace in which the the resource is present. In other words, the Gateway resource must reside in the same namespace as the gateway workload instance.' which means as I understand, that gateway crd resource should be in istio-system namespace, not in default namespace as in example - how is it works?

3. how istio can be combined with aws iam roles for istio identity? in docs - https://istio.io/docs/concepts/security/#istio-identity - there is only one mention that AWS: AWS IAM user/role account can be used as source for istio identity, but there is no example, no any further explanation how to do it

4. according to https://istio.io/docs/ops/best-practices/traffic-management/#cross-namespace-configuration 'you can define virtual services, destination rules, or service entries in one namespace and then reuse them in other namespaces, if they are exported to those namespaces. Istio exports all traffic management resources to all namespaces by default' but then docs state, that destinationrule has to be placed in specific namespaces to be found - so is it exported to all namespaces or not by default? and docs say only about destinationrule, but nothing about virtual services and service entries - do they also have to be placed in specific namespaces, or is it only for destinationrule?

5. how are certificates managed between envoy proxies? are they self signed by some istio's ca, have correct cn for service names and are automatically rotated by istio before expiration, or do I have to integrate for example cert-manager manually for automatic tls encryption between envoys?

[howardjohn]

1. @nschhina can you fix this when you update the doc to not use a subset? its confusing IMO, I agree with @padzikm

2. fixed now, https://preliminary.istio.io/latest/docs/reference/config/networking/gateway/#Gateway

3. Doc is updated to explain DR selection rules now. Other resources covered under exports all traffic management resources to all namespaces by default

4. Self signed by istio CA using spiffe identity

Please use discuss.istio.io in the future for questions, github is meant for reporting product bugs. Thanks!

[nschhina]

I already updated the doc for egress gateway, I don't really own this part so I never bothered checking this out. But I'll triage this to see how this could be better.

[nschhina]

@howardjohn @padzikm I looked at how this user task works

but there is no tlssettings and traffic is via http, not https, so there is no sni (which is part of https protocol)

This is not entirely true. Traffic is https- we don't even initiate http traffic with curl. SNI exists as well, this time sniHost is set in VirtualService and not DestinationRule. The reason for this is that egress gateway is acting as a passthrough cluster, if DestinationRule has TLSSettings, then the Gateway will terminate the TLS connection initiated by sidecar which is not what we wish to do in this example.

  - match:
    - gateways:
      - mesh
      port: 443
      sniHosts:
      - edition.cnn.com
    route:
    - destination:
        host: istio-egressgateway.istio-system.svc.cluster.local
        subset: cnn
        port:
          number: 443

I think it's best practice we use DestinationRule along with VirtualService- this page is not doc tested either, so I'm hesitant to make any change to the user task without any proper automated testing.