[release-1.4] Another ops guide incremental improvement (#5893)

* Another ops guide incremental improvement

* fix broken links

* more lint errors

* one more lint

* fix aliases

* disable zh build

config.toml

@@ -65,7 +65,5 @@ disableAliases = true
 
 # internationalization
 [languages]
-    [languages.zh]
-        contentDir = "content/zh"
     [languages.en]
         contentDir = "content/en"

content/en/about/feature-stages/index.md

@@ -44,7 +44,7 @@ Below is our list of existing features and their current phases. This informatio
 | Gateway: Ingress, Egress for all protocols | Stable
 | TLS termination and SNI Support in Gateways | Stable
 | SNI (multiple certs) at ingress | Stable
-| [Locality load balancing](/docs/ops/traffic-management/locality-load-balancing/) | Beta
+| [Locality load balancing](/docs/ops/configuration/traffic-management/locality-load-balancing/) | Beta
 | Enabling custom filters in Envoy | Alpha
 | CNI container interface | Alpha
 | [Sidecar API](/docs/reference/config/networking/sidecar/) | Beta
@@ -102,7 +102,7 @@ Below is our list of existing features and their current phases. This informatio
 | [Out of Process Mixer Adapters (gRPC Adapters)](https://github.com/istio/istio/wiki/Mixer-Out-Of-Process-Adapter-Dev-Guide) | Beta
 | [Istio CNI plugin](/docs/setup/additional-setup/cni/) | Alpha
 | IPv6 support for Kubernetes | Alpha
-| [Distroless base images for Istio](/docs/ops/security/harden-docker-images/) | Alpha
+| [Distroless base images for Istio](/docs/ops/configuration/security/harden-docker-images/) | Alpha
 
 {{< idea >}}
 Please get in touch by joining our [community](/about/community/) if there are features you'd like to see in our future releases!

content/en/blog/2018/egress-https/index.md

@@ -190,7 +190,7 @@ in this case `www.googleapis.com`.
 To allow Istio to perform monitoring and policy enforcement of egress requests based on HTTP details, the microservices
 must issue HTTP requests. Istio then opens an HTTPS connection to the destination (performs TLS origination). The code
 of the microservices must be written differently or configured differently, according to whether the microservice runs
-inside or outside an Istio service mesh. This contradicts the Istio design goal of [maximizing transparency](/docs/ops/architecture/#design-goals). Sometimes you need to compromise...
+inside or outside an Istio service mesh. This contradicts the Istio design goal of [maximizing transparency](/docs/ops/deployment/architecture/#design-goals). Sometimes you need to compromise...
 
 The diagram below shows two options for sending HTTPS traffic to external services. On the top, a microservice sends
 regular HTTPS requests, encrypted end-to-end. On the bottom, the same microservice sends unencrypted HTTP requests

content/en/blog/2019/app-identity-and-access-adapter/index.md

@@ -20,9 +20,9 @@ With the [App Identity and Access Adapter](https://github.com/ibm-cloud-security
 transparently layers onto distributed applications and seamlessly integrates
 with Kubernetes. To reduce the complexity of deployments Istio provides
 behavioral insights and operational control over the service mesh as a whole.
-See the [Istio Architecture](/docs/ops/architecture/) for more details.
+See the [Istio Architecture](/docs/ops/deployment/architecture/) for more details.
 
-Istio uses [Envoy proxy sidecars](/blog/2019/data-plane-setup/) to mediate inbound and outbound traffic for all pods in the service mesh. Istio extracts telemetry from the Envoy sidecars and sends it to [Mixer](/docs/ops/architecture/#mixer), the Istio component responsible for collecting telemetry and enforcing policy.
+Istio uses [Envoy proxy sidecars](/blog/2019/data-plane-setup/) to mediate inbound and outbound traffic for all pods in the service mesh. Istio extracts telemetry from the Envoy sidecars and sends it to [Mixer](/docs/ops/deployment/architecture/#mixer), the Istio component responsible for collecting telemetry and enforcing policy.
 
 The App Identity and Access adapter extends the Mixer functionality by analyzing the telemetry (attributes) against various access control policies across the service mesh. The access control policies can be linked to a particular Kubernetes services and can be finely tuned to specific service endpoints. For more information about policies and telemetry, see the Istio documentation.
 

content/en/blog/2019/data-plane-setup/index.md

@@ -10,7 +10,7 @@ target_release: 1.0
 ---
 A simple overview of an Istio service-mesh architecture always starts with describing the control-plane and data-plane.
 
-[From Istio’s documentation:](/docs/ops/architecture/)
+[From Istio’s documentation](/docs/ops/deployment/architecture/):
 
 {{< quote >}}
 An Istio service mesh is logically split into a data plane and a control plane.

content/en/blog/2019/multicluster-version-routing/index.md

@@ -18,10 +18,10 @@ wondering if all these things will be just as simple in your real production env
 Fortunately, Istio provides several ways to configure a service mesh so that applications
 can, more-or-less transparently, be part of a mesh where the services are running
 in more than one cluster, i.e., in a
-[multicluster deployment](/docs/ops/prep/deployment-models/#multiple-clusters).
+[multicluster deployment](/docs/ops/deployment/deployment-models/#multiple-clusters).
 The simplest way to set up a multicluster mesh, because it has no special networking requirements,
 is using a replicated
-[control plane model](/docs/ops/prep/deployment-models/#control-plane-models).
+[control plane model](/docs/ops/deployment/deployment-models/#control-plane-models).
 In this configuration, each Kubernetes cluster contributing to the mesh has its own control plane,
 but each control plane is synchronized and running under a single administrative control.
 

content/en/blog/2019/performance-best-practices/index.md

@@ -12,7 +12,7 @@ Service meshes add a lot of functionality to application deployments, including
 
 Earlier this year, we published a [blog post](/blog/2019/istio1.1_perf/) on Istio's performance improvements in version 1.1. Following the release of [Istio 1.2](/news/releases/1.2.x/announcing-1.2), we want to provide guidance and tools to help you benchmark Istio's data plane performance in a production-ready Kubernetes environment.
 
-Overall, we found that Istio's [sidecar proxy](/docs/ops/architecture/#envoy) latency scales with the number of concurrent connections. At 1000 requests per second (RPS), across 16 connections, Istio adds **3 milliseconds** per request in the 50th percentile, and **10 milliseconds** in the 99th percentile.
+Overall, we found that Istio's [sidecar proxy](/docs/ops/deployment/architecture/#envoy) latency scales with the number of concurrent connections. At 1000 requests per second (RPS), across 16 connections, Istio adds **3 milliseconds** per request in the 50th percentile, and **10 milliseconds** in the 99th percentile.
 
 In the [Istio Tools repository](https://github.com/istio/tools/tree/3ac7ab40db8a0d595b71f47b8ba246763ecd6213/perf/benchmark), you’ll find scripts and instructions for measuring Istio's data plane performance, with additional instructions on how to run the scripts with [Linkerd](https://linkerd.io), another service mesh implementation. [Follow along](https://github.com/istio/tools/tree/3ac7ab40db8a0d595b71f47b8ba246763ecd6213/perf/benchmark#setup) as we detail some best practices for each step of the performance test framework.
 
@@ -108,6 +108,6 @@ For a mesh with 1000 RPS across 16 connections, Istio 1.2 adds just **3 millisec
 Istio's performance depends on your specific setup and traffic load. Because of this variance, make sure your test setup accurately reflects your production workloads. To try out the benchmarking scripts, head over [to the Istio Tools repository](https://github.com/istio/tools/tree/3ac7ab40db8a0d595b71f47b8ba246763ecd6213/perf/benchmark).
 {{< /tip >}}
 
-Also check out the [Istio Performance and Scalability guide](/docs/ops/performance-and-scalability) for the most up-to-date performance data.
+Also check out the [Istio Performance and Scalability guide](/docs/ops/deployment/performance-and-scalability) for the most up-to-date performance data.
 
 Thank you for reading, and happy benchmarking!

content/en/blog/2019/root-transition/index.md

@@ -13,7 +13,7 @@ you need to schedule regular root transitions before they expire.
 An expiration of a root certificate may lead to an unexpected cluster-wide outage.
 The issue affects new clusters created with versions up to 1.0.7 and 1.1.7.
 
-See [Extending Self-Signed Certificate Lifetime](/docs/ops/security/root-transition/) for
+See [Extending Self-Signed Certificate Lifetime](/docs/ops/configuration/security/root-transition/) for
 information on how to gauge the age of your certificates and how to perform rotation.
 
 {{< tip >}}

content/en/docs/concepts/observability/index.md

@@ -19,7 +19,7 @@ Istio, operators gain a thorough understanding of how monitored services are int
 Istio generates the following types of telemetry in order to provide overall service mesh observability:
 
 - [**Metrics**](#metrics). Istio generates a set of service metrics based on the four "golden signals" of monitoring (latency, traffic, errors, and
-  saturation). Istio also provides detailed metrics for the [mesh control plane](/docs/ops/architecture/).
+  saturation). Istio also provides detailed metrics for the [mesh control plane](/docs/ops/deployment/architecture/).
   A default set of mesh monitoring dashboards built on top of these metrics is also provided.
 - [**Distributed Traces**](#distributed-traces). Istio generates distributed trace spans for each service, providing operators with a detailed understanding
   of call flows and service dependencies within a mesh.

content/en/docs/concepts/security/index.md

@@ -161,96 +161,6 @@ The flow goes as follows:
 Use the node agent debug endpoint to view the secrets a node agent is actively serving to its client proxies. Navigate to `/debug/sds/workload` on the agent's port `8080` to dump active workload secrets, or `/debug/sds/gateway` to dump active gateway secrets.
 {{< /idea >}}
 
-## Best practices
-
-In this section, we provide a few deployment guidelines and discuss a real-world scenario.
-
-### Deployment guidelines
-
-If there are multiple service operators (a.k.a. [SREs](https://en.wikipedia.org/wiki/Site_reliability_engineering))
-deploying different services in a medium- or large-size cluster, we recommend creating a separate
-[Kubernetes namespace](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/) for each SRE team to isolate their access.
-For example, you can create a `team1-ns` namespace for `team1`, and `team2-ns` namespace for `team2`, such
-that both teams cannot access each other's services.
-
-{{< warning >}}
-If Citadel is compromised, all its managed keys and certificates in the cluster may be exposed.
-We **strongly** recommend running Citadel in a dedicated namespace (for example, `istio-citadel-ns`), to restrict access to
-the cluster to only administrators.
-{{< /warning >}}
-
-### Example
-
-Let us consider a three-tier application with three services: `photo-frontend`,
-`photo-backend`, and `datastore`. The photo SRE team manages the
-`photo-frontend` and `photo-backend` services while the datastore SRE team
-manages the `datastore` service. The `photo-frontend` service can access
-`photo-backend`, and the `photo-backend` service can access `datastore`.
-However, the `photo-frontend` service cannot access `datastore`.
-
-In this scenario, a cluster administrator creates three namespaces:
-`istio-citadel-ns`, `photo-ns`, and `datastore-ns`. The administrator has
-access to all namespaces and each team only has access to its own namespace.
-The photo SRE team creates two service accounts to run `photo-frontend` and
-`photo-backend` respectively in the `photo-ns` namespace. The datastore SRE
-team creates one service account to run the `datastore` service in the
-`datastore-ns` namespace. Moreover, we need to enforce the service access
-control in [Istio Mixer](/docs/reference/config/policy-and-telemetry/) such that
-`photo-frontend` cannot access datastore.
-
-In this setup, Kubernetes can isolate the operator privileges on managing the services.
-Istio manages certificates and keys in all namespaces
-and enforces different access control rules to the services.
-
-### How Citadel determines whether to create service account secrets
-
-When a Citadel instance notices that a `ServiceAccount` is created in a namespace, it must decide whether it should generate an `istio.io/key-and-cert` secret for that `ServiceAccount`. In order to make that decision, Citadel considers three inputs (note: there can be multiple Citadel instances deployed in a single cluster, and the following targeting rules are applied to each instance):
-
-1. `ca.istio.io/env` namespace label: *string valued* label containing the namespace of the desired Citadel instance
-
-1. `ca.istio.io/override` namespace label: *boolean valued* label which overrides all other configurations and forces all Citadel instances either to target or ignore a namespace
-
-1. [`enableNamespacesByDefault` security configuration](/docs/reference/config/installation-options/#security-options): default behavior if no labels are found on the `ServiceAccount`'s namespace
-
-From these three values, the decision process mirrors that of the [`Sidecar Injection Webhook`](/docs/ops/setup/injection-concepts/). The detailed behavior is that:
-
-- If `ca.istio.io/override` exists and is `true`, generate key/cert secrets for workloads.
-
-- Otherwise, if `ca.istio.io/override` exists and is `false`, don't generate key/cert secrets for workloads.
-
-- Otherwise, if a `ca.istio.io/env: "ns-foo"` label is defined in the service account's namespace, the Citadel instance in namespace `ns-foo` will be used for generating key/cert secrets for workloads in the `ServiceAccount`'s namespace.
-
-- Otherwise, set `enableNamespacesByDefault` to `true` during installation. If it is `true`, the default Citadel instance will be used for generating key/cert secrets for workloads in the `ServiceAccount`'s namespace.
-
-- Otherwise, no secrets are created for the `ServiceAccount`'s namespace.
-
-This logic is captured in the truth table below:
-
-| `ca.istio.io/override` value | `ca.istio.io/env` match | `enableNamespacesByDefault` configuration | Workload secret created |
-|------------------------------|-------------------------|-------------------------------------------|-------------------------|
-|`true`|yes|`true`|yes|
-|`true`|yes|`false`|yes|
-|`true`|no|`true`|yes|
-|`true`|no|`false`|yes|
-|`true`|unset|`true`|yes|
-|`true`|unset|`false`|yes|
-|`false`|yes|`true`|no|
-|`false`|yes|`false`|no|
-|`false`|no|`true`|no|
-|`false`|no|`false`|no|
-|`false`|unset|`true`|no|
-|`false`|unset|`false`|no|
-|unset|yes|`true`|yes|
-|unset|yes|`false`|yes|
-|unset|no|`true`|no|
-|unset|no|`false`|no|
-|unset|unset|`true`|yes|
-|unset|unset|`false`|no|
-
-{{< idea >}}
-When a namespace transitions from _disabled_ to _enabled_, Citadel will retroactively generate secrets for all `ServiceAccounts` in that namespace. When transitioning from _enabled_ to _disabled_, however, Citadel will not delete the namespace's generated secrets until the root certificate is renewed.
-{{< /idea >}}
-
 ## Authentication
 
 Istio provides two types of authentication:

content/en/docs/concepts/traffic-management/index.md

@@ -29,7 +29,7 @@ changes to your services.
 
 If you’re interested in the details of how the features described in this guide
 work, you can find out more about Istio’s traffic management implementation in the
-[architecture overview](/docs/ops/architecture/). The rest of
+[architecture overview](/docs/ops/deployment/architecture/). The rest of
 this guide introduces Istio’s traffic management features.
 
 ## Introducing Istio traffic management

content/en/docs/examples/platform/gke/index.md

@@ -9,7 +9,7 @@ aliases:
 ---
 
 This example shows how to configure a multicluster mesh with a
-[single-network deployment](/docs/ops/prep/deployment-models/#single-network)
+[single-network deployment](/docs/ops/deployment/deployment-models/#single-network)
 over 2 [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) clusters.
 
 ## Before you begin

content/en/docs/examples/platform/icp/index.md

@@ -11,7 +11,7 @@ aliases:
 This example demonstrates how to setup network connectivity between two
 [IBM Cloud Private](https://www.ibm.com/cloud/private) clusters
 and then compose them into a multicluster mesh using a
-[single-network deployment](/docs/ops/prep/deployment-models/#single-network).
+[single-network deployment](/docs/ops/deployment/deployment-models/#single-network).
 
 ## Create the IBM Cloud Private clusters
 

content/en/docs/examples/virtual-machines/multi-network/index.md

@@ -87,7 +87,7 @@ following commands on a machine with cluster admin privileges:
 
 1. Determine and store the IP address of the Istio ingress gateway since the
    VMs access [Citadel](/docs/concepts/security/) and
-   [Pilot](/docs/ops/architecture/#pilot) and workloads on cluster through
+   [Pilot](/docs/ops/deployment/architecture/#pilot) and workloads on cluster through
    this IP address.
 
     {{< text bash >}}

content/en/docs/examples/virtual-machines/single-network/index.md

@@ -93,7 +93,7 @@ following commands on a machine with cluster admin privileges:
 
 1. Determine and store the IP address of the Istio ingress gateway since the VMs
    access [Citadel](/docs/concepts/security/) and
-   [Pilot](/docs/ops/architecture/#pilot) through this IP address.
+   [Pilot](/docs/ops/deployment/architecture/#pilot) through this IP address.
 
     {{< text bash >}}
     $ export GWIP=$(kubectl get -n istio-system service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

content/en/docs/ops/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Operations
-description: Hints, tips, tricks about running an Istio mesh.
+description: Concepts, tools, and techniques to deploy and manage an Istio mesh.
 weight: 32
 aliases:
     - /troubleshooting.html

content/en/docs/ops/best-practices/_index.md

@@ -0,0 +1,10 @@
+---
+title: Best Practices
+description: Best practices for setting up and managing an Istio service mesh.
+weight: 30
+keywords: [ops]
+aliases:
+    - /help/ops/troubleshooting
+    - /help/ops/traffic-management/troubleshooting
+    - /help/ops/setup
+---

content/en/docs/ops/best-practices/deployment/index.md

@@ -1,9 +1,10 @@
 ---
 title: Deployment Best Practices
-description: General best practices for your Istio deployments.
-weight: 2
-icon: best-practices
-keywords: [deployment-models, cluster, availability-zones, control-plane]
+description: General best practices when setting up an Istio service mesh.
+force_inline_toc: true
+weight: 10
+aliases:
+  - /docs/ops/prep/deployment
 ---
 
 We have identified the following general principles to help you get the most
@@ -14,7 +15,7 @@ bad configuration changes and make managing your deployments easier.
 
 Deploy Istio across a small number of large clusters, rather than a large number
 of small clusters. Instead of adding clusters to your deployment, the best
-practice is to use [namespace tenancy](/docs/ops/prep/deployment-models/#namespace-tenancy)
+practice is to use [namespace tenancy](/docs/ops/deployment/deployment-models/#namespace-tenancy)
 to manage large clusters. Following this approach, you can deploy Istio across
 one or two clusters per zone or region. You can then deploy a control plane on
 one cluster per region or zone for added reliability.

content/en/docs/ops/best-practices/security/index.md

@@ -0,0 +1,43 @@
+---
+title: Security Best Practices
+description: Best practices for securing applications using Istio.
+force_inline_toc: true
+weight: 30
+---
+
+This section provides some deployment guidelines to help keep a service mesh secure.
+
+## Use namespaces for isolation
+
+If there are multiple service operators (a.k.a. [SREs](https://en.wikipedia.org/wiki/Site_reliability_engineering))
+deploying different services in a medium- or large-size cluster, we recommend creating a separate
+[Kubernetes namespace](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/) for each SRE team to isolate their access.
+For example, you can create a `team1-ns` namespace for `team1`, and `team2-ns` namespace for `team2`, such
+that both teams cannot access each other's services.
+
+{{< warning >}}
+If Citadel is compromised, all its managed keys and certificates in the cluster may be exposed.
+We **strongly** recommend running Citadel in a dedicated namespace (for example, `istio-citadel-ns`), to restrict access to
+the cluster to only administrators.
+{{< /warning >}}
+
+Let us consider a three-tier application with three services: `photo-frontend`,
+`photo-backend`, and `datastore`. The photo SRE team manages the
+`photo-frontend` and `photo-backend` services while the datastore SRE team
+manages the `datastore` service. The `photo-frontend` service can access
+`photo-backend`, and the `photo-backend` service can access `datastore`.
+However, the `photo-frontend` service cannot access `datastore`.
+
+In this scenario, a cluster administrator creates three namespaces:
+`istio-citadel-ns`, `photo-ns`, and `datastore-ns`. The administrator has
+access to all namespaces and each team only has access to its own namespace.
+The photo SRE team creates two service accounts to run `photo-frontend` and
+`photo-backend` respectively in the `photo-ns` namespace. The datastore SRE
+team creates one service account to run the `datastore` service in the
+`datastore-ns` namespace. Moreover, we need to enforce the service access
+control in [Istio Mixer](/docs/reference/config/policy-and-telemetry/) such that
+`photo-frontend` cannot access datastore.
+
+In this setup, Kubernetes can isolate the operator privileges on managing the services.
+Istio manages certificates and keys in all namespaces
+and enforces different access control rules to the services.

content/en/docs/ops/best-practices/traffic-management/index.md

@@ -1,15 +1,99 @@
 ---
-title: Avoiding Traffic Management Issues
-description: Provides specific deployment or configuration guidelines to avoid networking or traffic management issues.
-weight: 2
+title: Traffic Management Best Practices
+description: Configuration best practices to avoid networking or traffic management issues.
+force_inline_toc: true
+weight: 20
 aliases:
-    - /help/ops/traffic-management/deploy-guidelines
-    - /help/ops/deploy-guidelines
+  - /help/ops/traffic-management/deploy-guidelines
+  - /help/ops/deploy-guidelines
+  - /docs/ops/traffic-management/deploy-guidelines
 ---
 
 This section provides specific deployment or configuration guidelines to avoid networking or traffic management issues.
 
-## Cross-namespace configuration sharing
+## Set default routes for services
+
+Although the default Istio behavior conveniently sends traffic from any
+source to all versions of a destination service without any rules being set,
+creating a `VirtualService` with a default route for every service,
+right from the start, is generally considered a best practice in Istio.
+
+Even if you initially have only one version of a service, as soon as you decide
+to deploy a second version, you need to have a routing rule in place **before**
+the new version is started, to prevent it from immediately receiving traffic
+in an uncontrolled way.
+
+Another potential issue when relying on Istio's default round-robin routing is
+due to a subtlety in Istio's destination rule evaluation algorithm.
+When routing a request, Envoy first evaluates route rules in virtual services
+to determine if a particular subset is being routed to.
+If so, only then will it activate any destination rule policies corresponding to the subset.
+Consequently, Istio only applies the policies you define for specific subsets if
+you **explicitly** routed traffic to the corresponding subset.
+
+For example, consider the following destination rule as the one and only configuration defined for the
+*reviews* service, that is, there are no route rules in a corresponding `VirtualService` definition:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: DestinationRule
+metadata:
+  name: reviews
+spec:
+  host: reviews
+  subsets:
+  - name: v1
+    labels:
+      version: v1
+    trafficPolicy:
+      connectionPool:
+        tcp:
+          maxConnections: 100
+{{< /text >}}
+
+Even if Istio’s default round-robin routing calls "v1" instances on occasion,
+maybe even always if "v1" is the only running version, the above traffic policy
+will never be invoked.
+
+You can fix the above example in one of two ways. You can either move the
+traffic policy up a level in the `DestinationRule` to make it apply to any version:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: DestinationRule
+metadata:
+  name: reviews
+spec:
+  host: reviews
+  trafficPolicy:
+    connectionPool:
+      tcp:
+        maxConnections: 100
+  subsets:
+  - name: v1
+    labels:
+      version: v1
+{{< /text >}}
+
+Or, better yet, define a proper route rule for the service in the `VirtualService` definition.
+For example, add a simple route rule for "reviews:v1":
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: reviews
+spec:
+  hosts:
+  - reviews
+  http:
+  - route:
+    - destination:
+        host: reviews
+        subset: v1
+{{< /text >}}
+
+## Control configuration sharing across namespaces {#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
@@ -93,98 +177,12 @@ Istio uses this restricted destination rule lookup path for two reasons:
 1. Have a clear lookup order in case there is more than one destination rule for
    the same host.
 
-## Configuring multiple TLS hosts in a gateway
-
-If you apply a `Gateway` configuration that has the same `selector` labels as another
-existing `Gateway`, then if they both expose the same HTTPS port you must ensure that they have
-unique port names. Otherwise, the configuration will be applied without an immediate error indication
-but it will be ignored in the runtime gateway configuration. For example:
-
-{{< text yaml >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
-  name: mygateway
-spec:
-  selector:
-    istio: ingressgateway # use istio default ingress gateway
-  servers:
-  - port:
-      number: 443
-      name: https
-      protocol: HTTPS
-    tls:
-      mode: SIMPLE
-      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
-      privateKey: /etc/istio/ingressgateway-certs/tls.key
-    hosts:
-    - "myhost.com"
----
-apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
-  name: mygateway2
-spec:
-  selector:
-    istio: ingressgateway # use istio default ingress gateway
-  servers:
-  - port:
-      number: 443
-      name: https
-      protocol: HTTPS
-    tls:
-      mode: SIMPLE
-      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
-      privateKey: /etc/istio/ingressgateway-certs/tls.key
-    hosts:
-    - "myhost2.com"
-{{< /text >}}
-
-With this configuration, requests to the second host, `myhost2.com`, will fail because
-both gateway ports have `name: https`.
-A _curl_ request, for example, will produce an error message something like this:
-
-{{< text plain >}}
-curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to myhost2.com:443
-{{< /text >}}
-
-You can confirm that this has happened by checking Pilot's logs for a message similar to the following:
-
-{{< text bash >}}
-$ kubectl logs -n istio-system $(kubectl get pod -l istio=pilot -n istio-system -o jsonpath={.items..metadata.name}) -c discovery | grep "non unique port"
-2018-09-14T19:02:31.916960Z info    model   skipping server on gateway mygateway2 port https.443.HTTPS: non unique port name for HTTPS port
-{{< /text >}}
-
-To avoid this problem, ensure that multiple uses of the same `protocol: HTTPS` port are uniquely named.
-For example, change the second one to `https2`:
-
-{{< text yaml >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
-  name: mygateway2
-spec:
-  selector:
-    istio: ingressgateway # use istio default ingress gateway
-  servers:
-  - port:
-      number: 443
-      name: https2
-      protocol: HTTPS
-    tls:
-      mode: SIMPLE
-      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
-      privateKey: /etc/istio/ingressgateway-certs/tls.key
-    hosts:
-    - "myhost2.com"
-{{< /text >}}
-
-## Multiple virtual services and destination rules for the same host
+## Split large virtual services and destination rules into multiple resources {#split-virtual-services}
 
 In situations where it is inconvenient to define the complete set of route rules or policies for a particular
 host in a single `VirtualService` or `DestinationRule` resource, it may be preferable to incrementally specify
 the configuration for the host in multiple resources.
-Starting with Istio 1.0.1, Pilot will merge such destination rules
+Pilot will merge such destination rules
 and merge such virtual services if they are bound to a gateway.
 
 Consider the case of a `VirtualService` bound to an ingress gateway exposing an application host which uses

content/en/docs/ops/common-problems/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Common Problems
 description: Describes how to identify and resolve common problems in Istio.
-weight: 70
+weight: 40
 keywords: [ops]
 aliases:
     - /help/ops/troubleshooting

content/en/docs/ops/common-problems/network-issues/index.md

@@ -1,5 +1,5 @@
 ---
-title: Networking Problems
+title: Traffic Management Problems
 description: Techniques to address common Istio traffic management and network problems.
 force_inline_toc: true
 weight: 10
@@ -52,7 +52,7 @@ but similar version routing rules have no effect on your own application, it may
 your Kubernetes services need to be changed slightly.
 Kubernetes services must adhere to certain restrictions in order to take advantage of
 Istio's L7 routing features.
-Refer to the [Requirements for Pods and Services](/docs/ops/prep/requirements/)
+Refer to the [Requirements for Pods and Services](/docs/ops/deployment/requirements/)
 for details.
 
 Another potential issue is that the route rules may simply be slow to take effect.
@@ -63,87 +63,6 @@ to propagate to all the sidecars.  With large deployments the
 propagation will take longer and there may be a lag time on the
 order of seconds.
 
-## Destination rule policy not activated
-
-Although destination rules are associated with a particular destination host,
-the activation of subset-specific policies depends on route rule evaluation.
-
-When routing a request, Envoy first evaluates route rules in virtual services
-to determine if a particular subset is being routed to.
-If so, only then will it activate any destination rule policies corresponding to the subset.
-Consequently, Istio only applies the policies you define for specific subsets if
-you explicitly routed traffic to the corresponding subset.
-
-For example, consider the following destination rule as the one and only configuration defined for the
-*reviews* service, that is, there are no route rules in a corresponding `VirtualService` definition:
-
-{{< text yaml >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
-  name: reviews
-spec:
-  host: reviews
-  subsets:
-  - name: v1
-    labels:
-      version: v1
-    trafficPolicy:
-      connectionPool:
-        tcp:
-          maxConnections: 100
-{{< /text >}}
-
-Even if Istio's default round-robin routing calls "v1" instances on occasion,
-maybe even always if "v1" is the only running version, the above traffic policy will never be invoked.
-
-You can fix the above example in one of two ways:
-
-1. Move the traffic policy in the destination rule up a level to make the policy
-    apply to any subset, for example:
-
-    {{< text yaml >}}
-    apiVersion: networking.istio.io/v1alpha3
-    kind: DestinationRule
-    metadata:
-      name: reviews
-    spec:
-      host: reviews
-      trafficPolicy:
-        connectionPool:
-          tcp:
-            maxConnections: 100
-      subsets:
-      - name: v1
-        labels:
-          version: v1
-    {{< /text >}}
-
-1. Define proper route rules for the service using a `VirtualService`.
-    For example, add a simple route rule for the `v1` subset of the `reviews` service:
-
-    {{< text yaml >}}
-    apiVersion: networking.istio.io/v1alpha3
-    kind: VirtualService
-    metadata:
-      name: reviews
-    spec:
-      hosts:
-      - reviews
-      http:
-      - route:
-        - destination:
-            host: reviews
-            subset: v1
-    {{< /text >}}
-
-The default Istio behavior conveniently sends traffic from any source
-to all versions of the destination service without you setting any rules.
-As soon as you need to differentiate between the versions of a service,
-you need to define routing rules.
-Due to this fact, we consider a best practice to set a default routing rule
-for every service from the start.
-
 ## 503 errors after setting destination rule
 
 If requests to a service immediately start generating HTTP 503 errors after you applied a `DestinationRule`
@@ -369,3 +288,89 @@ Then, simply bind both `VirtualServices` to it like this:
 - `Gateway` configuration `gw` with host `*.test.com`, selector `istio: ingressgateway`, and TLS using gateway's mounted (wildcard) certificate
 - `VirtualService` configuration `vs1` with host `service1.test.com` and gateway `gw`
 - `VirtualService` configuration `vs2` with host `service2.test.com` and gateway `gw`
+
+## Port conflict when configuring multiple TLS hosts in a gateway
+
+If you apply a `Gateway` configuration that has the same `selector` labels as another
+existing `Gateway`, then if they both expose the same HTTPS port you must ensure that they have
+unique port names. Otherwise, the configuration will be applied without an immediate error indication
+but it will be ignored in the runtime gateway configuration. For example:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: mygateway
+spec:
+  selector:
+    istio: ingressgateway # use istio default ingress gateway
+  servers:
+  - port:
+      number: 443
+      name: https
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+    hosts:
+    - "myhost.com"
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: mygateway2
+spec:
+  selector:
+    istio: ingressgateway # use istio default ingress gateway
+  servers:
+  - port:
+      number: 443
+      name: https
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+    hosts:
+    - "myhost2.com"
+{{< /text >}}
+
+With this configuration, requests to the second host, `myhost2.com`, will fail because
+both gateway ports have `name: https`.
+A _curl_ request, for example, will produce an error message something like this:
+
+{{< text plain >}}
+curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to myhost2.com:443
+{{< /text >}}
+
+You can confirm that this has happened by checking Pilot's logs for a message similar to the following:
+
+{{< text bash >}}
+$ kubectl logs -n istio-system $(kubectl get pod -l istio=pilot -n istio-system -o jsonpath={.items..metadata.name}) -c discovery | grep "non unique port"
+2018-09-14T19:02:31.916960Z info    model   skipping server on gateway mygateway2 port https.443.HTTPS: non unique port name for HTTPS port
+{{< /text >}}
+
+To avoid this problem, ensure that multiple uses of the same `protocol: HTTPS` port are uniquely named.
+For example, change the second one to `https2`:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: mygateway2
+spec:
+  selector:
+    istio: ingressgateway # use istio default ingress gateway
+  servers:
+  - port:
+      number: 443
+      name: https2
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+    hosts:
+    - "myhost2.com"
+{{< /text >}}

content/en/docs/ops/common-problems/observability-issues/index.md

@@ -29,7 +29,7 @@ If the Istio Dashboard or the Prometheus queries don’t show the expected metri
 
 ### Verify Istio CNI pods are running (if used)
 
-The Istio CNI plugin performs the Istio mesh pod traffic redirection in the Kubernetes pod lifecycle’s network setup phase, thereby removing the [`NET_ADMIN` capability requirement](/docs/ops/prep/requirements/) for users deploying pods into the Istio mesh. The Istio CNI plugin replaces the functionality provided by the `istio-init` container.
+The Istio CNI plugin performs the Istio mesh pod traffic redirection in the Kubernetes pod lifecycle’s network setup phase, thereby removing the [`NET_ADMIN` capability requirement](/docs/ops/deployment/requirements/) for users deploying pods into the Istio mesh. The Istio CNI plugin replaces the functionality provided by the `istio-init` container.
 
 1. Verify that the `istio-cni-node` pods are running:
 
@@ -37,7 +37,7 @@ The Istio CNI plugin performs the Istio mesh pod traffic redirection in the Kube
     $ kubectl -n kube-system get pod -l k8s-app=istio-cni-node
     {{< /text >}}
 
-1. If `PodSecurityPolicy` is being enforced in your cluster, ensure the `istio-cni` service account can use a `PodSecurityPolicy` with the [`NET_ADMIN` capability requirement](/docs/ops/prep/requirements/)
+1. If `PodSecurityPolicy` is being enforced in your cluster, ensure the `istio-cni` service account can use a `PodSecurityPolicy` with the [`NET_ADMIN` capability requirement](/docs/ops/deployment/requirements/)
 ### Verify Mixer is receiving report calls
 
 Mixer generates metrics to monitor its own behavior. The first step is to check these metrics:

content/en/docs/ops/configuration/_index.md

@@ -0,0 +1,8 @@
+---
+title: Configuration
+description: Advanced concepts and features for configuring a running Istio mesh.
+weight: 20
+keywords: [ops,setup]
+aliases:
+    - /help/ops/setup
+---

content/en/docs/ops/configuration/mesh/_index.md

@@ -0,0 +1,6 @@
+---
+title: Mesh Configuration
+description: Helps you manage the global mesh configuration.
+weight: 10
+keywords: [ops,mesh]
+---

content/en/docs/ops/configuration/mesh/app-health-check/index.md

@@ -1,13 +1,14 @@
 ---
 title: Health Checking of Istio Services
 description: Shows how to do health checking for Istio services.
-weight: 60
+weight: 50
 aliases:
   - /docs/tasks/traffic-management/app-health-check/
   - /docs/ops/security/health-checks-and-mtls/
   - /help/ops/setup/app-health-check
   - /help/ops/app-health-check
   - /docs/ops/app-health-check
+  - /docs/ops/setup/app-health-check
 keywords: [security,health-check]
 ---
 

content/en/docs/ops/configuration/mesh/injection-concepts/index.md

@@ -1,9 +1,10 @@
 ---
 title: Automatic Sidecar Injection
 description: Describes Istio's use of Kubernetes webhooks for automatic sidecar injection.
-weight: 5
+weight: 20
 aliases:
-    - /help/ops/setup/injection
+  - /help/ops/setup/injection
+  - /docs/ops/setup/injection-concepts
 ---
 
 Automatic sidecar injection adds the sidecar proxy into user-created

content/en/docs/ops/configuration/mesh/secret-creation/index.md

@@ -0,0 +1,55 @@
+---
+title: Service Account Secret Creation
+description: Describes how Citadel determines whether to create service account secrets.
+weight: 30
+---
+
+When a Citadel instance notices that a `ServiceAccount` is created in a namespace, it must decide whether
+it should generate an `istio.io/key-and-cert` secret for that `ServiceAccount`.
+In order to make that decision, Citadel considers three inputs (note: there can be multiple Citadel instances
+deployed in a single cluster, and the following targeting rules are applied to each instance):
+
+1. `ca.istio.io/env` namespace label: *string valued* label containing the namespace of the desired Citadel instance
+
+1. `ca.istio.io/override` namespace label: *boolean valued* label which overrides all other configurations and forces all Citadel instances either to target or ignore a namespace
+
+1. [`enableNamespacesByDefault` security configuration](/docs/reference/config/installation-options/#security-options): default behavior if no labels are found on the `ServiceAccount`'s namespace
+
+From these three values, the decision process mirrors that of the [`Sidecar Injection Webhook`](/docs/ops/configuration/mesh/injection-concepts/). The detailed behavior is that:
+
+- If `ca.istio.io/override` exists and is `true`, generate key/cert secrets for workloads.
+
+- Otherwise, if `ca.istio.io/override` exists and is `false`, don't generate key/cert secrets for workloads.
+
+- Otherwise, if a `ca.istio.io/env: "ns-foo"` label is defined in the service account's namespace, the Citadel instance in namespace `ns-foo` will be used for generating key/cert secrets for workloads in the `ServiceAccount`'s namespace.
+
+- Otherwise, set `enableNamespacesByDefault` to `true` during installation. If it is `true`, the default Citadel instance will be used for generating key/cert secrets for workloads in the `ServiceAccount`'s namespace.
+
+- Otherwise, no secrets are created for the `ServiceAccount`'s namespace.
+
+This logic is captured in the truth table below:
+
+| `ca.istio.io/override` value | `ca.istio.io/env` match | `enableNamespacesByDefault` configuration | Workload secret created |
+|------------------------------|-------------------------|-------------------------------------------|-------------------------|
+|`true`|yes|`true`|yes|
+|`true`|yes|`false`|yes|
+|`true`|no|`true`|yes|
+|`true`|no|`false`|yes|
+|`true`|unset|`true`|yes|
+|`true`|unset|`false`|yes|
+|`false`|yes|`true`|no|
+|`false`|yes|`false`|no|
+|`false`|no|`true`|no|
+|`false`|no|`false`|no|
+|`false`|unset|`true`|no|
+|`false`|unset|`false`|no|
+|unset|yes|`true`|yes|
+|unset|yes|`false`|yes|
+|unset|no|`true`|no|
+|unset|no|`false`|no|
+|unset|unset|`true`|yes|
+|unset|unset|`false`|no|
+
+{{< idea >}}
+When a namespace transitions from _disabled_ to _enabled_, Citadel will retroactively generate secrets for all `ServiceAccounts` in that namespace. When transitioning from _enabled_ to _disabled_, however, Citadel will not delete the namespace's generated secrets until the root certificate is renewed.
+{{< /idea >}}

content/en/docs/ops/configuration/mesh/validation/index.md

@@ -1,9 +1,10 @@
 ---
 title: Configuration Validation Webhook
 description: Describes Istio's use of Kubernetes webhooks for server-side configuration validation.
-weight: 20
+weight: 40
 aliases:
-    - /help/ops/setup/validation   
+  - /help/ops/setup/validation
+  - /docs/ops/setup/validation
 ---
 
 Galley's configuration validation ensures user authored Istio

content/en/docs/ops/configuration/mesh/webhook/index.md

@@ -3,7 +3,8 @@ title: Dynamic Admission Webhooks Overview
 description: Provides a general overview of Istio's use of Kubernetes webhooks and the related issues that can arise.
 weight: 10
 aliases:
-    - /help/ops/setup/webhook
+  - /help/ops/setup/webhook
+  - /docs/ops/setup/webhook
 ---
 
 From [Kubernetes mutating and validating webhook mechanisms](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/):

content/en/docs/ops/configuration/security/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Security
 description: Helps you manage the security aspects of a running mesh.
-weight: 50
+weight: 30
 keywords: [ops,security]
 aliases:
     - /help/ops/security

content/en/docs/ops/configuration/security/harden-docker-images/index.md

@@ -3,7 +3,8 @@ title: Harden Docker Container Images
 description: Use hardened container images to reduce Istio's attack surface.
 weight: 80
 aliases:
-    - /help/ops/security/harden-docker-images
+  - /help/ops/security/harden-docker-images
+  - /docs/ops/security/harden-docker-images
 ---
 To ease the process of hardening docker images, Istio provides a set of images based on  [distroless images](https://github.com/GoogleContainerTools/distroless)
 

content/en/docs/ops/configuration/security/root-transition/index.md

@@ -4,7 +4,8 @@ description: Learn how to extend the lifetime of the Istio self-signed root cert
 weight: 90
 keywords: [security, PKI, certificate, Citadel]
 aliases:
-    - /help/ops/security/root-transition
+  - /help/ops/security/root-transition
+  - /docs/ops/security/root-transition
 ---
 
 Istio self-signed certificates have historically had a 1 year default lifetime.

content/en/docs/ops/configuration/telemetry/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Observability
 description: Helps you manage telemetry collection and visualization in a running mesh.
-weight: 60
+weight: 40
 keywords: [ops,telemetry]
 aliases:
     - /help/ops/telemetry

content/en/docs/ops/configuration/telemetry/envoy-stats/index.md

@@ -1,9 +1,10 @@
 ---
 title: Envoy Statistics
 description: Fine-grained control of Envoy statistics.
-weight: 95
+weight: 10
 aliases:
-    - /help/ops/telemetry/envoy-stats
+  - /help/ops/telemetry/envoy-stats
+  - /docs/ops/telemetry/envoy-stats
 ---
 
 The Envoy proxy keeps detailed statistics about network traffic.

content/en/docs/ops/configuration/telemetry/in-proxy-service-telemetry/index.md

@@ -1,7 +1,9 @@
 ---
 title: Generate Istio Metrics Without Mixer [Alpha]
 description: How to enable in-proxy generation of HTTP service-level metrics.
-weight: 70
+weight: 20
+aliases:
+  - /docs/ops/telemetry/in-proxy-service-telemetry
 ---
 
 Istio 1.4 adds alpha support to generate service-level HTTP metrics

content/en/docs/ops/configuration/traffic-management/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Traffic Management
 description: Helps you manage the networking aspects of a running mesh.
-weight: 40
+weight: 20
 keywords: [ops,traffic-management]
 aliases:
     - /help/ops/traffic-management

content/en/docs/ops/configuration/traffic-management/locality-load-balancing/index.md

@@ -1,12 +1,13 @@
 ---
 title: Locality Load Balancing
 description: Information on how to enable and understand Locality Load Balancing.
-weight: 98
+weight: 20
 keywords: [locality,load balancing,priority,prioritized]
 aliases:
-    - /help/ops/traffic-management/locality-load-balancing
-    - /help/ops/locality-load-balancing
-    - /help/tasks/traffic-management/locality-load-balancing
+  - /help/ops/traffic-management/locality-load-balancing
+  - /help/ops/locality-load-balancing
+  - /help/tasks/traffic-management/locality-load-balancing
+  - /docs/ops/traffic-management/locality-load-balancing
 ---
 
 A locality defines a geographic location within your mesh using the following triplet:

content/en/docs/ops/configuration/traffic-management/protocol-selection/index.md

@@ -1,12 +1,13 @@
 ---
 title: Protocol Selection
 description: Information on how to specify protocols.
-weight: 98
+weight: 10
 keywords: [protocol,protocol sniffing,protocol selection,protocol detection]
 aliases:
-    - /help/ops/traffic-management/protocol-selection
-    - /help/ops/protocol-selection
-    - /help/tasks/traffic-management/protocol-selection
+  - /help/ops/traffic-management/protocol-selection
+  - /help/ops/protocol-selection
+  - /help/tasks/traffic-management/protocol-selection
+  - /docs/ops/traffic-management/protocol-selection
 ---
 
 Istio supports proxying all TCP traffic by default, but in order to provide additional capabilities,

content/en/docs/ops/deployment/_index.md

@@ -0,0 +1,12 @@
+---
+title: Deployment
+description: Requirements, concepts, and considerations for setting up an Istio deployment.
+weight: 10
+keywords:
+- deployment-models
+- best-practices
+- pods
+- requirements
+- installation
+- configuration
+---

content/en/docs/ops/deployment/architecture/index.md

@@ -1,9 +1,10 @@
 ---
 title: Architecture
 description: Describes Istio's high-level architecture and design goals.
-weight: 5
+weight: 10
 aliases:
-- /docs/concepts/architecture
+  - /docs/concepts/architecture
+  - /docs/ops/architecture
 ---
 
 An Istio service mesh is logically split into a **data plane** and a **control

content/en/docs/ops/deployment/deployment-models/index.md

@@ -1,20 +1,21 @@
 ---
 title: Deployment Models
 description: Describes the system models that impact your overall Istio depolyment.
-weight: 1
+weight: 20
 keywords:
-- single-cluster
-- multiple-clusters
-- control-plane
-- tenancy
-- networks
-- identity
-- trust
-- single-mesh
-- multiple-meshes
+  - single-cluster
+  - multiple-clusters
+  - control-plane
+  - tenancy
+  - networks
+  - identity
+  - trust
+  - single-mesh
+  - multiple-meshes
 aliases:
-- /docs/concepts/multicluster-deployments/
-- /docs/concepts/deployment-models
+  - /docs/concepts/multicluster-deployments
+  - /docs/concepts/deployment-models
+  - /docs/ops/prep/deployment-models
 ---
 
 Important system models impact your overall Istio deployment model. This page

content/en/docs/ops/deployment/performance-and-scalability/index.md

@@ -1,21 +1,22 @@
 ---
 title: Performance and Scalability
-description: Introduces performance and scalability for Istio.
-weight: 75
-aliases:
-- /docs/performance-and-scalability/overview
-- /docs/performance-and-scalability/microbenchmarks
-- /docs/performance-and-scalability/performance-testing-automation
-- /docs/performance-and-scalability/realistic-app-benchmark
-- /docs/performance-and-scalability/scalability
-- /docs/performance-and-scalability/scenarios
-- /docs/performance-and-scalability/synthetic-benchmarks
-- /docs/concepts/performance-and-scalability
+description: Istio performance and scalability summary.
+weight: 30
 keywords:
-- performance
-- scalability
-- scale
-- benchmarks
+  - performance
+  - scalability
+  - scale
+  - benchmarks
+aliases:
+  - /docs/performance-and-scalability/overview
+  - /docs/performance-and-scalability/microbenchmarks
+  - /docs/performance-and-scalability/performance-testing-automation
+  - /docs/performance-and-scalability/realistic-app-benchmark
+  - /docs/performance-and-scalability/scalability
+  - /docs/performance-and-scalability/scenarios
+  - /docs/performance-and-scalability/synthetic-benchmarks
+  - /docs/concepts/performance-and-scalability
+  - /docs/ops/performance-and-scalability
 ---
 
 Istio makes it easy to create a network of deployed services with rich routing,

content/en/docs/ops/deployment/requirements/index.md

@@ -2,22 +2,23 @@
 title: Pods and Services
 description: Prepare your Kubernetes pods and services to run in an Istio-enabled
   cluster.
-weight: 3
-aliases:
-- /docs/setup/kubernetes/spec-requirements/
-- /docs/setup/kubernetes/prepare/spec-requirements/
-- /docs/setup/kubernetes/prepare/requirements/
-- /docs/setup/kubernetes/additional-setup/requirements/
-- /docs/setup/additional-setup/requirements
-- /docs/ops/setup/required-pod-capabilities
-- /help/ops/setup/required-pod-capabilities
+weight: 40
 keywords:
-- kubernetes
-- sidecar
-- sidecar-injection
-- deployment-models
-- pods
-- setup
+  - kubernetes
+  - sidecar
+  - sidecar-injection
+  - deployment-models
+  - pods
+  - setup
+aliases:
+  - /docs/setup/kubernetes/spec-requirements/
+  - /docs/setup/kubernetes/prepare/spec-requirements/
+  - /docs/setup/kubernetes/prepare/requirements/
+  - /docs/setup/kubernetes/additional-setup/requirements/
+  - /docs/setup/additional-setup/requirements
+  - /docs/ops/setup/required-pod-capabilities
+  - /help/ops/setup/required-pod-capabilities
+  - /docs/ops/prep/requirements
 ---
 
 To be part of a mesh, Kubernetes pods and services must satisfy the following
@@ -25,7 +26,7 @@ requirements:
 
 - **Named service ports**: Service ports must be named. The port name key/value
   pairs must have the following syntax: `name: <protocol>[-<suffix>]`. See
-  [Protocol Selection](/docs/ops/traffic-management/protocol-selection/) for
+  [Protocol Selection](/docs/ops/configuration/traffic-management/protocol-selection/) for
   more details.
 
 - **Service association**: A pod must belong to at least one Kubernetes

content/en/docs/ops/diagnostic-tools/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Diagnostic Tools
 description: Tools and techniques to help troubleshoot an Istio mesh.
-weight: 80
+weight: 50
 keywords: [ops]
 aliases:
   - /docs/ops/troubleshooting/proxy-cmd

content/en/docs/ops/diagnostic-tools/istioctl-describe/index.md

@@ -39,7 +39,7 @@ before continuing.
 
 The `istioctl describe` command returns a warning if the {{< gloss >}}Envoy{{< /gloss >}}
 proxy is not present in a pod or if the proxy has not started. Additionally, the command warns
-if some of the [Istio requirements for pods](/docs/ops/prep/requirements/)
+if some of the [Istio requirements for pods](/docs/ops/deployment/requirements/)
 are not met.
 
 For example, the following command produces a warning indicating a `kubernetes-dashboard`

content/en/docs/ops/prep/_index.md

@@ -1,13 +0,0 @@
----
-title: Prepare Your Deployment
-description: Learn about how to prepare an Istio deployment including the
-            requirements for your pods and best practices.
-weight: 6
-keywords:
-- deployment-models
-- best-practices
-- pods
-- requirements
-- installation
-- configuration
----

content/en/docs/ops/setup/_index.md

@@ -1,8 +0,0 @@
----
-title: Installation and Configuration
-description: Requirements, concepts, and considerations for installing and configuring Istio.
-weight: 30
-keywords: [ops,setup]
-aliases:
-    - /help/ops/setup
----

content/en/docs/ops/traffic-management/introduction/index.md

@@ -1,64 +0,0 @@
----
-title: Introduction to Network Operations
-description: An introduction to Istio networking operational aspects.
-weight: 1
-aliases:
-    - /help/ops/traffic-management/introduction
-    - /help/ops/introduction
----
-This section is intended as a guide to operators of an Istio based
-deployment.  It will provide information an operator of a Istio deployment
-would need to manage the networking aspects of an Istio service mesh.  Much
-of the information and many of the procedures that an Istio operator
-would require are already documented in other sections of the Istio
-documentation so this section will rely heavily on pointers to that
-other content.
-
-## Key Istio concepts
-
-When attempting to understand, monitor or troubleshoot the networking within
-an Istio deployment it is critical to understand the fundamental Istio
-concepts starting with the service mesh.  The service mesh is described
-in [Architecture](/docs/ops/architecture/).  As noted
-in the architecture section Istio has a distinct control plane and a data
-plane and operationally it will be important to be able to monitor the
-network state of both.  The service mesh is a fully interconnected set of
-proxies that are utilized in both the control and data plane to provide
-the Istio features.
-
-Another key concept to understand is how Istio performs traffic management.
-This is described in [Traffic Management Explained](/docs/concepts/traffic-management).
-Traffic management allows fine grained control with respect to what external
-traffic can enter or exit the mesh and how those requests are routed.  The
-traffic management configuration also dictates how requests between
-microservices within the mesh are handled.  Full details on how to
-configure the traffic management is available
-here: [Traffic Management Configuration](/docs/tasks/traffic-management).
-
-The final concept that is essential for the operator to understand is how
-Istio uses gateways to allow traffic into the mesh or control how requests originating
-in the mesh access external services. This is described with a
-configuration example here:
-[Istio Gateways](/docs/concepts/traffic-management/#gateways)
-
-## Network layers beneath the mesh
-
-Istio's service mesh runs on top of the networking provided by the
-infrastructure environment (e.g. Kubernetes) on which the Istio mesh
-is deployed.  Istio has certain requirements of this networking layer.
-This guide will not attempt to provide any operational insight to this
-networking layer as many options exist.  In the case of Kubernetes a
-good reference to understand the container networking layer is
-[Kubernetes Cluster Operator](https://kubernetes.io/docs/user-journeys/users/cluster-operator/foundational/).
-Istio has the following requirements of the networking infrastructure
-underneath it:
-
-* The mapping of a service name to workload IP is discoverable by Pilot (this is more a service discovery requirement than a networking requirement)
-
-* The Pilot discovery process can reach the environment specific API server for service discovery.
-
-* Service endpoints have L3 reachability to all endpoints for services in the Istio mesh.
-
-* Any firewall or ACL rules at the infrastructure networking layer don't conflict with any of the Istio layer 3-7 traffic management rules
-
-* Any firewall or ACL rules at the infrastructure networking layer don't conflict with any of the ports used for Istio control traffic

content/en/docs/reference/config/networking/virtual-service/index.html

@@ -1981,7 +1981,7 @@ properties of the corresponding hosts, including those for multiple
 HTTP and TCP ports. Alternatively, the traffic properties of a host
 can be defined using more than one VirtualService, with certain
 caveats. Refer to the
-<a href="/docs/ops/traffic-management/deploy-guidelines/#multiple-virtual-services-and-destination-rules-for-the-same-host">Operations Guide</a>
+<a href="/docs/ops/best-practices/traffic-management/#split-virtual-services">Operations Guide</a>
 for details.</p>
 
 <p><em>Note for Kubernetes users</em>: When short names are used (e.g. &ldquo;reviews&rdquo;

content/en/docs/reference/glossary/mesh-federation.md

@@ -6,4 +6,4 @@ Mesh federation is the act of exposing services between meshes and enabling
 communication across mesh boundaries. Each mesh may expose a subset of its
 services to enable one or more other meshes to consume the exposed services. You
 can use mesh federation to enable communication between meshes in a
-[multi-mesh deployment](/docs/ops/prep/deployment-models/#multiple-meshes).
+[multi-mesh deployment](/docs/ops/deployment/deployment-models/#multiple-meshes).

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

@@ -24,7 +24,7 @@ networking functionality but without requiring Istio users to enable elevated
 Kubernetes RBAC permissions.
 
 The Istio CNI plugin performs the Istio mesh pod traffic redirection in the Kubernetes pod lifecycle's network
-setup phase, thereby removing the [`NET_ADMIN` capability requirement](/docs/ops/prep/requirements/)
+setup phase, thereby removing the [`NET_ADMIN` capability requirement](/docs/ops/deployment/requirements/)
 for users deploying pods into the Istio mesh.  The Istio CNI plugin
 replaces the functionality provided by the `istio-init` container.
 

content/en/docs/setup/additional-setup/config-profiles/index.md

@@ -34,7 +34,7 @@ your specific needs. The following built-in configuration profiles are currently
     This profile comes with additional authentication features enabled by default (Strict Mutual TLS).
 
 1. **remote**: used for configuring remote clusters of a
-    [multicluster mesh](/docs/ops/prep/deployment-models/#multiple-clusters) with a
+    [multicluster mesh](/docs/ops/deployment/deployment-models/#multiple-clusters) with a
     [shared control plane](/docs/setup/install/multicluster/shared-vpn/) configuration.
 
 The components marked as **X** are installed within each profile:

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

@@ -69,7 +69,7 @@ These instructions assume you are new to Istio, providing streamlined instructio
 install Istio's built-in `demo` [configuration profile](/docs/setup/additional-setup/config-profiles/).
 This installation lets you quickly get started evaluating Istio.
 If you are already familiar with Istio or interested in installing other configuration profiles
-or a more advanced [deployment model](/docs/ops/prep/deployment-models/),
+or a more advanced [deployment model](/docs/ops/deployment/deployment-models/),
 follow the [installing with {{< istioctl >}} instructions](/docs/setup/install/istioctl) instead.
 
 {{< warning >}}
@@ -186,9 +186,9 @@ The next step is to customize Istio and deploy your own applications.
 Before you install and customize Istio to fit your platform and intended use,
 check out the following resources:
 
-- [Deployment models](/docs/ops/prep/deployment-models/)
-- [Deployment best practices](/docs/ops/prep/deployment/)
-- [Pod requirements](/docs/ops/prep/requirements/)
+- [Deployment models](/docs/ops/deployment/deployment-models/)
+- [Deployment best practices](/docs/ops/best-practices/deployment/)
+- [Pod requirements](/docs/ops/deployment/requirements/)
 - [General installation instructions](/docs/setup/)
 
 As you continue to use Istio, we look forward to hearing from you and welcoming

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

@@ -35,7 +35,7 @@ and then further customize the configuration for your specific needs.
 
 1. Perform any necessary [platform-specific setup](/docs/setup/platform-setup/).
 
-1. Check the [Requirements for Pods and Services](/docs/ops/prep/requirements/).
+1. Check the [Requirements for Pods and Services](/docs/ops/deployment/requirements/).
 
 1. [Install a Helm client](https://github.com/helm/helm#install) with a version higher than 2.10.
 

content/en/docs/setup/install/istioctl/index.md

@@ -24,7 +24,7 @@ Before you begin, check the following prerequisites:
 
 1. [Download the Istio release](/docs/setup/getting-started/#download).
 1. Perform any necessary [platform-specific setup](/docs/setup/platform-setup/).
-1. Check the [Requirements for Pods and Services](/docs/ops/prep/requirements/).
+1. Check the [Requirements for Pods and Services](/docs/ops/deployment/requirements/).
 
 ## Install Istio using the default profile
 

content/en/docs/setup/install/multicluster/_index.md

@@ -16,5 +16,5 @@ a combination of the approaches can be used. For example,
 two clusters might share a control plane while a third has its own.
 {{< /tip >}}
 
-Refer to the [multicluster deployment model](/docs/ops/prep/deployment-models/#multiple-clusters)
+Refer to the [multicluster deployment model](/docs/ops/deployment/deployment-models/#multiple-clusters)
 concept documentation for more information.

content/en/docs/setup/install/multicluster/gateways/index.md

@@ -11,8 +11,8 @@ keywords: [kubernetes,multicluster,gateway]
 ---
 
 Follow this guide to install an Istio
-[multicluster deployment](/docs/ops/prep/deployment-models/#multiple-clusters)
-with replicated [control plane](/docs/ops/prep/deployment-models/#control-plane-models) instances
+[multicluster deployment](/docs/ops/deployment/deployment-models/#multiple-clusters)
+with replicated [control plane](/docs/ops/deployment/deployment-models/#control-plane-models) instances
 in every cluster and using gateways to connect services across clusters.
 
 Instead of using a shared Istio control plane to manage the mesh,

content/en/docs/setup/install/multicluster/shared-gateways/index.md

@@ -10,7 +10,7 @@ aliases:
 ---
 
 Follow this guide to configure a multicluster mesh using a shared
-[control plane](/docs/ops/prep/deployment-models/#control-plane-models)
+[control plane](/docs/ops/deployment/deployment-models/#control-plane-models)
 with gateways to connect network-isolated clusters.
 Istio's location-aware service routing feature is used to route requests to different endpoints,
 depending on the location of the request source.

content/en/docs/setup/install/multicluster/shared-vpn/index.md

@@ -9,14 +9,14 @@ aliases:
     - /docs/setup/kubernetes/install/multicluster/shared-vpn/
 ---
 
-Follow this guide to install an Istio [multicluster service mesh](/docs/ops/prep/deployment-models/#multiple-clusters)
+Follow this guide to install an Istio [multicluster service mesh](/docs/ops/deployment/deployment-models/#multiple-clusters)
 where the Kubernetes cluster services and the applications in each cluster
 have the capability to expose their internal Kubernetes network to other
 clusters.
 
 In this configuration, multiple Kubernetes clusters running
 a remote configuration connect to a shared Istio
-[control plane](/docs/ops/prep/deployment-models/#control-plane-models).
+[control plane](/docs/ops/deployment/deployment-models/#control-plane-models).
 Once one or more remote Kubernetes clusters are connected to the
 Istio control plane, Envoy can then form a mesh network across multiple clusters.
 

content/en/docs/setup/install/multicluster/simplified/index.md

@@ -10,7 +10,7 @@ keywords: [kubernetes,multicluster]
 This guide describes how to configure an Istio mesh that includes multiple Kubernetes clusters using a simplified experimental approach.
 We hope to continue developing this functionality in coming releases, so we'd love your feedback on the overall flow.
 
-We focus here on the details of getting a multicluster mesh wired up, refer to [multicluster deployment model](/docs/ops/prep/deployment-models/#multiple-clusters) for
+We focus here on the details of getting a multicluster mesh wired up, refer to [multicluster deployment model](/docs/ops/deployment/deployment-models/#multiple-clusters) for
 additional background information. We'll show how to connect two clusters that are on the same network together, along
 with a third cluster that's on a different network.
 

content/en/docs/setup/install/standalone-operator/index.md

@@ -19,7 +19,7 @@ instead.
 
 1. Perform any necessary [platform-specific setup](/docs/setup/platform-setup/).
 
-1. Check the [Requirements for Pods and Services](/docs/ops/prep/requirements/).
+1. Check the [Requirements for Pods and Services](/docs/ops/deployment/requirements/).
 
 1. Deploy the Istio operator:
 

content/en/docs/tasks/security/citadel-config/ca-namespace-targeting/index.md

@@ -6,13 +6,13 @@ aliases:
     - /docs/tasks/security/ca-namespace-targeting/
 ---
 
-A cluster operator might decide not to generate `ServiceAccount` secrets for some subset of namespaces, or to make `ServiceAccount` secret generation opt-in per namespace. This task describes how an operator can configure their cluster for these situations. Full documentation of the Citadel namespace targeting mechanism can be found [here](/docs/concepts/security/#how-citadel-determines-whether-to-create-service-account-secrets).
+A cluster operator might decide not to generate `ServiceAccount` secrets for some subset of namespaces, or to make `ServiceAccount` secret generation opt-in per namespace. This task describes how an operator can configure their cluster for these situations. Full documentation of the Citadel namespace targeting mechanism can be found [here]((/docs/ops/configuration/mesh/secret-creation/).
 
 ## Before you begin
 
 To complete this task, you should first take the following actions:
 
-* Read the [security concept](/docs/concepts/security/#how-citadel-determines-whether-to-create-service-account-secrets).
+* Read the [security concept](/docs/ops/configuration/mesh/secret-creation/).
 
 * Follow the [Istio installation guide](/docs/setup/install/istioctl/) to install Istio with mutual TLS enabled.
 

content/en/docs/tasks/traffic-management/egress/egress-gateway/index.md

@@ -61,7 +61,7 @@ controlled way.
 The following instructions create a destination rule for the egress gateway in the `default` namespace
 and assume that the client, `SOURCE_POD`, is also running in the `default` namespace.
 If not, the destination rule will not be found on the
-[destination rule lookup path](/docs/ops/traffic-management/deploy-guidelines/#cross-namespace-configuration-sharing)
+[destination rule lookup path](/docs/ops/best-practices/traffic-management/#cross-namespace-configuration)
 and the client requests will fail.
 
 {{< /warning >}}

content/en/docs/tasks/traffic-management/egress/egress_sni_monitoring_and_policies/index.md

@@ -92,7 +92,7 @@ $ kubectl delete -f @samples/sleep/policy/sni-wikipedia.yaml@
 
 ## Monitor the SNI and the source identity, and enforce access policies based on them
 
-Since you enabled mutual TLS between the sidecar proxies and the egress gateway, you can monitor the [service identity](/docs/ops/architecture/#citadel) of the applications that access external services, and enforce policies
+Since you enabled mutual TLS between the sidecar proxies and the egress gateway, you can monitor the [service identity](/docs/ops/deployment/architecture/#citadel) of the applications that access external services, and enforce policies
 based on the identities of the traffic source.
 In Istio on Kubernetes, the identities are based on
 [Service Accounts](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/). In this

content/en/docs/tasks/traffic-management/request-routing/index.md

@@ -206,7 +206,7 @@ to the request by the `productpage` service.
 
 Note that Kubernetes services, like the Bookinfo ones used in this task, must
 adhere to certain restrictions to take advantage of Istio's L7 routing features.
-Refer to the [Requirements for Pods and Services](/docs/ops/prep/requirements/) for details.
+Refer to the [Requirements for Pods and Services](/docs/ops/deployment/requirements/) for details.
 
 In the [traffic shifting](/docs/tasks/traffic-management/traffic-shifting) task, you
 will follow the same basic pattern you learned here to configure route rules to

content/en/faq/security/k8s-health-checks.md

@@ -8,10 +8,10 @@ If mutual TLS is enabled, HTTP and TCP health checks from the kubelet will not w
 As of Istio 1.1, we have several options to solve this issue.
 
 1.  Using probe rewrite to redirect liveness and readiness requests to the
-    workload directly. Please refer to [Probe Rewrite](/docs/ops/setup/app-health-check/#probe-rewrite)
+    workload directly. Please refer to [Probe Rewrite](/docs/ops/configuration/mesh/app-health-check/#probe-rewrite)
     for more information.
 
-1.  Using a separate port for health checks and enabling mutual TLS only on the regular service port. Please refer to [Health Checking of Istio Services](/docs/ops/setup/app-health-check/#separate-port) for more information.
+1.  Using a separate port for health checks and enabling mutual TLS only on the regular service port. Please refer to [Health Checking of Istio Services](/docs/ops/configuration/mesh/app-health-check/#separate-port) for more information.
 
 1.  Using the [`PERMISSIVE` mode](/docs/tasks/security/authentication/mtls-migration) for Istio services so they can accept both HTTP and mutual TLS traffic. Please keep in mind that mutual TLS is not enforced since others can communicate with the service with HTTP traffic.
 

content/en/faq/traffic-management/naming-port-convention.md

@@ -5,4 +5,4 @@ weight: 50
 
 Currently, Istio supports TCP based protocols. Additionally, Istio provides functionality such as routing and metrics for other protocols such as `http` and `mysql`.
 
-For a list of all protocols, and information on how to configure protocols, view the [Protocol Selection](/docs/ops/traffic-management/protocol-selection/) documentation.
+For a list of all protocols, and information on how to configure protocols, view the [Protocol Selection](/docs/ops/configuration/traffic-management/protocol-selection/) documentation.

content/en/news/releases/1.0.x/announcing-1.0.1/index.md

@@ -22,7 +22,7 @@ We're pleased to announce the availability of Istio 1.0.1. Please see below for
 
 - Fixed virtual service host mismatch issue when adding a port.
 
-- Added limited support for [merging multiple virtual service or destination rule definitions](/docs/ops/traffic-management/deploy-guidelines/#multiple-virtual-services-and-destination-rules-for-the-same-host) for the same host.
+- Added limited support for [merging multiple virtual service or destination rule definitions](/docs/ops/best-practices/traffic-management/#split-virtual-services) for the same host.
 
 - Allow [outlier](https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/cluster/outlier_detection.proto) consecutive gateway failures when using HTTP.
 

content/en/news/releases/1.1.x/announcing-1.1/_index.md

@@ -26,31 +26,31 @@ The theme for 1.1 is Enterprise Ready. We’ve been very pleased to see more and
 more companies using Istio in production, but as some larger companies tried to
 adopt Istio they hit some limits.
 
-One of our prime areas of focus has been [performance and scalability](/docs/ops/performance-and-scalability/).
+One of our prime areas of focus has been [performance and scalability](/docs/ops/deployment/performance-and-scalability/).
 As people moved into production with larger clusters running more services at
 higher volume, they hit some scaling and performance issues. The
 [sidecars](/docs/concepts/traffic-management/#sidecars) took too many resources
 and added too much latency. The control plane (especially
-[Pilot](/docs/ops/architecture/#pilot)) was overly
+[Pilot](/docs/ops/deployment/architecture/#pilot)) was overly
 resource hungry.
 
 We’ve done a lot of work to make both the data plane and the control plane more
 efficient. You can find the details of our 1.1 performance testing and the
-results in our updated [performance ans scalability concept](/docs/ops/performance-and-scalability/).
+results in our updated [performance ans scalability concept](/docs/ops/deployment/performance-and-scalability/).
 
 We’ve done work around namespace isolation as well. This lets you use
 Kubernetes namespaces to enforce boundaries of control, and ensures that your
 teams cannot interfere with each other.
 
-We have also improved the [multicluster capabilities and usability](/docs/ops/prep/deployment-models/).
+We have also improved the [multicluster capabilities and usability](/docs/ops/deployment/deployment-models/).
 We listened to the community and improved defaults for traffic control and
 policy. We introduced a new component called
-[Galley](/docs/ops/architecture/#galley). Galley validates that sweet,
+[Galley](/docs/ops/deployment/architecture/#galley). Galley validates that sweet,
 sweet YAML, reducing the chance of configuration errors. Galley will also be
 instrumental in [multicluster setups](/docs/setup/install/multicluster/),
 gathering service discovery information from each Kubernetes cluster. We are
 also supporting additional multicluster topologies including different
-[control plane models](/docs/ops/prep/deployment-models/#control-plane-models)
+[control plane models](/docs/ops/deployment/deployment-models/#control-plane-models)
 topologies without requiring a flat network.
 
 There is lots more -- see the [change notes](./change-notes) for complete

content/en/news/releases/1.1.x/announcing-1.1/change-notes/index.md

@@ -85,7 +85,7 @@ concise list of things you should know before upgrading your deployment to Istio
   [gateways](/docs/concepts/traffic-management/#gateways).
 
 - **Performance and Scalability Improvements**. Tuned the performance and
-  scalability of Istio and Envoy. Read more about [Performance and Scalability](/docs/ops/performance-and-scalability/)
+  scalability of Istio and Envoy. Read more about [Performance and Scalability](/docs/ops/deployment/performance-and-scalability/)
   enhancements.
 
 - **Access Logging Off by Default**. Disabled the access logs for all Envoy
@@ -183,7 +183,7 @@ concise list of things you should know before upgrading your deployment to Istio
 
 ### Configuration management
 
-- **Galley**. Added [Galley](/docs/ops/architecture/#galley) as the
+- **Galley**. Added [Galley](/docs/ops/deployment/architecture/#galley) as the
   primary configuration ingestion and distribution mechanism within Istio. It
   provides a robust model to validate, transform, and distribute configuration
   states to Istio components insulating the Istio components from Kubernetes

content/en/news/releases/1.2.x/announcing-1.2/change-notes/index.md

@@ -13,7 +13,7 @@ aliases:
 
 ## Traffic management
 
-- **Improved** [locality based routing](/docs/ops/traffic-management/locality-load-balancing/) in multicluster environments.
+- **Improved** [locality based routing](/docs/ops/configuration/traffic-management/locality-load-balancing/) in multicluster environments.
 - **Improved** outbound traffic policy in [`ALLOW_ANY` mode](/docs/reference/config/installation-options/#global-options). Traffic for unknown HTTP/HTTPS hosts on an existing port will be [forwarded as is](/docs/tasks/traffic-management/egress/egress-control/#envoy-passthrough-to-external-services). Unknown traffic will be logged in Envoy access logs.
 - **Added** support for setting HTTP idle timeouts to upstream services.
 - **Improved** Sidecar support for [NONE mode](/docs/reference/config/networking/sidecar/#CaptureMode) (without iptables) .
@@ -23,7 +23,7 @@ aliases:
 ## Security
 
 - **Improved** extend the default lifetime of self-signed Citadel root certificates to 10 years.
-- **Added** Kubernetes health check prober rewrite per deployment via `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in the `PodSpec` [annotation](/docs/ops/setup/app-health-check/#use-annotations-on-pod).
+- **Added** Kubernetes health check prober rewrite per deployment via `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in the `PodSpec` [annotation](/docs/ops/configuration/mesh/app-health-check/#use-annotations-on-pod).
 - **Added** support for configuring the secret paths for Istio mutual TLS certificates. Refer [here](https://github.com/istio/istio/issues/11984) for more details.
 - **Added** support for [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) private keys for workloads, enabled by the flag `pkcs8-keys` on Citadel.
 - **Improved** JWT public key fetching logic to be more resilient to network failure.

content/en/news/releases/1.3.x/announcing-1.3.1/index.md

@@ -31,5 +31,5 @@ This release includes bug fixes to improve robustness. This release note describ
 - **Added** annotations for Datadog tracing that controls extra features in sidecars.
 - **Added** the `pilot_xds_push_time` metric to report Pilot xDS push time.
 - **Added** `istioctl experimental analyze` to support multi-resource analysis and validation.
-- **Added** support for running metadata exchange and stats extensions in a WebAssembly sandbox. Follow [these](/docs/ops/telemetry/in-proxy-service-telemetry/) instructions to try it out.
+- **Added** support for running metadata exchange and stats extensions in a WebAssembly sandbox. Follow [these](/docs/ops/configuration/telemetry/in-proxy-service-telemetry/) instructions to try it out.
 - **Removed** time diff info in the proxy-status command.

content/en/news/releases/1.3.x/announcing-1.3/_index.md

@@ -64,7 +64,7 @@ Leverage Istio to integrate with Kubernetes and handle large fleets of Envoys in
     - Added a new Grafana dashboard for Citadel
     - Improved the Pilot dashboard to expose additional key metrics
 
-- Added the new [Istio Deployment Models concept](/docs/ops/prep/deployment-models/) to help you decide what deployment model suits your needs.
+- Added the new [Istio Deployment Models concept](/docs/ops/deployment/deployment-models/) to help you decide what deployment model suits your needs.
 
 - Organized the content in of our [Operations Guide](/docs/ops/) and created a [section with all troubleshooting tasks](/docs/ops/common-problems) to help you find the information you seek faster.
 

content/en/news/releases/1.3.x/announcing-1.3/change-notes/index.md

@@ -12,7 +12,7 @@ aliases:
 
 ## Traffic management
 
-- **Added** [automatic protocol determination](/docs/ops/traffic-management/protocol-selection/) of HTTP or TCP for outbound traffic when ports are not named according to Istio’s [conventions](/docs/ops/prep/requirements/).
+- **Added** [automatic protocol determination](/docs/ops/configuration/traffic-management/protocol-selection/) of HTTP or TCP for outbound traffic when ports are not named according to Istio’s [conventions](/docs/ops/deployment/requirements/).
 - **Added** a mode to the Gateway API for mutual TLS operation.
 - **Fixed** issues present when a service communicates over the network first in permissive mutual TLS mode for protocols like MySQL and MongoDB.
 - **Improved** Envoy proxy readiness checks. They now check Envoy's readiness status.
@@ -27,7 +27,7 @@ aliases:
 ## Security
 
 - **Added** trust domain validation for services using mutual TLS. By default, the server only authenticates the requests from the same trust domain.
-- **Added** [labels](/docs/concepts/security/#how-citadel-determines-whether-to-create-service-account-secrets) to control service account secret generation by namespace.
+- **Added** [labels]((/docs/ops/configuration/mesh/secret-creation/) to control service account secret generation by namespace.
 - **Added** SDS support to deliver the private key and certificates to each Istio control plane service.
 - **Added** support for [introspection](/docs/ops/diagnostic-tools/controlz/) to Citadel.
 - **Added** metrics to the `/metrics` endpoint of Citadel Agent on port 15014 to monitor the SDS service.
@@ -78,6 +78,6 @@ aliases:
 
 ## Miscellaneous
 
-- **Added** new images based on [distroless](/docs/ops/security/harden-docker-images/) base images.
+- **Added** new images based on [distroless](/docs/ops/configuration/security/harden-docker-images/) base images.
 - **Improved** the Istio CNI Helm chart to have consistent versions with Istio.
 - **Improved** Kubernetes Jobs behavior. Kubernetes Jobs now exit correctly when the job manually calls the `/quitquitquit` endpoint.

content/en/news/releases/1.3.x/announcing-1.3/upgrade-notes/index.md

@@ -31,7 +31,7 @@ to intentionally bypass Envoy, you must opt out of port capturing with the
 
 Protocol sniffing is now enabled by default. Disable protocol sniffing with the
 `--set pilot.enableProtocolSniffing=false` option when you upgrade to get the
-previous behavior. To learn more see our [protocol selection page](/docs/ops/traffic-management/protocol-selection/).
+previous behavior. To learn more see our [protocol selection page](/docs/ops/configuration/traffic-management/protocol-selection/).
 
 To specify a hostname in multiple namespaces, you must select a single host using
 a [`Sidecar` resource](/docs/reference/config/networking/sidecar/).

content/en/news/releases/1.4.x/announcing-1.4/change-notes/index.md

@@ -24,7 +24,7 @@ weight: 10
 ## Telemetry
 
 - **Added** experimental in-proxy telemetry reporting to [Stackdriver](https://github.com/istio/proxy/blob/{{< source_branch_name >}}/extensions/stackdriver/README.md).
-- **Improved** support for [in-proxy](/docs/ops/telemetry/in-proxy-service-telemetry/) Prometheus generation of HTTP service metrics (from experimental to alpha).
+- **Improved** support for [in-proxy](/docs/ops/configuration/telemetry/in-proxy-service-telemetry/) Prometheus generation of HTTP service metrics (from experimental to alpha).
 - **Improved** telemetry collection for [blocked and passthrough external service traffic](/blog/2019/monitoring-external-service-traffic/).
 - **Added** the option to configure [stat patterns](/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig) for Envoy stats.
 - **Added** the `inbound` and `outbound` prefixes to the Envoy HTTP stats to specify traffic direction.

content/en/news/releases/1.4.x/announcing-1.4/upgrade-notes/index.md

@@ -22,7 +22,7 @@ If you depend on this behavior, there are a few options:
 * Change the protocol from type `http` to type `tcp`
 * Specify the environment variable `PILOT_BLOCK_HTTP_ON_443=false` to the Pilot deployment. Note: this may be removed in future releases.
 
-See [Protocol Selection](/docs/ops/traffic-management/protocol-selection/) for more information about specifying the protocol of a port
+See [Protocol Selection](/docs/ops/configuration/traffic-management/protocol-selection/) for more information about specifying the protocol of a port
 
 ### Regex Engine Changes