Getting started page, one more time (#4359)

* getting started

* fix typo

* remove tip

* review comments

content/_index.md

@@ -106,7 +106,7 @@ description: Connect, secure, control, and observe services.
     </div>
 
     <div id="buttons">
-        <a title="Install Istio on Kubernetes today." class="btn" href="/docs/setup/kubernetes/">GET STARTED</a>
+        <a title="Install Istio on Kubernetes today." class="btn" href="/docs/setup/kubernetes/getting-started/">GET STARTED</a>
         <a title="Dive deeper to understand what Istio is and how it works." class="btn" href="/docs/concepts/what-is-istio/">LEARN MORE</a>
         <a title="Download the latest release." class="btn" href="{{< istio_release_url >}}">DOWNLOAD {{< istio_release_name >}}</a>
     </div>

content/docs/setup/kubernetes/_index.md

@@ -7,6 +7,8 @@ aliases:
     - /docs/tasks/installing-istio.html
     - /docs/setup/install-kubernetes.html
     - /docs/setup/kubernetes/quick-start.html
+    - /docs/setup/kubernetes/download-release/
+    - /docs/setup/kubernetes/download/
 icon: kubernetes
 keywords: [kubernetes,install,quick-start,setup,installation]
 content_above: true
@@ -16,12 +18,88 @@ content_above: true
 Istio {{< istio_version >}} has been tested with these Kubernetes releases: {{< supported_kubernetes_versions >}}.
 {{< /tip >}}
 
-Istio offers [multiple installation flows](/docs/setup/kubernetes/getting-started/) depending on your platform and intended use.
+Istio offers [multiple installation flows](/docs/setup/kubernetes/getting-started/)
+depending on your platform and whether or not you intend to use Istio in production.
 At a high level, the basic flow is the same regardless of platform:
 
 1. [Review the pod requirements](/docs/setup/kubernetes/additional-setup/requirements/)
 1. [Prepare your platform for Istio](/docs/setup/kubernetes/platform-setup/)
-1. [Download the Istio release](/docs/setup/kubernetes/getting-started/#downloading-the-release)
+1. [Download the Istio release](#downloading-the-release)
 1. [Install Istio on your platform](/docs/setup/kubernetes/install)
 
-To proceed with your installation, follow our [getting started guide](/docs/setup/kubernetes/getting-started/).
+## Installing Istio
+
+Choose one of the following installation options, depending on your intended use:
+
+- [Demo installation](/docs/setup/kubernetes/install/kubernetes/):
+   This option is ideal if you're new to Istio and just want to try it out.
+   It allows you to experiment with many Istio features with modest resource requirements.
+
+- [Custom installation with Helm](/docs/setup/kubernetes/install/helm/):
+   This option is ideal to install Istio for production use or for performance evaluation.
+
+- [Supported platform installation](/docs/setup/kubernetes/install/platform/):
+   This option is ideal if your platform provides native support for Istio-enabled clusters
+   with a [configuration profile](/docs/setup/kubernetes/additional-setup/config-profiles/)
+   corresponding to your intended use.
+
+After choosing an option and installing Istio on your cluster, you can deploy
+your own applications or experiment with some of our [tasks](/docs/tasks/) and [examples](/docs/examples/).
+
+{{< tip >}}
+If you're running your own applications, make sure to
+check the [requirements for pods and services](/docs/setup/kubernetes/additional-setup/requirements/).
+{{< /tip >}}
+
+When you're ready to consider more advanced Istio use cases, check out the following resources:
+
+- To install using Istio's Container Network Interface
+(CNI) plugin, visit our [CNI guide](/docs/setup/kubernetes/additional-setup/cni/).
+
+- To perform a multicluster setup, visit our
+[multicluster installation documents](/docs/setup/kubernetes/install/multicluster/).
+
+- To expand your existing mesh with additional containers or VMs not running on
+your mesh's Kubernetes cluster, follow our [mesh expansion guide](/docs/setup/kubernetes/additional-setup/mesh-expansion/).
+
+- To add services requires a detailed understanding of sidecar injection. Visit our
+[sidecar injection guide](/docs/setup/kubernetes/additional-setup/sidecar-injection/)
+to learn more.
+
+## Downloading the release
+
+Istio is installed in its own `istio-system` namespace and can manage
+services from all other namespaces.
+
+1.  Go to the [Istio release](https://github.com/istio/istio/releases) page to
+    download the installation file corresponding to your OS. On a macOS or
+    Linux system, you can run the following command to download and
+    extract the latest release automatically:
+
+    {{< text bash >}}
+    $ curl -L https://git.io/getLatestIstio | ISTIO_VERSION={{< istio_full_version >}} sh -
+    {{< /text >}}
+
+1.  Move to the Istio package directory. For example, if the package is
+    `istio-{{< istio_full_version >}}`:
+
+    {{< text bash >}}
+    $ cd istio-{{< istio_full_version >}}
+    {{< /text >}}
+
+    The installation directory contains:
+
+    - Installation YAML files for Kubernetes in `install/kubernetes`
+    - Sample applications in `samples/`
+    - The `istioctl` client binary in the `bin/` directory. `istioctl` is
+      used when manually injecting Envoy as a sidecar proxy.
+
+1.  Add the `istioctl` client to your `PATH` environment variable, on a macOS or
+    Linux system:
+
+    {{< text bash >}}
+    $ export PATH=$PWD/bin:$PATH
+    {{< /text >}}
+
+1. You can enable the [auto-completion option](/docs/ops/setup/istioctl) when working with a bash or ZSH console.
+

content/docs/setup/kubernetes/additional-setup/cni/index.md

@@ -40,7 +40,7 @@ replaces the functionality provided by the `istio-init` container.
     *  The Kubernetes documentation highly recommends this for all Kubernetes installations
        where `ServiceAccounts` are utilized.
 
-1.  [Download the Istio release](/docs/setup/kubernetes/getting-started/#downloading-the-release).
+1.  [Download the Istio release](/docs/setup/kubernetes/#downloading-the-release).
 
 ## Installation
 

content/docs/setup/kubernetes/getting-started/index.md

@@ -2,83 +2,39 @@
 title: Getting Started
 description: Download and install Istio.
 weight: 5
-aliases:
-    - /docs/setup/kubernetes/download-release/
-    - /docs/setup/kubernetes/download/
 keywords: [kubernetes]
 ---
 
-Istio offers multiple installation options depending on your platform and
+If you’re new to Istio and just want to try it out, the quickest way to get started is
-whether or not you intend to use Istio in production.
+by downloading and installing Istio's built-in **demo** configuration.
+Istio can also be installed and customized in many other ways, depending on your platform and intended use.
+Check out our [general installation instructions](/docs/setup/) for details.
 
-- [Demo installation](/docs/setup/kubernetes/install/kubernetes/):
+To get started, proceed as follows:
-   This option is ideal if you're new to Istio and just want to try it out.
-   It allows you to experiment with many Istio features with modest resource requirements.
 
-- [Custom installation with Helm](/docs/setup/kubernetes/install/helm/):
+1. [Setup your platform](/docs/setup/kubernetes/platform-setup/)
-   This option is ideal to install Istio for production use or for performance evaluation.
+1. [Download the Istio release](/docs/setup/kubernetes/#downloading-the-release)
+1. [Follow the quick-start installation instructions](/docs/setup/kubernetes/install/kubernetes)
 
-- [Supported platform installation](/docs/setup/kubernetes/install/platform/):
+Once you've installed Istio, a good way to start evaluating Istio's features is using our
-   This option is ideal if your platform provides native support for Istio-enabled clusters
+[Bookinfo sample application](/docs/examples/bookinfo/).
-   with a [configuration profile](/docs/setup/kubernetes/additional-setup/config-profiles/)
+You can use this sample to experiment with Istio’s features for traffic routing,
-   corresponding to your intended use.
+fault injection, rate limiting, etc..
 
-After choosing an option and installing Istio on your cluster, you can deploy
+1. [Deploy the Bookinfo sample](/docs/examples/bookinfo/#if-you-are-running-on-kubernetes)
-your own application or experiment with some of our [tasks](/docs/tasks/) and [examples](/docs/examples/).
+1. Explore various [Istio tasks](/docs/tasks/), depending on your interest.
+    The following tasks are a good start for beginners:
+    * [Request routing](/docs/tasks/traffic-management/request-routing/)
+    * [Fault injection](/docs/tasks/traffic-management/fault-injection/)
+    * [Traffic shifting](/docs/tasks/traffic-management/traffic-shifting/)
+    * [Querying metrics](/docs/tasks/telemetry/metrics/querying-metrics/)
+    * [Visualizing metrics](/docs/tasks/telemetry/metrics/using-istio-dashboard/)
+    * [Collecting logs](/docs/tasks/telemetry/logs/collecting-logs/)
+    * [Rate limiting](/docs/tasks/policy-enforcement/rate-limiting/)
+    * [Ingress gateways](/docs/tasks/traffic-management/ingress/ingress-control/)
+    * [Accessing external services](/docs/tasks/traffic-management/egress/egress-control/)
+    * [Visualizing your mesh](/docs/tasks/telemetry/kiali/)
 
-{{< tip >}}
+After that, you will have a pretty good understanding of Istio's basic functionality and can then
-If you're running your own application, make sure to
+proceed to explore Istio's many other tasks or, even better, start to deploy your own applications.
-check the [requirements for pods and services](/docs/setup/kubernetes/additional-setup/requirements/).
+If you do continue to use Istio, we look forward to hearing from you.
-{{< /tip >}}
-
-When you're ready to consider more advanced Istio use cases, check out the following resources:
-
-- To install using Istio's Container Network Interface
-(CNI) plugin, visit our [CNI guide](/docs/setup/kubernetes/additional-setup/cni/).
-
-- To perform a multicluster setup, visit our
-[multicluster installation documents](/docs/setup/kubernetes/install/multicluster/).
-
-- To expand your existing mesh with additional containers or VMs not running on
-your mesh's Kubernetes cluster, follow our [mesh expansion guide](/docs/setup/kubernetes/additional-setup/mesh-expansion/).
-
-- To add services requires detailed understanding of sidecar injection. Visit our
-[sidecar injection guide](/docs/setup/kubernetes/additional-setup/sidecar-injection/)
-to learn more.
-
-## Downloading the release
-
-Istio is installed in its own `istio-system` namespace and can manage
-services from all other namespaces.
-
-1.  Go to the [Istio release](https://github.com/istio/istio/releases) page to
-    download the installation file corresponding to your OS. On a macOS or
-    Linux system, you can run the following command to download and
-    extract the latest release automatically:
-
-    {{< text bash >}}
-    $ curl -L https://git.io/getLatestIstio | ISTIO_VERSION={{< istio_full_version >}} sh -
-    {{< /text >}}
-
-1.  Move to the Istio package directory. For example, if the package is
-    `istio-{{< istio_full_version >}}`:
-
-    {{< text bash >}}
-    $ cd istio-{{< istio_full_version >}}
-    {{< /text >}}
-
-    The installation directory contains:
-
-    - Installation YAML files for Kubernetes in `install/kubernetes`
-    - Sample applications in `samples/`
-    - The `istioctl` client binary in the `bin/` directory. `istioctl` is
-      used when manually injecting Envoy as a sidecar proxy.
-
-1.  Add the `istioctl` client to your `PATH` environment variable, on a macOS or
-    Linux system:
-
-    {{< text bash >}}
-    $ export PATH=$PWD/bin:$PATH
-    {{< /text >}}
-
-1. You can enable the [auto-completion option](/docs/ops/setup/istioctl) when working with a bash or ZSH console.

content/docs/setup/kubernetes/install/helm/index.md

@@ -25,7 +25,7 @@ and then further customize the configuration for your specific needs.
 
 ## Prerequisites
 
-1. [Download the Istio release](/docs/setup/kubernetes/getting-started/#downloading-the-release).
+1. [Download the Istio release](/docs/setup/kubernetes/#downloading-the-release).
 
 1. Perform any necessary [platform-specific setup](/docs/setup/kubernetes/platform-setup/).
 

content/docs/setup/kubernetes/install/kubernetes/index.md

@@ -24,13 +24,13 @@ This permits customization of Istio to operator specific requirements.
 
 ## Prerequisites
 
-1. [Download the Istio release](/docs/setup/kubernetes/getting-started/#downloading-the-release).
+1. [Download the Istio release](/docs/setup/kubernetes/#downloading-the-release).
 
     {{< warning >}}
     These quick-start instructions will not work with a downloaded [istio repository](https://github.com/istio/istio)
     becuase the pregenerated yaml files, `istio-demo.yaml` and `istio-demo-auth.yaml`, are only available in
-    **release images**. If you want to use the GitHub repository, istead of a release image,
+    [release images](https://github.com/istio/istio/releases). If you want to work with the latest Istio codebase,
-    install the demo profile using [helm template](/docs/setup/kubernetes/install/helm/#option-1-install-with-helm-via-helm-template) instead.
+    refer to the [developer wiki](https://github.com/istio/istio/wiki) for instructions.
     {{< /warning >}}
 
 1. Perform any necessary [platform-specific setup](/docs/setup/kubernetes/platform-setup/).

content/docs/setup/kubernetes/upgrade/steps/index.md

@@ -28,7 +28,7 @@ upgrading your deployment to Istio 1.1.
 
 ## Upgrade steps
 
-[Download the new Istio release](/docs/setup/kubernetes/getting-started/#downloading-the-release)
+[Download the new Istio release](/docs/setup/kubernetes/#downloading-the-release)
 and change directory to the new release directory.
 
 ### Control plane upgrade
@@ -249,7 +249,7 @@ the object to be namespace-scoped in some cases. The `ClusterRbacConfig` follows
 specification as the `RbacConfig` but with the correct cluster scope implementation.
 
 To automate the migration, we developed the `convert_RbacConfig_to_ClusterRbacConfig.sh` script.
-The script is included in the [Istio installation package](/docs/setup/kubernetes/getting-started/#downloading-the-release).
+The script is included in the [Istio installation package](/docs/setup/kubernetes/#downloading-the-release).
 
 Download and run the script with the following command: