update Lightstep docs with different instructions based on Satellite … (#8778)

* update Lightstep docs with different instructions based on Satellite type

* fix linting errors

* fix sp error

* Update content/en/docs/tasks/observability/distributed-tracing/lightstep/index.md

Co-authored-by: Frank Budinsky <frankb@ca.ibm.com>

Co-authored-by: Frank Budinsky <frankb@ca.ibm.com>

content/en/docs/tasks/observability/distributed-tracing/lightstep/index.md

@@ -10,10 +10,12 @@ test: no
 ---
 
 This task shows you how to configure Istio to collect trace spans and send them to [Lightstep](https://lightstep.com).
-Lightstep lets you analyze 100% of unsampled transaction data from large-scale production software to produce meaningful
+Lightstep lets you analyze 100% of unsampled transaction data from large scale production software to produce meaningful
 distributed traces and metrics that help explain performance behaviors and accelerate root cause analysis.
 At the end of this task, Istio sends trace spans from the proxies to a Lightstep Satellite pool making them
-available to the web UI.
+available to the web UI. By default, all HTTP requests are captured (to see end-to-end traces, your code needs to forward OT headers even if it does not join the traces).
+
+If you only want to collect tracing spans directly from Istio (and not add specific instrumentation directly to your code), then you don't need to configure any tracers, as long as your services forward the [HTTP headers generated by traces](https://www.envoyproxy.io/docs/envoy/latest/configuration/http_conn_man/headers#config-http-conn-man-headers-x-ot-span-context).
 
 This task uses the [Bookinfo](/docs/examples/bookinfo/) sample application as an example.
 
@@ -24,22 +26,26 @@ This task uses the [Bookinfo](/docs/examples/bookinfo/) sample application as an
 1.  If you're using [on-premise Satellites](https://docs.lightstep.com/docs/learn-about-satellites#on-premise-satellites), ensure you have a satellite pool configured with TLS certs and a secure GRPC port exposed. See
     [Install and Configure Satellites](https://docs.lightstep.com/docs/install-and-configure-satellites) for details about setting up satellites.
 
-    For [Lightstep Public Satellites](https://docs.lightstep.com/docs/learn-about-satellites#public-satellites) or [Developer Satellites](https://docs.lightstep.com/docs/learn-about-satellites#developer-satellites), your satellites are already configured.
+    For [Lightstep Public Satellites](https://docs.lightstep.com/docs/learn-about-satellites#public-satellites) or [Developer Satellites](https://docs.lightstep.com/docs/learn-about-satellites#developer-satellites), your satellites are already configured. However you need to download [this certificate](https://docs.lightstep.com/docs/instrument-with-istio-as-your-service-mesh#cacertpem-file) to a local directory.
 
 1.  Ensure sure you have a Lightstep [access token](https://docs.lightstep.com/docs/create-and-manage-access-tokens). Access tokens allow your app to communicate with your Lightstep project.
 
-1.  You'll need to deploy Istio with your satellite address.
-    For on-premise Satellites, ensure you can reach the satellite pool at an address in the format `<Host>:<Port>`, for example `lightstep-satellite.lightstep:9292`.
+## Deploy Istio
 
-    For for Public or Developer Satellites, use the address `collector-grpc.lightstep.com:443`.
+How you deploy Istio depends on which type of Satellite you use.
+
+### Deploy Istio with On-Premise Satellites
+
+These instructions do not assume TLS. If you are using TLS for your Satellite pool, follow the config for the [Public Satellite pool](#deploy-istio-with-public-or-developer-mode-satellites), but
+use your own cert and your own pool's endpoint (`host:port`).
+
+1.  You need to deploy Istio with your Satellite address at an address in the format `<Host>:<Port>`, for example `lightstep-satellite.lightstep:9292`. You find this in your [configuration](https://docs.lightstep.com/docs/satellite-configuration-parameters#ports) file.
 
 1.  Deploy Istio with the following configuration parameters specified:
     - `pilot.traceSampling=100`
     - `global.proxy.tracer="lightstep"`
     - `global.tracer.lightstep.address="<satellite-address>"`
     - `global.tracer.lightstep.accessToken="<access-token>"`
-    - `global.tracer.lightstep.secure=true`
-    - `global.tracer.lightstep.cacertPath="/etc/lightstep/cacert.pem"`
 
     You can set these parameters using the `--set key=value` syntax
     when you run the install command. For example:
@@ -50,12 +56,36 @@ This task uses the [Bookinfo](/docs/examples/bookinfo/) sample application as an
         --set values.global.proxy.tracer="lightstep" \
         --set values.global.tracer.lightstep.address="<satellite-address>" \
         --set values.global.tracer.lightstep.accessToken="<access-token>" \
-        --set values.global.tracer.lightstep.secure=true \
-        --set values.global.tracer.lightstep.cacertPath="/etc/lightstep/cacert.pem"
+    {{< /text >}}
+
+### Deploy Istio with Public or Developer Mode Satellites
+
+Follow these steps if you're using the Public or Developer Mode Satellites, or if you're using on-premise Satellites with a TLS certificate.
+
+1.  Deploy Istio with the following configuration parameters specified:
+    - `pilot.traceSampling=100`
+    - `global.proxy.tracer="lightstep"`
+    - `meshConfig.defaultConfig.tracing.tlsSettings.mode="SIMPLE"`
+    - `meshConfig.defaultConfig.tracing.tlsSettings.caCertificates="/etc/lightstep/cacert.pem"`
+    - `global.tracer.lightstep.address="ingest.lightstep.com:443"`
+    - `global.tracer.lightstep.accessToken="<access-token>"`
+
+    You can set these parameters using the `--set key=value` syntax
+    when you run the install command. For example:
+
+    {{< text bash >}}
+    $ istioctl install \
+        --set values.pilot.traceSampling=100 \
+        --set values.global.proxy.tracer="lightstep" \
+        --set meshConfig.defaultConfig.tracing.tlsSettings.mode="SIMPLE" \
+        --set meshConfig.defaultConfig.tracing.tlsSettings.caCertificates="/etc/lightstep/cacert.pem" \
+        --set values.global.tracer.lightstep.
+        address="ingest.lightstep.com:443" \
+        --set values.global.tracer.lightstep.accessToken="<access-token>" \
     {{< /text >}}
 
 1.  Store your satellite pool's certificate authority certificate as a secret in the default namespace.
-    For Lightstep Public and Developer Satellites, download and use [this certificate](https://docs.lightstep.com/docs/instrument-with-istio-as-your-service-mesh#cacertpem-file).
+    Download and use [this certificate](https://docs.lightstep.com/docs/instrument-with-istio-as-your-service-mesh#cacertpem-file).
     If you deploy the Bookinfo application in a different namespace, create the secret in that namespace instead.
 
     {{< text bash >}}
@@ -78,9 +108,9 @@ This task uses the [Bookinfo](/docs/examples/bookinfo/) sample application as an
     EOF
     {{< /text >}}
 
-1.   Follow the [instructions to deploy the Bookinfo sample application](/docs/examples/bookinfo/#deploying-the-application).
+## Install and run the Bookinfo app
 
-## Visualize trace data
+1. Follow the [instructions to deploy the Bookinfo sample application](/docs/examples/bookinfo/#deploying-the-application).
 
 1.  Follow the [instructions to create an ingress gateway for the Bookinfo application](/docs/examples/bookinfo/#determine-the-ingress-ip-and-port).
 
@@ -92,6 +122,8 @@ This task uses the [Bookinfo](/docs/examples/bookinfo/) sample application as an
     $ curl http://$GATEWAY_URL/productpage
     {{< /text >}}
 
+## Visualize trace data
+
 1.  Load the Lightstep [web UI](https://app.lightstep.com/). You'll see the three Bookinfo services listed in the Service Directory.
 
     {{< image link="./istio-services.png" caption="Bookfinder services in the Service Directory" >}}
@@ -132,8 +164,7 @@ The Lightstep integration does not currently capture spans generated by Istio's
 Istio captures traces at a configurable trace sampling percentage. To learn how to modify the trace sampling percentage,
 visit the [Distributed Tracing trace sampling section](../configurability/#trace-sampling).
 
-When using Lightstep, we do not recommend reducing the trace sampling percentage below 100%. To handle a high traffic mesh,
-consider scaling up the size of your satellite pool.
+When using Lightstep, we do not recommend reducing the trace sampling percentage below 100%. To handle a high traffic mesh, consider scaling up the size of your satellite pool.
 
 ## Cleanup