public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-25 12:38:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adding first pass documentation

Browse Source
This commit is contained in:
Brenda Rearden
2020-09-30 16:16:27 -07:00
committed by Catherine Luse
parent ff976cc7f8
commit 80599a08b9
14 changed files with 1031 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/istio/_index.md
+72 -1
View File
@@ -1,4 +1,75 @@
---
title: Istio
weight: 15
---
---
_Available as of v2.5.0_
[Istio](https://istio.io/) is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.
As a network of microservices changes and grows, the interactions between them can become more difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly.
Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.
This service mesh provides features that include but are not limited to the following:
- Traffic management features
- Enhanced monitoring and tracing
- Service discovery and routing
- Secure connections and service-to-service authentication with mutual TLS
- Load balancing
- Automatic retries, backoff, and circuit breaking
After Istio is enabled in a cluster, you can leverage Istio's control plane functionality with `kubectl`.
Rancher's Istio integration comes with support for the following addon(s):
- **Get the full picture of your microservice architecture with Kiali.** [Kiali](https://www.kiali.io/) provides a diagram that shows the services within a service mesh and how they are connected, including the traffic rates and latencies between them. You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component.
# What's New
The overall architecture of Istio has been simplified. A single component, Istiod, has been created by combining Pilot, Citadel, Galley and the sidecar injector. Node Agent functionality has also been merged into istio-agent.
Addons that were previously installed by Istio (cert-manager, Grafana, Jaeger, Kiali, Prometheus, Zipkin ) will now need to be installed separately. Istio will support installation of integrations that are from the Istio Project and will maintain compatibility with those that are not.
A Prometheus integration will still be available through an installation of Rancher Monitoring (insert link here), or by installing your own prometheus operator. Rancher's Istio chart will also install kiali by default to ensure you can get a full picture of your microservice out of the box.
Istio has migrated away from Helm as a way to install Istio and now provides installation through the Istioctl binary or Istio Operator. To ensure the easiest interaction with Istio, Rancher's Istio will maintain a helm chart that utilizes the Istioctl binary to manage your Istio installation.
This helm chart will be available via the Apps and Marketplace in the UI. A user that has access to the Rancher Chart's catalog will need to set up Istio before it ca be used in the project.
# Prerequisites
Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough [CPU and memory](instert new url here) to run all of the components of Istio.
# Setup Guide
Refer to the [setup guide]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup) for instructions on how to set up Istio and use it in a project.
# Disabling Istio
To remove Istio components from a cluster, namespace, or workload, refer to the section on [disabling Istio.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/disabling-istio)
# Architecture
Istio installs a service mesh that uses [Envoy](https://www.envoyproxy.io/learn/service-mesh) sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster.
Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio.
Enabling Istio in Rancher enables monitoring in the cluster, and enables Istio in all new namespaces that are created in a cluster. You need to manually enable Istio in preexisting namespaces.
When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads.
For more information on the Istio sidecar, refer to the [Istio docs](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/).
### Multiple Ingresses
By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. To allow Istio to receive external traffic, you need to enable the Istio ingress gateway for the cluster. The result is that your cluster will have two ingresses.
![In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.]({{<baseurl>}}/img/rancher/istio-ingress.svg)
Additional Ingresses can be configured via the [overlay file] (overlay file link here)
### Egress Support
By default an Egress gateway is not installed, but can be configured via the [overlay file] (overlay file link here)
content/rancher/v2.x/en/istio/cluster-istio/_index.md
+85
View File
@@ -0,0 +1,85 @@
---
title: Istio
weight: 5
---
_Available as of v2.5.0_
> If you are usnig a rancher version less than v2.5.0, the older way of setting up Istio is documented in [this section]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/)
[Istio](https://istio.io/) is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.
As a network of microservices changes and grows, the interactions between them can become more difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly.
Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.
This service mesh provides features that include but are not limited to the following:
- Traffic management features
- Enhanced monitoring and tracing
- Service discovery and routing
- Secure connections and service-to-service authentication with mutual TLS
- Load balancing
- Automatic retries, backoff, and circuit breaking
After Istio is enabled in a cluster, you can leverage Istio's control plane functionality with `kubectl`.
Rancher's Istio integration comes with comprehensive visualization aids:
- **Get the full picture of your microservice architecture with Kiali.** [Kiali](https://www.kiali.io/) provides a diagram that shows the services within a service mesh and how they are connected, including the traffic rates and latencies between them. You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component.
Istio needs to be set up by a Rancher administrator or cluster administrator before it can be used in a project.
# Prerequisites
Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough [CPU and memory]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/resources) to run all of the components of Istio.
# Setup Guide
Refer to the [setup guide]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup) for instructions on how to set up Istio and use it in a project.
# Disabling Istio
To remove Istio components from a cluster, namespace, or workload, refer to the section on [disabling Istio.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/disabling-istio)
# Accessing Visualizations
> By default, only cluster owners have access to Jaeger and Kiali. For instructions on how to allow project members to access them, refer to [Access to Visualizations.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/rbac/#access-to-visualizations)
After Istio is set up in a cluster, Grafana, Prometheus, Jaeger, and Kiali are available in the Rancher UI.
Your access to the visualizations depend on your role. Grafana and Prometheus are only available for cluster owners. The Kiali and Jaeger UIs are available only to cluster owners by default, but cluster owners can allow project members to access them by editing the Istio settings. When you go to your project and click **Resources > Istio,** you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page.
To see the visualizations, go to the cluster where Istio is set up and click **Tools > Istio.** You should see links to each UI at the top of the page.
You can also get to the visualization tools from the project view.
# Viewing the Kiali Traffic Graph
1. From the project view in Rancher, click **Resources > Istio.**
1. If you are a cluster owner, you can go to the **Traffic Graph** tab. This tab has the Kiali network visualization integrated into the UI.
# Viewing Traffic Metrics
Istio’s monitoring features provide visibility into the performance of all your services.
1. From the project view in Rancher, click **Resources > Istio.**
1. Go to the **Traffic Metrics** tab. After traffic is generated in your cluster, you should be able to see metrics for **Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count** and **Request Duration.** Cluster owners can see all of the metrics, while project members can see a subset of the metrics.
# Architecture
Istio installs a service mesh that uses [Envoy](https://www.envoyproxy.io/learn/service-mesh) sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster.
Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio.
Enabling Istio in Rancher enables monitoring in the cluster, and enables Istio in all new namespaces that are created in a cluster. You need to manually enable Istio in preexisting namespaces.
When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads.
For more information on the Istio sidecar, refer to the [Istio docs](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/).
### Two Ingresses
By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. To allow Istio to receive external traffic, you need to enable the Istio ingress gateway for the cluster. The result is that your cluster will have two ingresses.
![In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.]({{<baseurl>}}/img/rancher/istio-ingress.svg)
content/rancher/v2.x/en/istio/disabling-istio/_index.md
+31
View File
@@ -0,0 +1,31 @@
---
title: Disabling Istio
weight: 4
---
This section describes how to uninstall Istio in a cluster or disable a namespace, or workload.
# Uninstall Istio in a Cluster
To Uninstall Istio,
1. From Dashboard UI, navigate to **Installed Apps** in **Apps & Marketplace** and locate the rancher-istio installation
1. Select all the apps in the `istio-system` namespace and click **Delete**.
**Result:** The `rancher-istio` app in the cluster gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster.
**Note:** You can no longer disable and reenable your Istio installation. If you would like to save your settings for a future install, view and save individual yamls to refer to.
# Disable Istio in a Namespace
1. From the **Cluster Explorer** view, use the side-nav to select **Namespaces** page
1. On the **Namespace** page, you will see a list of namespaces. Go to the namespace where you want to disable and click the select **Edit as Form** or **Edit as Yaml**
1. Remove the `istio-injection=enabled` label from the namespace
1. Click **Save**
**Result:** When workloads are deployed in this namespace, they will not have the Istio sidecar.
# Remove the Istio Sidecar from a Workload
Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar.
content/rancher/v2.x/en/istio/rbac/_index.md
+30
View File
@@ -0,0 +1,30 @@
---
title: Role-based Access Control
weight: 3
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/rbac
---
This section describes the permissions required to access Istio features.
## Admin and Edit access
By default, only Admin and Edit roles can:
- Install Istio for the cluster
- Configure resource allocations for Istio
- Enable and disable Istio sidecar auto-injection for namespaces
- Add the Istio sidecar to workloads
- View the traffic metrics and traffic graph for the cluster
- Configure Istio's resources (such as the gateway, destination rules, or virtual services)
# Summary of Default Permissions for Kubernetes Default roles
| Permission | Admin | Edit | View |
|------------------------------------------|----------------|----------------|-----------------|
| Enable and disable Istio for the cluster | ✓ | ✓ | |
| Configure Istio resource limits | ✓ | ✓ | |
| Enable and disable Istio for a namespace | ✓ | ✓ | |
| Enable and disable Istio on workloads | ✓ | ✓ | |
| Configure Istio with `kubectl` | ✓ | ✓ | |
| View Istio project dashboard, including traffic metrics* | ✓ | ✓ | ✓ |
content/rancher/v2.x/en/istio/release-notes/_index.md
+20
View File
@@ -0,0 +1,20 @@
---
title: Release Notes
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/release-notes
---
# Istio 1.5.8
### Important note on 1.5.x versions
When upgrading from any 1.4 version of Istio to any 1.5 version, the Rancher installer will delete several resources in order to complete the upgrade, at which point they will be immediately re-installed. This includes the `istio-reader-service-account`. If your Istio installation is using this service account be aware that any secrets tied to the service account will be deleted. Most notably this will **break specific [multi-cluster deployments](https://archive.istio.io/v1.4/docs/setup/install/multicluster/)**. Downgrades back to 1.4 are not possible.
See the official upgrade notes for additional information on the 1.5 release and upgrading from 1.4: https://istio.io/latest/news/releases/1.5.x/announcing-1.5/upgrade-notes/
> **Note:** Rancher continues to use the Helm installation method, which produces a different architecture from an istioctl installation.
### Known Issues
* The Kiali traffic graph is currently not working [#24924](https://github.com/istio/istio/issues/24924)
content/rancher/v2.x/en/istio/resources/_index.md
+92
View File
@@ -0,0 +1,92 @@
---
title: CPU and Memory Allocations
weight: 1
aliases:
- /rancher/v2.x/en/project-admin/istio/configuring-resource-allocations/
- /rancher/v2.x/en/project-admin/istio/config/
- /rancher/v2.x/en/cluster-admin/tools/istio/resources
---
_Available as of v2.5.0_
This section describes the minimum recommended computing resources for the Istio components in a cluster.
The CPU and memory allocations for each component are [configurable.](#configuring-resource-allocations)
Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.
> **Tip:** In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.
The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each central Istio component.
In Kubernetes, the resource request indicates that the workload will not deployed on a node unless the node has at least the specified amount of memory and CPU available. If the workload surpasses the limit for CPU or memory, it can be terminated or evicted from the node. For more information on managing resource limits for containers, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
Workload | CPU - Request | Mem - Request | CPU - Limit | Mem - Limit | Configurable
---------|---------------|---------------|-------------|-------------|-------------
istiod | 610m | 2186Mi | 4000m | 2048Mi | Y | Y
istio-telemetry | 1000m | 10214Mi | 4800m | 4096Mi | Y
istio-policy | 1000m | 1024Mi | 4800m | 4096Mi | Y
istio-ingressgateway | 2000m | 1024Mi | 10m | 40Mi | Y
Others | 500m | 500Mi | - | - | Y
**Total** | **4500m** | **5620Mi** | **>12300m** | **>14848Mi** | **-**
# Configuring Resource Allocations
You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component.
To make it easier to schedule the workloads to a node, a cluster administrator can reduce the CPU and memory resource requests for the component. However, the default CPU and memory allocations are the minimum that we recommend.
You can find more information about Istio configuration in the [official Istio documentation](https://istio.io/docs/concepts/what-is-istio).
To configure the resources allocated to an Istio component,
1. In Rancher Dashboard, navigate to your Istio installation in Apps & Marketplace
1. Click **Upgrade** to edit the base components via changes the values.yaml or add an [overlay file](link to overlayfile install instructions).
1. Change the CPU or memory allocations, the nodes where each component will be scheduled to, or the node tolerations.
1. Click **Upgrade.** to rollout changes
**Result:** The resource allocations for the Istio components are updated.
## Istiod
[Istiod](https://istio.io/latest/docs/ops/deployment/architecture/#istiod) provides the following:
- Authentication configuration
- Service discovery for the Envoy sidecars
- Traffic management capabilities for intelligent routing (A/B tests and canary rollouts)
- Configuration for resiliency (timeouts, retries, circuit breakers, etc)
For more information on Istiod, refer to the [documentation](https://istio.io/latest/docs/ops/deployment/architecture/#components).
## Tracing
[Distributed tracing](https://istio.io/latest/docs/tasks/observability/distributed-tracing/overview/) enables users to track a request through a service mesh. This makes it easier to troubleshoot problems with latency, parallelism and serialization.
Option | Description| Required | Default
-------|------------|-------|-------
Enable Tracing | Whether or not to deploy the istio-tracing. | Yes | True
Tracing CPU Limit | CPU resource limit for the istio-tracing pod. | Yes | 500
Tracing CPU Reservation | CPU reservation for the istio-tracing pod. | Yes | 100
Tracing Memory Limit | Memory resource limit for the istio-tracing pod. | Yes | 1024
Tracing Memory Reservation | Memory resource requests for the istio-tracing pod. | Yes | 100
Tracing Selector | Ability to select the nodes in which tracing pod is deployed to. To use this option, the nodes must have labels. | No | n/a
## Ingress Gateway
The Istio gateway allows Istio features such as monitoring and route rules to be applied to traffic entering the cluster. This gateway is a prerequisite for outside traffic to make requests to Istio.
For more information, refer to the [documentation](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/).
Option | Description| Required | Default
-------|------------|-------|-------
Enable Ingress Gateway | Whether or not to deploy the istio-ingressgateway. | Yes | False
Service Type of Istio Ingress Gateway | How to expose the gateway. You can choose NodePort or Loadbalancer | Yes | NodePort
Http2 Port | The NodePort for http2 requests | Yes | 31380
Https Port | The NodePort for https requests | Yes | 31390
Load Balancer IP | Ingress Gateway Load Balancer IP | No | n/a
Load Balancer Source Ranges | Ingress Gateway Load Balancer Source Ranges | No | n/a
Ingress Gateway CPU Limit | CPU resource limit for the istio-ingressgateway pod. | Yes | 2000
Ingress Gateway CPU Reservation | CPU reservation for the istio-ingressgateway pod. | Yes | 100
Ingress Gateway Memory Limit | Memory resource limit for the istio-ingressgateway pod. | Yes | 1024
Ingress Gateway Memory Reservation | Memory resource requests for the istio-ingressgateway pod. | Yes | 128
Ingress Gateway Selector | Ability to select the nodes in which istio-ingressgateway pod is deployed to. To use this option, the nodes must have labels. | No | n/a
content/rancher/v2.x/en/istio/setup/_index.md
+30
View File
@@ -0,0 +1,30 @@
---
title: Setup Guide
weight: 2
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup
---
This section describes how to enable Istio and start using it in your projects.
This section assumes that you have Rancher installed, and you have a Rancher-provisioned Kubernetes cluster where you would like to set up Istio.
If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below.
> **Quick Setup** If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for [setting up the Istio gateway]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway) and [setting up Istio's components for traffic management.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management)
1. [Enable Istio in the cluster.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster)
1. [Enable Istio in all the namespaces where you want to use it.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace)
1. [Select the nodes where the main Istio components will be deployed.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/node-selectors)
1. [Add deployments and services that have the Istio sidecar injected.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/deploy-workloads)
1. [Set up the Istio gateway. ]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway)
1. [Set up Istio's components for traffic management.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management)
1. [Generate traffic and see Istio in action.](#generate-traffic-and-see-istio-in-action)
# Prerequisites
This guide assumes you have already [installed Rancher,]({{<baseurl>}}/rancher/v2.x/en/installation) and you have already [provisioned a separate Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning) on which you will install Istio.
The nodes in your cluster must meet the [CPU and memory requirements.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/resources/)
The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/)
content/rancher/v2.x/en/istio/setup/deploy-workloads/_index.md
+324
View File
@@ -0,0 +1,324 @@
---
title: 4. Add Deployments and Services with the Istio Sidecar
weight: 4
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/deploy-workloads
---
> **Prerequisite:** To enable Istio for a workload, the cluster and namespace must have Istio enabled.
Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload.
To inject the Istio sidecar on an existing workload in the namespace, go to the workload, click the **&#8942;,** and click **Redeploy.** When the workload is redeployed, it will have the Envoy sidecar automatically injected.
Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see istio-init and istio-proxy alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml.
### 3. Add Deployments and Services
Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.
1. Go to the project inside the cluster you want to deploy the workload on.
1. In Workloads, click **Import YAML.**
1. Copy the below resources into the form.
1. Click **Import.**
This will set up the following sample resources from Istio's example BookInfo app:
Details service and deployment:
- A `details` Service
- A ServiceAccount for `bookinfo-details`
- A `details-v1` Deployment
Ratings service and deployment:
- A `ratings` Service
- A ServiceAccount for `bookinfo-ratings`
- A `ratings-v1` Deployment
Reviews service and deployments (three versions):
- A `reviews` Service
- A ServiceAccount for `bookinfo-reviews`
- A `reviews-v1` Deployment
- A `reviews-v2` Deployment
- A `reviews-v3` Deployment
Productpage service and deployment:
This is the main page of the app, which will be visible from a web browser. The other services will be called from this page.
- A `productpage` service
- A ServiceAccount for `bookinfo-productpage`
- A `productpage-v1` Deployment
### Resource YAML
```yaml
# Copyright 2017 Istio Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
##################################################################################################
# Details service
##################################################################################################
apiVersion: v1
kind: Service
metadata:
name: details
labels:
app: details
service: details
spec:
ports:
- port: 9080
name: http
selector:
app: details
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: bookinfo-details
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: details-v1
labels:
app: details
version: v1
spec:
replicas: 1
selector:
matchLabels:
app: details
version: v1
template:
metadata:
labels:
app: details
version: v1
spec:
serviceAccountName: bookinfo-details
containers:
- name: details
image: docker.io/istio/examples-bookinfo-details-v1:1.15.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9080
---
##################################################################################################
# Ratings service
##################################################################################################
apiVersion: v1
kind: Service
metadata:
name: ratings
labels:
app: ratings
service: ratings
spec:
ports:
- port: 9080
name: http
selector:
app: ratings
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: bookinfo-ratings
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: ratings-v1
labels:
app: ratings
version: v1
spec:
replicas: 1
selector:
matchLabels:
app: ratings
version: v1
template:
metadata:
labels:
app: ratings
version: v1
spec:
serviceAccountName: bookinfo-ratings
containers:
- name: ratings
image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9080
---
##################################################################################################
# Reviews service
##################################################################################################
apiVersion: v1
kind: Service
metadata:
name: reviews
labels:
app: reviews
service: reviews
spec:
ports:
- port: 9080
name: http
selector:
app: reviews
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: bookinfo-reviews
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: reviews-v1
labels:
app: reviews
version: v1
spec:
replicas: 1
selector:
matchLabels:
app: reviews
version: v1
template:
metadata:
labels:
app: reviews
version: v1
spec:
serviceAccountName: bookinfo-reviews
containers:
- name: reviews
image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9080
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: reviews-v2
labels:
app: reviews
version: v2
spec:
replicas: 1
selector:
matchLabels:
app: reviews
version: v2
template:
metadata:
labels:
app: reviews
version: v2
spec:
serviceAccountName: bookinfo-reviews
containers:
- name: reviews
image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9080
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: reviews-v3
labels:
app: reviews
version: v3
spec:
replicas: 1
selector:
matchLabels:
app: reviews
version: v3
template:
metadata:
labels:
app: reviews
version: v3
spec:
serviceAccountName: bookinfo-reviews
containers:
- name: reviews
image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9080
---
##################################################################################################
# Productpage services
##################################################################################################
apiVersion: v1
kind: Service
metadata:
name: productpage
labels:
app: productpage
service: productpage
spec:
ports:
- port: 9080
name: http
selector:
app: productpage
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: bookinfo-productpage
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: productpage-v1
labels:
app: productpage
version: v1
spec:
replicas: 1
selector:
matchLabels:
app: productpage
version: v1
template:
metadata:
labels:
app: productpage
version: v1
spec:
serviceAccountName: bookinfo-productpage
containers:
- name: productpage
image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9080
---
```
### [Next: Set up the Istio Gateway]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway)
content/rancher/v2.x/en/istio/setup/enable-istio-in-cluster/_index.md
+41
View File
@@ -0,0 +1,41 @@
---
title: 1. Enable Istio in the Cluster
weight: 1
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster
---
This cluster uses the default Nginx controller to allow traffic into the cluster.
Only a user with the following [Kubernetes default roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster.
- Admin
- Edit
> If the cluster has a Pod Security Policy enabled there are [prerequisites steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/enable-istio-with-psp/)
1. From the Rancher Dashboard's **Cluster Explorer** view, navigate to available Charts in **Apps & Marketplace**
1. Select the Istio chart from the rancher provided charts
1. Optional: Configure member access and [resource limits]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/resources/) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
1. Optional: Make additional configuration changes to values.yaml if needed
1. Optional: Add additioanl resources or configuartion via the [overlay file](link to overlay file)
1. Click **Install**.
**Result:** Istio is installed at the cluster level.
The Istio application, `rancher-istio`, is added as an application to the cluster's `system` project.
When Istio is installed in the cluster, the label for Istio sidecar auto injection,`istio-injection=enabled`, will be automatically added to each new namespace in this cluster. This automatically enables Istio sidecar injection in all new workloads that are deployed in those namespaces. You will need to manually enable Istio in preexisting namespaces and workloads.
### [Next: Enable Istio in a Namespace]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace)
### Advanced Config Options
## Overlay File
An Overlay File is designed to support extensive configation of your Istio installation. It allows you to make changes to any values available in the [IstioOperator API](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/). This will ensure you can customize the default installation to fit any scenario.
The Overlay File will add configuration ontop of the default installation that is provided from the Istio chart installation. This means you do not need to redefine the components that already defined for installation.
For more information on Overlay Files, refer to the (documentation)[https://istio.io/latest/docs/setup/install/istioctl/#configure-component-settings]
content/rancher/v2.x/en/istio/setup/enable-istio-in-namespace/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: 2. Enable Istio in a Namespace
weight: 2
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace
---
You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace.
This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection.
> **Prerequisite:** To enable Istio in a namespace, the cluster must have Istio installed.
1. In the Rancher Dashboard, open the kubectl shell
1. Then run `kubectl label namespace <namespace> istio-injection=enabled`
**Result:** The namespace now has the label `istio-injection=enabled`. All new workloads deployed in this namespace will have the Istio sidecar injected by default.
### Verifying that Automatic Istio Sidecar Injection is Enabled
To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the **Containers** section, you should see the `istio-proxy` container.
### Excluding Workloads from Being Injected with the Istio Sidecar
If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:
```
sidecar.istio.io/inject: “false”
```
To add the annotation to a workload,
1. From the **Cluster Explorer** view, use the side-nav to select the **Overview** page for workloads
1. Go to the workload that should not have the sidecar and edit as yaml
1. Add the following key, value `sidecar.istio.io/inject: false` as an annotation on the workload
1. Click **Save.**
**Result:** The Istio sidecar will not be injected into the workload.
> **NOTE:** If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed.
### [Next: Select the Nodes ]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/node-selectors)
content/rancher/v2.x/en/istio/setup/gateway/_index.md
+132
View File
@@ -0,0 +1,132 @@
---
title: 5. Set up the Istio Gateway
weight: 5
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway
---
The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster.
You can use the NGINX ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster.
To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two ingresses.
You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster.
You can route traffic into the service mesh with a load balancer or just Istio's NodePort gateway. This section describes how to set up the NodePort gateway.
For more information on the Istio gateway, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/gateway/)
![In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.]({{<baseurl>}}/img/rancher/istio-ingress.svg)
# Enable the Istio Gateway
The ingress gateway is a Kubernetes service that will be deployed in your cluster. There is only one Istio gateway per cluster.
1. Go to the cluster where you want to allow outside traffic into Istio.
1. Click **Tools > Istio.**
1. Expand the **Ingress Gateway** section.
1. Under **Enable Ingress Gateway,** click **True.** The default type of service for the Istio gateway is NodePort. You can also configure it as a [load balancer.]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers/)
1. Optionally, configure the ports, service types, node selectors and tolerations, and resource requests and limits for this service. The default resource requests for CPU and memory are the minimum recommended resources.
1. Click **Save.**
**Result:** The gateway is deployed, which allows Istio to receive traffic from outside the cluster.
# Add a Kubernetes Gateway that Points to the Istio Gateway
To allow traffic to reach Ingress, you will also need to provide a Kubernetes gateway resource in your YAML that points to Istio's implementation of the ingress gateway to the cluster.
1. Go to the namespace where you want to deploy the Kubernetes gateway and click **Import YAML.**
1. Upload the gateway YAML as a file or paste it into the form. An example gateway YAML is provided below.
1. Click **Import.**
```yaml
apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
name: bookinfo-gateway
spec:
selector:
istio: ingressgateway # use istio default controller
servers:
- port:
number: 80
name: http
protocol: HTTP
hosts:
- "*"
---
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: bookinfo
spec:
hosts:
- "*"
gateways:
- bookinfo-gateway
http:
- match:
- uri:
exact: /productpage
- uri:
prefix: /static
- uri:
exact: /login
- uri:
exact: /logout
- uri:
prefix: /api/v1/products
route:
- destination:
host: productpage
port:
number: 9080
```
**Result:** You have configured your gateway resource so that Istio can receive traffic from outside the cluster.
Confirm that the resource exists by running:
```
kubectl get gateway -A
```
The result should be something like this:
```
NAME AGE
bookinfo-gateway 64m
```
### Access the ProductPage Service from a Web Browser
To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource:
`http://<IP of Istio controller>:<Port of istio controller>/productpage`
To get the ingress gateway URL and port,
1. Go to the `System` project in your cluster.
1. Within the `System` project, go to `Resources` > `Workloads` then scroll down to the `istio-system` namespace.
1. Within `istio-system`, there is a workload named `istio-ingressgateway`. Under the name of this workload, you should see links, such as `80/tcp`.
1. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append `/productpage` to the URL.
**Result:** You should see the BookInfo app in the web browser.
For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)
# Troubleshooting
The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests.
### Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller
You can try the steps in this section to make sure the Kubernetes gateway is configured properly.
In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is `istio` and the value is `ingressgateway`. To make sure the label is appropriate for the gateway, do the following:
1. Go to the `System` project in your cluster.
1. Within the `System` project, go to the namespace `istio-system`.
1. Within `istio-system`, there is a workload named `istio-ingressgateway`.
1. Click the name of this workload and go to the **Labels and Annotations** section. You should see that it has the key `istio` and the value `ingressgateway`. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.
### [Next: Set up Istio's Components for Traffic Management]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management)
content/rancher/v2.x/en/istio/setup/node-selectors/_index.md
+40
View File
@@ -0,0 +1,40 @@
---
title: 3. Select the Nodes Where Istio Components Will be Deployed
weight: 3
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/node-selectors
---
> **Prerequisite:** Your cluster needs a worker node that can designated for Istio. The worker node should meet the [resource requirements.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/resources)
This section describes how use node selectors to configure Istio components to be deployed on a designated node.
In larger deployments, it is strongly advised that Istio's infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.
# Adding a Label to the Istio Node
First, add a label to the node where Istio components should be deployed. This label can have any key-value pair. For this example, we will use the key `istio` and the value `enabled`.
1. From the cluster view, go to the **Nodes** tab.
1. Go to a worker node that will host the Istio components and click **&#8942; > Edit.**
1. Expand the **Labels & Annotations** section.
1. Click **Add Label.**
1. In the fields that appear, enter `istio` for the key and `enabled` for the value.
1. Click **Save.**
**Result:** A worker node has the label that will allow you to designate it for Istio components.
# Configuring Istio Components to Use the Labeled Node
Configure each Istio component to be deployed to the node with the Istio label. Each Istio component can be configured individually, but in this tutorial, we will configure all of the components to be scheduled on the same node for the sake of simplicity.
For larger deployments, it is recommended to schedule each component of Istio onto separate nodes.
1. From the cluster view, click **Tools > Istio.**
1. Expand the **Pilot** section and click **Add Selector** in the form that appears. Enter the node selector label that you added to the Istio node. In our case, we are using the key `istio` and the value `enabled.`
1. Repeat the previous step for the **Mixer** and **Tracing** sections.
1. Click **Save.**
**Result:** The Istio components will be deployed on the Istio node.
### [Next: Add Deployments and Services]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/deploy-workloads)
content/rancher/v2.x/en/istio/setup/set-up-traffic-management/_index.md
+63
View File
@@ -0,0 +1,63 @@
---
title: 6. Set up Istio's Components for Traffic Management
weight: 6
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management
---
A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are *virtual services* and *destination rules*.
- [Virtual services](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/) intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed.
- [Destination rules](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule/) serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred.
This section describes how to add an example virtual service that corresponds to the `reviews` microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the `reviews` service.
In this example, we take the traffic to the `reviews` service and intercept it so that 50 percent of it goes to `v1` of the service and 50 percent goes to `v2`.
After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service.
To deploy the virtual service and destination rules for the `reviews` service,
1. Go to the project view and click **Import YAML.**
1. Copy resources below into the form.
1. Click **Import.**
```
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: reviews
spec:
hosts:
- reviews
http:
- route:
- destination:
host: reviews
subset: v1
weight: 50
- destination:
host: reviews
subset: v3
weight: 50
---
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: reviews
spec:
host: reviews
subsets:
- name: v1
labels:
version: v1
- name: v2
labels:
version: v2
- name: v3
labels:
version: v3
```
**Result:** When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the `reviews` service is divided evenly between `v1` and `v3`.
### [Next: Generate and View Traffic]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/view-traffic)
content/rancher/v2.x/en/istio/setup/view-traffic/_index.md
+28
View File
@@ -0,0 +1,28 @@
---
title: 7. Generate and View Traffic
weight: 7
aliases:
- /rancher/v2.x/en/cluster-admin/tools/istio/setup/view-traffic
---
This section describes how to view the traffic that is being managed by Istio.
# The Kiali Traffic Graph
Rancher integrates a Kiali graph into the Rancher UI. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other.
To see the traffic graph,
1. From the project view in Rancher, click **Resources > Istio.**
1. Go to the **Traffic Graph** tab. This tab has the Kiali network visualization integrated into the UI.
If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to `v1` and `v3` of the `reviews` service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph.
For additional tools and visualizations, you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page.
# Viewing Traffic Metrics
Istio’s monitoring features provide visibility into the performance of all your services.
1. From the project view in Rancher, click **Resources > Istio.**
1. Go to the **Traffic Metrics** tab. After traffic is generated in your cluster, you should be able to see metrics for **Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count** and **Request Duration.**