From 22d066be37a24961e346e86c3a42de9881c3948c Mon Sep 17 00:00:00 2001 From: Rigs Caballero Date: Thu, 14 Nov 2019 08:58:29 -0800 Subject: [PATCH] Added the Best Practices section with general principles. (#5137) * Added the Best Practices section with general principles. This is the beginning of the new Best Practices section. Our goal is to provide a section for all the best practices and recommendations for Istio deployments. The best practices are based on the identified and recommended deployment models. Signed-off-by: rcaballeromx * Change headings for clarity. Adds clarity to some passages based on feedback. Removes a list of recommendations that was causing some confusion. Adds a glossary entry for failure domains and how they relate to a platform's availability zones. Signed-off-by: rcaballeromx * Move Best Practices to Ops Guide Signed-off-by: rcaballeromx * Moved Deployment Best Practices to a new "Prepare Your Deployment" section. Moved all deployment preparation content into a new section under "Setup". For now the content includes the following sections: - Deployment models - Deployment best practices - Pod requirements Merged the two existing pages containing pod requirements into one single page. Signed-off-by: rcaballeromx * Replace example with better guidance around namespace tenancy. Signed-off-by: Rigs Caballero * Add links and language pointing to the Prepare section Signed-off-by: Rigs Caballero * Fix minor typos and broken links. Signed-off-by: Rigs Caballero * Move from Setup to Operations Signed-off-by: Rigs Caballero * Fix broken links Signed-off-by: Rigs Caballero * Fix rebasing issues. Signed-off-by: Rigs Caballero * Fix multicluster install link. Signed-off-by: Rigs Caballero --- .../multicluster-version-routing/index.md | 4 +- .../en/docs/examples/platform/gke/index.md | 2 +- .../en/docs/examples/platform/icp/index.md | 2 +- .../common-problems/network-issues/index.md | 2 +- .../observability-issues/index.md | 4 +- .../istioctl-describe/index.md | 2 +- content/en/docs/ops/prep/_index.md | 13 + .../prep}/deployment-models/cluster-iso.svg | 0 .../prep}/deployment-models/cluster-ns.svg | 0 .../prep}/deployment-models/exp-ns.svg | 0 .../prep}/deployment-models/failover.svg | 0 .../prep}/deployment-models/index.md | 2 +- .../prep}/deployment-models/iso-ns.svg | 0 .../prep}/deployment-models/multi-cluster.svg | 0 .../prep}/deployment-models/multi-control.svg | 0 .../prep}/deployment-models/multi-mesh.svg | 0 .../prep}/deployment-models/multi-net.svg | 0 .../prep}/deployment-models/multi-trust.svg | 0 .../deployment-models/shared-control.svg | 0 .../deployment-models/single-cluster.svg | 0 .../prep}/deployment-models/single-net.svg | 0 .../prep}/deployment-models/single-trust.svg | 0 content/en/docs/ops/prep/deployment/index.md | 32 ++ .../prep}/requirements/index.md | 68 ++- .../docs/reference/glossary/failure-domain.md | 10 + .../reference/glossary/mesh-federation.md | 2 +- .../docs/setup/additional-setup/cni/index.md | 2 +- .../additional-setup/config-profiles/index.md | 2 +- .../en/docs/setup/getting-started/index.md | 26 +- content/en/docs/setup/install/helm/index.md | 2 +- .../en/docs/setup/install/istioctl/index.md | 2 +- .../docs/setup/install/multicluster/_index.md | 2 +- .../install/multicluster/gateways/index.md | 4 +- .../multicluster/shared-gateways/index.md | 2 +- .../install/multicluster/shared-vpn/index.md | 4 +- .../install/multicluster/simplified/index.md | 2 +- .../install/standalone-operator/index.md | 2 +- .../request-routing/index.md | 2 +- content/en/news/2019/announcing-1.1/_index.md | 4 +- content/en/news/2019/announcing-1.3/_index.md | 2 +- .../2019/announcing-1.3/change-notes/index.md | 2 +- .../multicluster-version-routing/index.md | 4 +- .../docs/examples/multicluster/gke/index.md | 2 +- .../docs/examples/multicluster/icp/index.md | 2 +- .../common-problems/network-issues/index.md | 2 +- .../istioctl-describe/index.md | 2 +- .../ops/setup/standalone-operator/index.md | 2 +- content/zh/docs/setup/_index.md | 2 +- .../docs/setup/install/multicluster/_index.md | 2 +- .../multicluster/shared-gateways/index.md | 2 +- .../install/multicluster/shared-vpn/index.md | 4 +- .../zh/docs/setup/install/operator/index.md | 411 ++++++++++++++++++ content/zh/news/2019/announcing-1.1/_index.md | 4 +- content/zh/news/2019/announcing-1.3/_index.md | 2 +- .../2019/announcing-1.3/change-notes/index.md | 2 +- src/icons/best-practices.svg | 26 ++ 56 files changed, 608 insertions(+), 64 deletions(-) create mode 100644 content/en/docs/ops/prep/_index.md rename content/en/docs/{setup => ops/prep}/deployment-models/cluster-iso.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/cluster-ns.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/exp-ns.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/failover.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/index.md (99%) rename content/en/docs/{setup => ops/prep}/deployment-models/iso-ns.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/multi-cluster.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/multi-control.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/multi-mesh.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/multi-net.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/multi-trust.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/shared-control.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/single-cluster.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/single-net.svg (100%) rename content/en/docs/{setup => ops/prep}/deployment-models/single-trust.svg (100%) create mode 100644 content/en/docs/ops/prep/deployment/index.md rename content/en/docs/{setup/additional-setup => ops/prep}/requirements/index.md (50%) create mode 100644 content/en/docs/reference/glossary/failure-domain.md create mode 100644 content/zh/docs/setup/install/operator/index.md create mode 100644 src/icons/best-practices.svg diff --git a/content/en/blog/2019/multicluster-version-routing/index.md b/content/en/blog/2019/multicluster-version-routing/index.md index 141b82b8db..e83a176d5f 100644 --- a/content/en/blog/2019/multicluster-version-routing/index.md +++ b/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/setup/deployment-models/#multiple-clusters). +[multicluster deployment](/docs/ops/prep/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/setup/deployment-models/#control-plane-models). +[control plane model](/docs/ops/prep/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. diff --git a/content/en/docs/examples/platform/gke/index.md b/content/en/docs/examples/platform/gke/index.md index 43e3b92c7a..a618670ec8 100644 --- a/content/en/docs/examples/platform/gke/index.md +++ b/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/setup/deployment-models/#single-network) +[single-network deployment](/docs/ops/prep/deployment-models/#single-network) over 2 [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) clusters. ## Before you begin diff --git a/content/en/docs/examples/platform/icp/index.md b/content/en/docs/examples/platform/icp/index.md index 90b45142ef..7d1e8d3412 100644 --- a/content/en/docs/examples/platform/icp/index.md +++ b/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/setup/deployment-models/#single-network). +[single-network deployment](/docs/ops/prep/deployment-models/#single-network). ## Create the IBM Cloud Private clusters diff --git a/content/en/docs/ops/common-problems/network-issues/index.md b/content/en/docs/ops/common-problems/network-issues/index.md index c0ba997a49..24ab8388b9 100644 --- a/content/en/docs/ops/common-problems/network-issues/index.md +++ b/content/en/docs/ops/common-problems/network-issues/index.md @@ -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/setup/additional-setup/requirements/) +Refer to the [Requirements for Pods and Services](/docs/ops/prep/requirements/) for details. Another potential issue is that the route rules may simply be slow to take effect. diff --git a/content/en/docs/ops/common-problems/observability-issues/index.md b/content/en/docs/ops/common-problems/observability-issues/index.md index 3183c47b13..55ce98555b 100644 --- a/content/en/docs/ops/common-problems/observability-issues/index.md +++ b/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/setup/additional-setup/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/prep/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/setup/additional-setup/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/prep/requirements/) ### Verify Mixer is receiving report calls Mixer generates metrics to monitor its own behavior. The first step is to check these metrics: diff --git a/content/en/docs/ops/diagnostic-tools/istioctl-describe/index.md b/content/en/docs/ops/diagnostic-tools/istioctl-describe/index.md index 64f2e91426..5cd53e122e 100644 --- a/content/en/docs/ops/diagnostic-tools/istioctl-describe/index.md +++ b/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/setup/additional-setup/requirements/) +if some of the [Istio requirements for pods](/docs/ops/prep/requirements/) are not met. For example, the following command produces a warning indicating a `kubernetes-dashboard` diff --git a/content/en/docs/ops/prep/_index.md b/content/en/docs/ops/prep/_index.md new file mode 100644 index 0000000000..b28f7b29de --- /dev/null +++ b/content/en/docs/ops/prep/_index.md @@ -0,0 +1,13 @@ +--- +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 +--- \ No newline at end of file diff --git a/content/en/docs/setup/deployment-models/cluster-iso.svg b/content/en/docs/ops/prep/deployment-models/cluster-iso.svg similarity index 100% rename from content/en/docs/setup/deployment-models/cluster-iso.svg rename to content/en/docs/ops/prep/deployment-models/cluster-iso.svg diff --git a/content/en/docs/setup/deployment-models/cluster-ns.svg b/content/en/docs/ops/prep/deployment-models/cluster-ns.svg similarity index 100% rename from content/en/docs/setup/deployment-models/cluster-ns.svg rename to content/en/docs/ops/prep/deployment-models/cluster-ns.svg diff --git a/content/en/docs/setup/deployment-models/exp-ns.svg b/content/en/docs/ops/prep/deployment-models/exp-ns.svg similarity index 100% rename from content/en/docs/setup/deployment-models/exp-ns.svg rename to content/en/docs/ops/prep/deployment-models/exp-ns.svg diff --git a/content/en/docs/setup/deployment-models/failover.svg b/content/en/docs/ops/prep/deployment-models/failover.svg similarity index 100% rename from content/en/docs/setup/deployment-models/failover.svg rename to content/en/docs/ops/prep/deployment-models/failover.svg diff --git a/content/en/docs/setup/deployment-models/index.md b/content/en/docs/ops/prep/deployment-models/index.md similarity index 99% rename from content/en/docs/setup/deployment-models/index.md rename to content/en/docs/ops/prep/deployment-models/index.md index 7db96148cf..3120d02be1 100644 --- a/content/en/docs/setup/deployment-models/index.md +++ b/content/en/docs/ops/prep/deployment-models/index.md @@ -1,7 +1,7 @@ --- title: Deployment Models description: Describes the system models that impact your overall Istio depolyment. -weight: 6 +weight: 1 keywords: - single-cluster - multiple-clusters diff --git a/content/en/docs/setup/deployment-models/iso-ns.svg b/content/en/docs/ops/prep/deployment-models/iso-ns.svg similarity index 100% rename from content/en/docs/setup/deployment-models/iso-ns.svg rename to content/en/docs/ops/prep/deployment-models/iso-ns.svg diff --git a/content/en/docs/setup/deployment-models/multi-cluster.svg b/content/en/docs/ops/prep/deployment-models/multi-cluster.svg similarity index 100% rename from content/en/docs/setup/deployment-models/multi-cluster.svg rename to content/en/docs/ops/prep/deployment-models/multi-cluster.svg diff --git a/content/en/docs/setup/deployment-models/multi-control.svg b/content/en/docs/ops/prep/deployment-models/multi-control.svg similarity index 100% rename from content/en/docs/setup/deployment-models/multi-control.svg rename to content/en/docs/ops/prep/deployment-models/multi-control.svg diff --git a/content/en/docs/setup/deployment-models/multi-mesh.svg b/content/en/docs/ops/prep/deployment-models/multi-mesh.svg similarity index 100% rename from content/en/docs/setup/deployment-models/multi-mesh.svg rename to content/en/docs/ops/prep/deployment-models/multi-mesh.svg diff --git a/content/en/docs/setup/deployment-models/multi-net.svg b/content/en/docs/ops/prep/deployment-models/multi-net.svg similarity index 100% rename from content/en/docs/setup/deployment-models/multi-net.svg rename to content/en/docs/ops/prep/deployment-models/multi-net.svg diff --git a/content/en/docs/setup/deployment-models/multi-trust.svg b/content/en/docs/ops/prep/deployment-models/multi-trust.svg similarity index 100% rename from content/en/docs/setup/deployment-models/multi-trust.svg rename to content/en/docs/ops/prep/deployment-models/multi-trust.svg diff --git a/content/en/docs/setup/deployment-models/shared-control.svg b/content/en/docs/ops/prep/deployment-models/shared-control.svg similarity index 100% rename from content/en/docs/setup/deployment-models/shared-control.svg rename to content/en/docs/ops/prep/deployment-models/shared-control.svg diff --git a/content/en/docs/setup/deployment-models/single-cluster.svg b/content/en/docs/ops/prep/deployment-models/single-cluster.svg similarity index 100% rename from content/en/docs/setup/deployment-models/single-cluster.svg rename to content/en/docs/ops/prep/deployment-models/single-cluster.svg diff --git a/content/en/docs/setup/deployment-models/single-net.svg b/content/en/docs/ops/prep/deployment-models/single-net.svg similarity index 100% rename from content/en/docs/setup/deployment-models/single-net.svg rename to content/en/docs/ops/prep/deployment-models/single-net.svg diff --git a/content/en/docs/setup/deployment-models/single-trust.svg b/content/en/docs/ops/prep/deployment-models/single-trust.svg similarity index 100% rename from content/en/docs/setup/deployment-models/single-trust.svg rename to content/en/docs/ops/prep/deployment-models/single-trust.svg diff --git a/content/en/docs/ops/prep/deployment/index.md b/content/en/docs/ops/prep/deployment/index.md new file mode 100644 index 0000000000..d6b06bcc7b --- /dev/null +++ b/content/en/docs/ops/prep/deployment/index.md @@ -0,0 +1,32 @@ +--- +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] +--- + +We have identified the following general principles to help you get the most +out of your Istio deployments. These best practices aim to limit the impact of +bad configuration changes and make managing your deployments easier. + +## Deploy fewer clusters + +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) +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. + +## Deploy clusters near your users + +Include clusters in your deployment across the globe for **geographic +proximity to end-users**. Proximity helps your deployment have low latency. + +## Deploy across multiple availability zones + +Include clusters in your deployment **across multiple availability regions +and zones** within each geographic region. This approach limits the size of the +{{< gloss "failure domain" >}}failure domains{{< /gloss >}} of your deployment, +and helps you avoid global failures. diff --git a/content/en/docs/setup/additional-setup/requirements/index.md b/content/en/docs/ops/prep/requirements/index.md similarity index 50% rename from content/en/docs/setup/additional-setup/requirements/index.md rename to content/en/docs/ops/prep/requirements/index.md index e9281ca0a3..89174d0a11 100644 --- a/content/en/docs/setup/additional-setup/requirements/index.md +++ b/content/en/docs/ops/prep/requirements/index.md @@ -1,20 +1,31 @@ --- title: Pods and Services -description: Prepare your Kubernetes pods and services to run in an Istio-enabled cluster. -weight: 5 +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/ -keywords: [kubernetes,sidecar,sidecar-injection] +- /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 +- /help/ops/setup/required-pod-capabilities +keywords: +- kubernetes +- sidecar +- sidecar-injection +- deployment-models +- pods +- setup --- -To be a part of an Istio service mesh, pods and services in a Kubernetes -cluster must satisfy the following requirements: +To be part of a mesh, Kubernetes pods and services must satisfy the following +requirements: - **Named service ports**: Service ports must be named. The port name key/value - pairs must have the following syntax: `name: [-]`. See [Protocol Selection](/docs/ops/traffic-management/protocol-selection/) for more details. + pairs must have the following syntax: `name: [-]`. See + [Protocol Selection](/docs/ops/traffic-management/protocol-selection/) for + more details. - **Service association**: A pod must belong to at least one Kubernetes service even if the pod does NOT expose any port. @@ -45,7 +56,8 @@ cluster must satisfy the following requirements: ## Ports used by Istio -The following ports and protocols are used by Istio. Ensure that there are no TCP headless services using a TCP port used by one of Istio's services. +The following ports and protocols are used by Istio. Ensure that there are no +TCP headless services using a TCP port used by one of Istio's services. | Port | Protocol | Used by | Description | |----|----|----|----| @@ -70,3 +82,37 @@ The following ports and protocols are used by Istio. Ensure that there are no TC | 15443 | TLS | Ingress and Egress Gateways | SNI | | 15090 | HTTP | Mixer | Proxy | | 42422 | TCP | Mixer | Telemetry - Prometheus | + +## Required pod capabilities + +Follow these steps to verify which capabilities are allowed for your pods. + +If [pod security +policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) +are [enforced](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#enabling-pod-security-policies) +in your cluster and unless you use Istio CNI Plugin, your pods must have the +`NET_ADMIN` capability allowed. The initialization containers of the Envoy +proxies require this capability. To check which capabilities are allowed for +your pods, check if their [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) +can use a pod security policy that allows the `NET_ADMIN` capability. + +If you don't specify a service account in your pods' deployment, the pods run as +the `default` service account in their deployment's namespace. + +To check which capabilities are allowed for the service account of your pods, +run the following command: + +{{< text bash >}} +$ for psp in $(kubectl get psp -o jsonpath="{range .items[*]}{@.metadata.name}{'\n'}{end}"); do if [ $(kubectl auth can-i use psp/$psp --as=system:serviceaccount::) = yes ]; then kubectl get psp/$psp --no-headers -o=custom-columns=NAME:.metadata.name,CAPS:.spec.allowedCapabilities; fi; done +{{< /text >}} + +For example, to check which capabilities are allowed for the `default` service +account in the `default` namespace, run the following command: + +{{< text bash >}} +$ for psp in $(kubectl get psp -o jsonpath="{range .items[*]}{@.metadata.name}{'\n'}{end}"); do if [ $(kubectl auth can-i use psp/$psp --as=system:serviceaccount:default:default) = yes ]; then kubectl get psp/$psp --no-headers -o=custom-columns=NAME:.metadata.name,CAPS:.spec.allowedCapabilities; fi; done +{{< /text >}} + +If you see `NET_ADMIN` or `*` in the list of capabilities of one of the allowed +policies for your service account, your pods have permission to run the Istio +init containers. Otherwise, you must [provide such permission](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#authorizing-policies). diff --git a/content/en/docs/reference/glossary/failure-domain.md b/content/en/docs/reference/glossary/failure-domain.md new file mode 100644 index 0000000000..96326d3f54 --- /dev/null +++ b/content/en/docs/reference/glossary/failure-domain.md @@ -0,0 +1,10 @@ +--- +title: Failure Domain +--- + +A failure domain is a physical or logical section of the computing environment +that is negatively affected when a critical device or service experiences +problems. + +For an Istio deployment, failure domains could encompass multiple availability +zones of your platform. diff --git a/content/en/docs/reference/glossary/mesh-federation.md b/content/en/docs/reference/glossary/mesh-federation.md index 6459bd237b..f70e8a446e 100644 --- a/content/en/docs/reference/glossary/mesh-federation.md +++ b/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/setup/deployment-models/#multiple-meshes). +[multi-mesh deployment](/docs/ops/prep/deployment-models/#multiple-meshes). diff --git a/content/en/docs/setup/additional-setup/cni/index.md b/content/en/docs/setup/additional-setup/cni/index.md index 9a94d86ebd..239fc7e721 100644 --- a/content/en/docs/setup/additional-setup/cni/index.md +++ b/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/setup/additional-setup/requirements/) +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. diff --git a/content/en/docs/setup/additional-setup/config-profiles/index.md b/content/en/docs/setup/additional-setup/config-profiles/index.md index 7ddc91dc3f..9f98e49ac7 100644 --- a/content/en/docs/setup/additional-setup/config-profiles/index.md +++ b/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/setup/deployment-models/#multiple-clusters) with a + [multicluster mesh](/docs/ops/prep/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: diff --git a/content/en/docs/setup/getting-started/index.md b/content/en/docs/setup/getting-started/index.md index 6a4eff4c5f..50bad0a60a 100644 --- a/content/en/docs/setup/getting-started/index.md +++ b/content/en/docs/setup/getting-started/index.md @@ -8,11 +8,11 @@ aliases: keywords: [getting-started, install, bookinfo, quick-start, kubernetes] --- -To get started with Istio, just follow these three steps: +To get started with Istio, just follow these steps: -1. [Set up your platform](#platform) -1. [Download the release](#download) -1. [Install Istio](#install) +- [Set up your platform](#platform) +- [Download the Istio release](#download) +- [Install Istio](#install) ## Set up your platform {#platform} @@ -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/setup/deployment-models/), +or a more advanced [deployment model](/docs/ops/prep/deployment-models/), follow the [installing with {{< istioctl >}} instructions](/docs/setup/install/istioctl) instead. {{< warning >}} @@ -135,7 +135,7 @@ access logging. prometheus-67cdb66cbb-9w2hm 1/1 Running 0 1m {{< /text >}} -## What's next +## Next steps With Istio installed, you can now deploy your own application or one of the sample applications provided with the installation. @@ -182,10 +182,16 @@ The following tasks are a good place for beginners to start: - [Accessing external services](/docs/tasks/traffic-management/egress/egress-control/) - [Visualizing your mesh](/docs/tasks/observability/kiali/) -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 -our [deployment models](/docs/setup/deployment-models/) and [general installation](/docs/setup/) -documents. +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/) +- [General installation instructions](/docs/setup/) + +Once you have a deployment that suits your needs, the next step is to deploy +your own applications. As you continue to use Istio, we look forward to hearing from you and welcoming you to our [community](/about/community/join/). diff --git a/content/en/docs/setup/install/helm/index.md b/content/en/docs/setup/install/helm/index.md index 951b2d1947..2e4fbf95c9 100644 --- a/content/en/docs/setup/install/helm/index.md +++ b/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/setup/additional-setup/requirements/). +1. Check the [Requirements for Pods and Services](/docs/ops/prep/requirements/). 1. [Install a Helm client](https://github.com/helm/helm#install) with a version higher than 2.10. diff --git a/content/en/docs/setup/install/istioctl/index.md b/content/en/docs/setup/install/istioctl/index.md index 0786cb3208..0fc6d7711f 100644 --- a/content/en/docs/setup/install/istioctl/index.md +++ b/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/setup/additional-setup/requirements/). +1. Check the [Requirements for Pods and Services](/docs/ops/prep/requirements/). ## Install Istio using the default profile diff --git a/content/en/docs/setup/install/multicluster/_index.md b/content/en/docs/setup/install/multicluster/_index.md index c86a48a974..a4f7c14180 100644 --- a/content/en/docs/setup/install/multicluster/_index.md +++ b/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/setup/deployment-models/#multiple-clusters) +Refer to the [multicluster deployment model](/docs/ops/prep/deployment-models/#multiple-clusters) concept documentation for more information. diff --git a/content/en/docs/setup/install/multicluster/gateways/index.md b/content/en/docs/setup/install/multicluster/gateways/index.md index 519ea2ff31..0bfdc17bfa 100644 --- a/content/en/docs/setup/install/multicluster/gateways/index.md +++ b/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/setup/deployment-models/#multiple-clusters) -with replicated [control plane](/docs/setup/deployment-models/#control-plane-models) instances +[multicluster deployment](/docs/ops/prep/deployment-models/#multiple-clusters) +with replicated [control plane](/docs/ops/prep/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, diff --git a/content/en/docs/setup/install/multicluster/shared-gateways/index.md b/content/en/docs/setup/install/multicluster/shared-gateways/index.md index f657515ab4..2b6aa291eb 100644 --- a/content/en/docs/setup/install/multicluster/shared-gateways/index.md +++ b/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/setup/deployment-models/#control-plane-models) +[control plane](/docs/ops/prep/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. diff --git a/content/en/docs/setup/install/multicluster/shared-vpn/index.md b/content/en/docs/setup/install/multicluster/shared-vpn/index.md index a80ade1ff8..8a1d0c20ae 100644 --- a/content/en/docs/setup/install/multicluster/shared-vpn/index.md +++ b/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/setup/deployment-models/#multiple-clusters) +Follow this guide to install an Istio [multicluster service mesh](/docs/ops/prep/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/setup/deployment-models/#control-plane-models). +[control plane](/docs/ops/prep/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. diff --git a/content/en/docs/setup/install/multicluster/simplified/index.md b/content/en/docs/setup/install/multicluster/simplified/index.md index 55be8a0800..063a04cd9c 100644 --- a/content/en/docs/setup/install/multicluster/simplified/index.md +++ b/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/setup/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/prep/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. diff --git a/content/en/docs/setup/install/standalone-operator/index.md b/content/en/docs/setup/install/standalone-operator/index.md index d2312e4380..20790b1b64 100644 --- a/content/en/docs/setup/install/standalone-operator/index.md +++ b/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/setup/additional-setup/requirements/). +1. Check the [Requirements for Pods and Services](/docs/ops/prep/requirements/). 1. Deploy the Istio operator: diff --git a/content/en/docs/tasks/traffic-management/request-routing/index.md b/content/en/docs/tasks/traffic-management/request-routing/index.md index 73a4bda6b4..b11af16546 100644 --- a/content/en/docs/tasks/traffic-management/request-routing/index.md +++ b/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/setup/additional-setup/requirements/) for details. +Refer to the [Requirements for Pods and Services](/docs/ops/prep/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 diff --git a/content/en/news/2019/announcing-1.1/_index.md b/content/en/news/2019/announcing-1.1/_index.md index ec4ed702dc..c2f3c4020c 100644 --- a/content/en/news/2019/announcing-1.1/_index.md +++ b/content/en/news/2019/announcing-1.1/_index.md @@ -39,7 +39,7 @@ 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/setup/deployment-models/). +We have also improved the [multicluster capabilities and usability](/docs/ops/prep/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, @@ -47,7 +47,7 @@ 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/setup/deployment-models/#control-plane-models) +[control plane models](/docs/ops/prep/deployment-models/#control-plane-models) topologies without requiring a flat network. There is lots more -- see the [change notes](./change-notes) for complete diff --git a/content/en/news/2019/announcing-1.3/_index.md b/content/en/news/2019/announcing-1.3/_index.md index 195e66cf66..ac5285466c 100644 --- a/content/en/news/2019/announcing-1.3/_index.md +++ b/content/en/news/2019/announcing-1.3/_index.md @@ -61,7 +61,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/setup/deployment-models/) to help you decide what deployment model suits your needs. +- Added the new [Istio Deployment Models concept](/docs/ops/prep/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. diff --git a/content/en/news/2019/announcing-1.3/change-notes/index.md b/content/en/news/2019/announcing-1.3/change-notes/index.md index 18f8a0919d..40376a3f3b 100644 --- a/content/en/news/2019/announcing-1.3/change-notes/index.md +++ b/content/en/news/2019/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/setup/additional-setup/requirements/). +- **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** 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. diff --git a/content/zh/blog/2019/multicluster-version-routing/index.md b/content/zh/blog/2019/multicluster-version-routing/index.md index 349a85c712..57397c5f26 100644 --- a/content/zh/blog/2019/multicluster-version-routing/index.md +++ b/content/zh/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/setup/deployment-models/#multiple-clusters). +[multicluster deployment](/docs/ops/prep/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/setup/deployment-models/#control-plane-models). +[control plane model](/docs/ops/prep/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. diff --git a/content/zh/docs/examples/multicluster/gke/index.md b/content/zh/docs/examples/multicluster/gke/index.md index b26251f029..7e975b6dd6 100644 --- a/content/zh/docs/examples/multicluster/gke/index.md +++ b/content/zh/docs/examples/multicluster/gke/index.md @@ -8,7 +8,7 @@ aliases: --- This example shows how to configure a multicluster mesh with a -[single-network deployment](/docs/setup/deployment-models/#single-network) +[single-network deployment](/docs/ops/prep/deployment-models/#single-network) over 2 [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) clusters. ## Before you begin diff --git a/content/zh/docs/examples/multicluster/icp/index.md b/content/zh/docs/examples/multicluster/icp/index.md index 18a335129a..cf229eed56 100644 --- a/content/zh/docs/examples/multicluster/icp/index.md +++ b/content/zh/docs/examples/multicluster/icp/index.md @@ -10,7 +10,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/setup/deployment-models/#single-network). +[single-network deployment](/docs/ops/prep/deployment-models/#single-network). ## Create the IBM Cloud Private Clusters diff --git a/content/zh/docs/ops/common-problems/network-issues/index.md b/content/zh/docs/ops/common-problems/network-issues/index.md index c0ba997a49..b290e2ff38 100644 --- a/content/zh/docs/ops/common-problems/network-issues/index.md +++ b/content/zh/docs/ops/common-problems/network-issues/index.md @@ -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/setup/additional-setup/requirements/) +Refer to the [Requirements for Pods and Services]/docs/ops/prep/requirements/) for details. Another potential issue is that the route rules may simply be slow to take effect. diff --git a/content/zh/docs/ops/diagnostic-tools/istioctl-describe/index.md b/content/zh/docs/ops/diagnostic-tools/istioctl-describe/index.md index 64f2e91426..8b7b181824 100644 --- a/content/zh/docs/ops/diagnostic-tools/istioctl-describe/index.md +++ b/content/zh/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/setup/additional-setup/requirements/) +if some of the [Istio requirements for pods]/docs/ops/prep/requirements/) are not met. For example, the following command produces a warning indicating a `kubernetes-dashboard` diff --git a/content/zh/docs/ops/setup/standalone-operator/index.md b/content/zh/docs/ops/setup/standalone-operator/index.md index 4d7660c299..497897c15e 100644 --- a/content/zh/docs/ops/setup/standalone-operator/index.md +++ b/content/zh/docs/ops/setup/standalone-operator/index.md @@ -18,7 +18,7 @@ instead, which is a stable feature. 1. Perform any necessary [platform-specific setup](/docs/setup/platform-setup/). -1. Check the [Requirements for Pods and Services](/docs/setup/additional-setup/requirements/). +1. Check the [Requirements for Pods and Services]/docs/ops/prep/requirements/). ## Installation steps diff --git a/content/zh/docs/setup/_index.md b/content/zh/docs/setup/_index.md index aac8e30a93..3f496c0ea6 100644 --- a/content/zh/docs/setup/_index.md +++ b/content/zh/docs/setup/_index.md @@ -25,7 +25,7 @@ Istio offers multiple installation flows 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/additional-setup/requirements/) +1. [Review the pod requirements]/docs/ops/prep/requirements/) 1. [Prepare your platform for Istio](/docs/setup/platform-setup/) 1. [Download the Istio release](#downloading-the-release) 1. [Install Istio on your platform](#installing-istio) diff --git a/content/zh/docs/setup/install/multicluster/_index.md b/content/zh/docs/setup/install/multicluster/_index.md index ac2d079304..c30165f3c9 100644 --- a/content/zh/docs/setup/install/multicluster/_index.md +++ b/content/zh/docs/setup/install/multicluster/_index.md @@ -13,4 +13,4 @@ aliases: 请注意，这些说明不是互斥的。 在由两个以上集群组成的大型多集群部署中，可以使用这些方法的组合。 例如，两个集群可能共享一个控制平面，而第三个集群拥有自己的控制平面。 {{< /tip >}} -欲获取更需信息请参考[多集群部署模型](/docs/setup/deployment-models/#multiple-clusters)。 +欲获取更需信息请参考[多集群部署模型](/docs/ops/prep/deployment-models/#multiple-clusters)。 diff --git a/content/zh/docs/setup/install/multicluster/shared-gateways/index.md b/content/zh/docs/setup/install/multicluster/shared-gateways/index.md index 91444f8809..37514415c9 100644 --- a/content/zh/docs/setup/install/multicluster/shared-gateways/index.md +++ b/content/zh/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/setup/deployment-models/#control-plane-models) +[control plane](/docs/ops/prep/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. diff --git a/content/zh/docs/setup/install/multicluster/shared-vpn/index.md b/content/zh/docs/setup/install/multicluster/shared-vpn/index.md index 1431166079..a8c345e344 100644 --- a/content/zh/docs/setup/install/multicluster/shared-vpn/index.md +++ b/content/zh/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/setup/deployment-models/#multiple-clusters) +Follow this guide to install an Istio [multicluster service mesh](/docs/ops/prep/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/setup/deployment-models/#control-plane-models). +[control plane](/docs/ops/prep/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. diff --git a/content/zh/docs/setup/install/operator/index.md b/content/zh/docs/setup/install/operator/index.md new file mode 100644 index 0000000000..826fcaa3b4 --- /dev/null +++ b/content/zh/docs/setup/install/operator/index.md @@ -0,0 +1,411 @@ +--- +title: Installing with Istioctl +description: Install and customize any Istio configuration profile for in-depth evaluation or production use. +weight: 10 +keywords: [operator,kubernetes,helm] +--- + +Follow this guide to install and configure an Istio mesh for in-depth evaluation or production use. + +This installation guide uses the [`istioctl`](/docs/reference/commands/istioctl/) command line +tool to provide rich customization of the Istio control plane and of the sidecars for the Istio data plane. +It has user input validation to help prevent installation errors and customization options to +override any aspect of the configuration. + +Using these instructions, you can select any one of Istio's built-in +[configuration profiles](/docs/setup/additional-setup/config-profiles/) +and then further customize the configuration for your specific needs. + +## Prerequisites + +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/). + +## Install Istio using the default profile + +The simplest option is to install the `default` Istio +[configuration profile](/docs/setup/additional-setup/config-profiles/) +using the following command: + +{{< text bash >}} +$ istioctl manifest apply +{{< /text >}} + +This command installs the `default` profile on the cluster defined by your +Kubernetes configuration. The `default` profile is a good starting point +for establishing a production environment, unlike the larger `demo` profile that +is intended for evaluating a broad set of Istio features. + +## Install a different profile + +Other Istio configuration profiles can be installed in a cluster by passing the +profile name on the command line. For example, the following command can be used +to install the `demo` profile: + +{{< text bash >}} +$ istioctl manifest apply --set profile=demo +{{< /text >}} + +## Display the list of available profiles + +You can display the names of Istio configuration profiles that are +accessible to `istioctl` by using this command: + +{{< text bash >}} +$ istioctl profile list + minimal + demo + sds + default +{{< /text >}} + +## Display the configuration of a profile + +You can view the configuration settings of a profile. For example, to view the setting for the `default` profile +run the following command: + +{{< text bash >}} +$ istioctl profile dump +autoInjection: + components: + injector: + enabled: true + k8s: + replicaCount: 1 + enabled: true +configManagement: + components: + galley: + enabled: true + k8s: + replicaCount: 1 + resources: + requests: + cpu: 100m + enabled: true +defaultNamespace: istio-system +gateways: + components: + egressGateway: + enabled: false + k8s: + hpaSpec: + maxReplicas: 5 + metrics: + - resource: + name: cpu + targetAverageUtilization: 80 + type: Resource + minReplicas: 1 +... +{{< /text >}} + +To view a subset of the entire configuration, you can use the `--config-path` flag, which selects only the portion +of the configuration under the given path: + +{{< text bash >}} +$ istioctl profile dump --config-path trafficManagement.components.pilot +enabled: true +k8s: + env: + - name: POD_NAME + valueFrom: + fieldRef: + apiVersion: v1 + fieldPath: metadata.name + - name: POD_NAMESPACE + valueFrom: + fieldRef: + apiVersion: v1 + fieldPath: metadata.namespace + - name: GODEBUG + value: gctrace=1 + - name: PILOT_TRACE_SAMPLING + value: "1" + - name: CONFIG_NAMESPACE + value: istio-config + hpaSpec: + maxReplicas: 5 + metrics: + - resource: + name: cpu + targetAverageUtilization: 80 + type: Resource + minReplicas: 1 + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: istio-pilot + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 30 + timeoutSeconds: 5 + resources: + requests: + cpu: 500m + memory: 2048Mi +{{< /text >}} + +## Show differences in profiles + +The `profile diff` sub-command can be used to show the differences between profiles, +which is useful for checking the effects of customizations before applying changes to a cluster. + +You can show differences between the default and demo profiles using these commands: + +{{< text bash >}} +$ istioctl profile dump default > 1.yaml +$ istioctl profile dump demo > 2.yaml +$ istioctl profile diff 1.yaml 2.yaml +{{< /text >}} + +## Generate a manifest before installation + +You can generate the manifest before installing Istio using the `manifest generate` +sub-command, instead of `manifest apply`. +For example, use the following command to generate a manifest for the `default` profile: + +{{< text bash >}} +$ istioctl manifest generate > $HOME/generated-manifest.yaml +{{< /text >}} + +Inspect the manifest as needed, then apply the manifest using this command: + +{{< text bash >}} +$ kubectl apply -f $HOME/generated-manifest.yaml +{{< /text >}} + +{{< tip >}} +This command might show transient errors due to resources not being available in +the cluster in the correct order. +{{< /tip >}} + +## Show differences in manifests + +You can show the differences in the generated manifests between the default profile and a customized install using these commands: + +{{< text bash >}} +$ istioctl manifest generate > 1.yaml +$ istioctl manifest generate -f samples/pilot-k8s.yaml > 2.yaml +$ istioctl manifest diff 1.yam1 2.yaml +{{< /text >}} + +## Verify a successful installation + +You can check if the Istio installation succeeded using the `verify-install` command +which compares the installation on your cluster to a manifest you specify. + +If you didn't generate your manifest prior to deployment, run the following command to +generate it now: + +{{< text bash >}} +$ istioctl manifest generate > $HOME/generated-manifest.yaml +{{< /text >}} + +Then run the following `verify-install` command to see if the installation was successful: + +{{< text bash >}} +$ istioctl verify-install -f $HOME/generated-manifest.yaml +{{< /text >}} + +## Customizing the configuration + +In addition to installing any of Istio's built-in +[configuration profiles](/docs/setup/additional-setup/config-profiles/), +`istioctl manifest` provides a complete API for customizing the configuration. + +- [The `IstioControlPlane` API](/docs/reference/config/istio.operator.v1alpha12.pb/) + +The configuration parameters in this API can be set individually using `--set` options on the command +line. For example, to disable the telemetry feature in a default configuration profile, use this command: + +{{< text bash >}} +$ istioctl manifest apply --set telemetry.enabled=false +{{< /text >}} + +Alternatively, a complete configuration can be specified in a YAML file and passed to +`istioctl` using the `-f` option: + +{{< text bash >}} +$ istioctl manifest apply -f samples/pilot-k8s.yaml +{{< /text >}} + +### Identify an Istio feature or component + +The `IstioControlPlane` API groups control plane components by feature, as shown in the table below: + +| Feature | Components | +|---------|------------| +`Base` | CRDs +`Traffic Management` | Pilot +`Policy` | Policy +`Telemetry` | Telemetry +`Security` | Citadel +`Security` | Node agent +`Security` | Cert manager +`Configuration management` | Galley +`Gateways` | Ingress gateway +`Gateways` | Egress gateway +`AutoInjection` | Sidecar injector + +In addition to the core Istio components, third-party addon features and components are also available: + +| Feature | Components | +|---------|------------| +`Telemetry` | Prometheus +`Telemetry` | Prometheus Operator +`Telemetry` | Grafana +`Telemetry` | Kiali +`Telemetry` | Tracing +`ThirdParty` | CNI + +Features can be enabled or disabled, which enables or disables all of the components that are a part of the feature. +Namespaces that components are installed into can be set by component, feature, or globally. + +### Configure the feature or component settings + +After you identify the name of the feature or component from the previous table, you can use the API to set the values +using the `--set` flag, or create an overlay file and use the `--filename` flag. The `--set` flag +works well for customizing a few parameters. Overlay files are designed for more extensive customization, or +tracking configuration changes. + +The simplest customization is to turn a feature or component on or off from the configuration profile default. + +To disable the telemetry feature in a default configuration profile, use this command: + +{{< text bash >}} +$ istioctl manifest apply --set telemetry.enabled=false +{{< /text >}} + +Alternatively, you can disable the telemetry feature using a configuration overlay file: + +1. Create this file with the name `telemetry_off.yaml` and these contents: + +{{< text yaml >}} +apiVersion: install.istio.io/v1alpha2 +kind: IstioControlPlane +spec: + telemetry: + enabled: false +{{< /text >}} + +1. Use the `telemetry_off.yaml` overlay file with the `manifest apply` command: + +{{< text bash >}} +$ istioctl manifest apply -f telemetry_off.yaml +{{< /text >}} + +You can also use this approach to set the component-level configuration, such as enabling the node agent: + +{{< text bash >}} +$ istioctl manifest apply --set security.components.nodeAgent.enabled=true +{{< /text >}} + +Another customization is to select different namespaces for features and components. The following is an example +of installation namespace customization: + +{{< text yaml >}} +apiVersion: install.istio.io/v1alpha2 +kind: IstioControlPlane +spec: + defaultNamespace: istio-system + security: + namespace: istio-security + components: + citadel: + namespace: istio-citadel +{{< /text >}} + +Applying this file will cause the default profile to be applied, with components being installed into the following +namespaces: + +- The Citadel component is installed into `istio-citadel` namespace +- All other components in the security feature installed into `istio-security` namespace +- Remaining Istio components installed into istio-system namespace + +### Customize Kubernetes settings + +The `IstioControlPlane` API allows each component's Kubernetes settings to be customized in a consistent way. + +Each component has a [`KubernetesResourceSpec`](/docs/reference/config/istio.operator.v1alpha12.pb/#KubernetesResourcesSpec), +which allows the following settings to be changed. Use this list to identify the setting to customize: + +1. [Resources](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) +1. [Readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/) +1. [Replica count](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) +1. [`HorizontalPodAutoscaler`](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) +1. [`PodDisruptionBudget`](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#how-disruption-budgets-work) +1. [Pod annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) +1. [Service annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) +1. [`ImagePullPolicy`](https://kubernetes.io/docs/concepts/containers/images/) +1. [Priority class name](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass) +1. [Node selector](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) +1. [Affinity and anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) + +All of these Kubernetes settings use the Kubernetes API definitions, so [Kubernetes documentation](https://kubernetes.io/docs/concepts/) can be used for reference. + +The following example overlay file adjusts the `TrafficManagement` feature's resources and horizontal pod autoscaling +settings for Pilot: + +{{< text yaml >}} +apiVersion: install.istio.io/v1alpha2 +kind: IstioControlPlane +spec: + trafficManagement: + components: + pilot: + k8s: + resources: + requests: + cpu: 1000m # override from default 500m + memory: 4096Mi # ... default 2048Mi + hpaSpec: + maxReplicas: 10 # ... default 5 + minReplicas: 2 # ... default 1 +{{< /text >}} + +Use `manifest apply` to apply the modified settings to the cluster: + +{{< text syntax="bash" repo="operator" >}} +$ istioctl manifest apply -f @samples/pilot-k8s.yaml@ +{{< /text >}} + +### Customize Istio settings using the Helm API + +The `IstioControlPlane` API includes a pass-through interface to the [Helm API](/docs/reference/config/installation-options/) +using the `values` field. + +The following YAML file configures global and Pilot settings through the Helm API: + +{{< text yaml >}} +apiVersion: install.istio.io/v1alpha2 +kind: IstioControlPlane +spec: + trafficManagement: + components: + pilot: + values: + traceSampling: 0.1 # override from 1.0 + + # global Helm settings + values: + monitoringPort: 15050 +{{< /text >}} + +Some parameters will temporarily exist in both the Helm and `IstioControlPlane` APIs, including Kubernetes resources, +namespaces and enablement settings. The Istio community recommends using the `IstioControlPlane` API as it is more +consistent, is validated, and follows the [community graduation process](https://github.com/istio/community/blob/master/FEATURE-LIFECYCLE-CHECKLIST.md#feature-lifecycle-checklist). + +## Uninstall Istio + +To uninstall Istio, run the following command: + +{{< text bash >}} +$ istioctl manifest generate | kubectl delete -f - +{{< /text >}} diff --git a/content/zh/news/2019/announcing-1.1/_index.md b/content/zh/news/2019/announcing-1.1/_index.md index de33390e9a..3db54d0a0e 100644 --- a/content/zh/news/2019/announcing-1.1/_index.md +++ b/content/zh/news/2019/announcing-1.1/_index.md @@ -40,7 +40,7 @@ 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/setup/deployment-models/). +We have also improved the [multicluster capabilities and usability](/docs/ops/prep/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, @@ -48,7 +48,7 @@ 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/setup/deployment-models/#control-plane-models) +[control plane models](/docs/ops/prep/deployment-models/#control-plane-models) topologies without requiring a flat network. There is lots more -- see the [change notes](./change-notes) for complete diff --git a/content/zh/news/2019/announcing-1.3/_index.md b/content/zh/news/2019/announcing-1.3/_index.md index 8e64da078f..922f4861ba 100644 --- a/content/zh/news/2019/announcing-1.3/_index.md +++ b/content/zh/news/2019/announcing-1.3/_index.md @@ -62,7 +62,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/setup/deployment-models/) to help you decide what deployment model suits your needs. +- Added the new [Istio Deployment Models concept](/docs/ops/prep/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. diff --git a/content/zh/news/2019/announcing-1.3/change-notes/index.md b/content/zh/news/2019/announcing-1.3/change-notes/index.md index 18f8a0919d..c5c9655ad1 100644 --- a/content/zh/news/2019/announcing-1.3/change-notes/index.md +++ b/content/zh/news/2019/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/setup/additional-setup/requirements/). +- **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** 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. diff --git a/src/icons/best-practices.svg b/src/icons/best-practices.svg new file mode 100644 index 0000000000..aeb03b3035 --- /dev/null +++ b/src/icons/best-practices.svg @@ -0,0 +1,26 @@ + + + + + + +