diff --git a/content/docs/tasks/telemetry/gateways/index.md b/content/docs/tasks/telemetry/gateways/index.md new file mode 100644 index 0000000000..bbedd2fdb8 --- /dev/null +++ b/content/docs/tasks/telemetry/gateways/index.md @@ -0,0 +1,640 @@ +--- +title: Remotely Accessing Telemetry Addons +description: This task shows you how to configure external access to the set of Istio telemetry addons. +weight: 99 +keywords: [telemetry,gateway,jaeger,zipkin,tracing,kiali,prometheus,addons] +--- + +This task shows how to configure Istio to expose and access the telemetry addons outside of +a cluster. + +## Configuring remote access + +Remote access to the telemetry addons can be configured in a number of different ways. This task covers +two basic access methods: secure (via HTTPS) and insecure (via HTTP). The secure method is *strongly +recommended* for any production or sensitive environment. Insecure access is simpler to set up, but +will not protect any credentials or data transmitted outside of your cluster. + +### Option 1: Secure access (HTTPS) + +A server certificate is required for secure access. Follow these steps to install and configure +server certificates for a domain that you control. + +You may use self-signed certificates instead. Visit our +[Securing Gateways with HTTPS Using Secret Discovery Service task](/docs/tasks/traffic-management/secure-ingress/sds/) +for general information on using self-signed certificates to access in-cluster services. + +{{< warning >}} +This option covers securing the transport layer *only*. You should also configure the telemetry +addons to require authentication when exposing them externally. +{{< /warning >}} + +1. [Install Istio](/docs/setup/kubernetes) in your cluster and enable the `cert-manager` flag and configure `istio-ingressgateway` to use +the [Secret Discovery Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/secret#config-secret-discovery-service). + + To install Istio accordingly, use the following Helm installation options: + + * `--set gateways.enabled=true` + * `--set gateways.istio-ingressgateway.enabled=true` + * `--set gateways.istio-ingressgateway.sds.enabled=true` + * `--set certmanager.enabled=true` + * `--set certmanager.email=mailbox@donotuseexample.com` + + To additionally install the telemetry addons, use the following Helm installation options: + + * Grafana: `--set grafana.enabled=true` + * Kiali: `--set kiali.enabled=true` + * Prometheus: `--set prometheus.enabled=true` + * Tracing: `--set tracing.enabled=true` + +1. Configure the DNS records for your domain. + + 1. Get the external IP address of the `istio-ingressgateway`. + + {{< text bash >}} + $ kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + + {{< /text >}} + + 1. Set an environment variable to hold your target domain. + + {{< text bash >}} + $ TELEMETRY_DOMAIN= + {{< /text >}} + + 1. Point your desired domain at that external IP address via your domain provider. + + The mechanism for achieving this step varies by provider. Here are a few example documentation links: + + * Bluehost: [DNS Management Add Edit or Delete DNS Entries](https://my.bluehost.com/hosting/help/559) + * GoDaddy: [Add an A record](https://www.godaddy.com/help/add-an-a-record-19238) + * Google Domains: [Resource Records](https://support.google.com/domains/answer/3290350?hl=en) + * Name.com: [Adding an A record](https://www.name.com/support/articles/115004893508-Adding-an-A-record) + + 1. Verify that the DNS records are correct. + + {{< text bash >}} + $ dig +short $TELEMETRY_DOMAIN + + {{< /text >}} + +1. Generate a server certificate + + {{< text bash >}} + $ cat <}} + +1. Wait until the server certificate is ready. + + {{< text bash >}} + $ JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status}{end}{end}' && kubectl -n istio-system get certificates -o jsonpath="$JSONPATH" + telemetry-gw-cert:Ready=True + {{< /text >}} + +1. Apply networking configuration for the telemetry addons. + + 1. Apply the following configuration to expose Grafana: + + {{< text bash >}} + $ cat <}} + + 1. Apply the following configuration to expose Kiali: + + {{< text bash >}} + $ cat <}} + + 1. Apply the following configuration to expose Prometheus: + + {{< text bash >}} + $ cat <}} + + 1. Apply the following configuration to expose the tracing service: + + {{< text bash >}} + $ cat <}} + +1. Visit the telemetry addons via your browser. + + * Kiali: `https://$TELEMETRY_DOMAIN:15029/` + * Prometheus: `https://$TELEMETRY_DOMAIN:15030/` + * Grafana: `https://$TELEMETRY_DOMAIN:15031/` + * Tracing: `https://$TELEMETRY_DOMAIN:15032/` + +### Option 2: Insecure access (HTTP) + +1. [Install Istio](/docs/setup/) in your cluster with your desired telemetry addons. + + To additionally install the telemetry addons, use the following Helm installation options: + + * Grafana: `--set grafana.enabled=true` + * Kiali: `--set kiali.enabled=true` + * Prometheus: `--set prometheus.enabled=true` + * Tracing: `--set tracing.enabled=true` + +1. Apply networking configuration for the telemetry addons. + + 1. Apply the following configuration to expose Grafana: + + {{< text bash >}} + $ cat <}} + + 1. Apply the following configuration to expose Kiali: + + {{< text bash >}} + $ cat <}} + + 1. Apply the following configuration to expose Prometheus: + + {{< text bash >}} + $ cat <}} + + 1. Apply the following configuration to expose the tracing service: + + {{< text bash >}} + $ cat <}} + +1. Visit the telemetry addons via your browser. + + * Kiali: `http://:15029/` + * Prometheus: `http://:15030/` + * Grafana: `http://:15031/` + * Tracing: `http://:15032/` + +## Cleanup + +* Remove all related Gateways: + + {{< text bash >}} + $ kubectl -n istio-system delete gateway grafana-gateway kiali-gateway prometheus-gateway tracing-gateway + gateway.networking.istio.io "grafana-gateway" deleted + gateway.networking.istio.io "kiali-gateway" deleted + gateway.networking.istio.io "prometheus-gateway" deleted + gateway.networking.istio.io "tracing-gateway" deleted + {{< /text >}} + +* Remove all related Virtual Services: + + {{< text bash >}} + $ kubectl -n istio-system delete virtualservice grafana-vs kiali-vs prometheus-vs tracing-vs + virtualservice.networking.istio.io "grafana-vs" deleted + virtualservice.networking.istio.io "kiali-vs" deleted + virtualservice.networking.istio.io "prometheus-vs" deleted + virtualservice.networking.istio.io "tracing-vs" deleted + {{< /text >}} + +* If installed, remove the gateway certificate: + + {{< text bash >}} + $ kubectl -n istio-system delete certificate telemetry-gw-cert + certificate.certmanager.k8s.io "telemetry-gw-cert" deleted + {{< /text >}} \ No newline at end of file