New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Ambient install user sub-guides #13920
Conversation
Hi @srampal. Thanks for your PR. I'm waiting for a istio member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
ztunnel sub-guide to be part of a separate PR
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/ok-to-test
@srampal: The following test failed, say
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
|
||
## Installation | ||
|
||
### Pre-requisites & Supported Topologies |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
https://istio.io/latest/docs/releases/contribute/style-guide/#use-sentence-case-for-headings
### Pre-requisites & Supported Topologies | |
### Pre-requisites & supported topologies |
A single Istio mesh can include pods and endpoints some of which operate using the sidecar proxy mode while others use the node level proxy of the Ambient architecture. | ||
{{< /tip >}} | ||
|
||
### Understanding the Ztunnel Default Configuration |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### Understanding the Ztunnel Default Configuration | |
### Understanding the Ztunnel default configuration |
|
||
An alternative to using istioctl is to use Helm based install of Istio Ambient. | ||
|
||
## Setup Repo Info |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## Setup Repo Info | |
## Setup repo info |
|
||
*See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation.* | ||
|
||
## Installing the Components |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## Installing the Components | |
## Installing the components |
|
||
## Installing the Components | ||
|
||
### Installing Base Component |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### Installing Base Component | |
### Installing Base component |
|
||
## Introduction | ||
|
||
This guide describe installation options and procedures for Istio Ambient mesh. The two primary installation methods supported are (1) Installation via the `istioctl` cli (2) Installation via `helm`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems we had standardized earlier on ambient mesh/mode being lower case. I will assume that is still the case.
This guide describe installation options and procedures for Istio Ambient mesh. The two primary installation methods supported are (1) Installation via the `istioctl` cli (2) Installation via `helm`. | |
This guide describe installation options and procedures for Istio ambient mesh. The two primary installation methods supported are (1) Installation via the `istioctl` cli (2) Installation via `helm`. |
|
||
### Pre-requisites & Supported Topologies | ||
|
||
Ztunnel proxies are automatically installed when one of the supported installation methods is used to install Istio Ambient mesh. The minimum Istio version required for the functionality described in this guide is 1.18.0. At this time, the ambient mode is only supported for deployment on Kubernetes clusters, support for deployment on non-Kubernetes endpoints such as Virtual machines is expected to be a future capability. Additionally, only single cluster deployments are supported for Ambient mode. Some limited multi-cluster scenarios may work currently in ambient mode but the behavior is not guaranteed and official support for multi-cluster operation is a future capability. Finally note that Ztunnel based L4 networking is primnarily focused on East-West mesh networking and can work with all of Istio's North-South networking options including Istio-native ingress and egress gateways as well as Kubernetes native Gateway API implementation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ztunnel proxies are automatically installed when one of the supported installation methods is used to install Istio Ambient mesh. The minimum Istio version required for the functionality described in this guide is 1.18.0. At this time, the ambient mode is only supported for deployment on Kubernetes clusters, support for deployment on non-Kubernetes endpoints such as Virtual machines is expected to be a future capability. Additionally, only single cluster deployments are supported for Ambient mode. Some limited multi-cluster scenarios may work currently in ambient mode but the behavior is not guaranteed and official support for multi-cluster operation is a future capability. Finally note that Ztunnel based L4 networking is primnarily focused on East-West mesh networking and can work with all of Istio's North-South networking options including Istio-native ingress and egress gateways as well as Kubernetes native Gateway API implementation. | |
Ztunnel proxies are automatically installed when one of the supported installation methods is used to install Istio ambient mesh. The minimum Istio version required for the functionality described in this guide is 1.18.0. At this time, the ambient mode is only supported for deployment on Kubernetes clusters, support for deployment on non-Kubernetes endpoints such as Virtual machines is expected to be a future capability. Additionally, only single cluster deployments are supported for ambient mode. Some limited multi-cluster scenarios may work currently in ambient mode but the behavior is not guaranteed and official support for multi-cluster operation is a future capability. Finally note that Ztunnel based L4 networking is primarily focused on East-West mesh networking and can work with all of Istio's North-South networking options including Istio-native ingress and egress gateways as well as Kubernetes native Gateway API implementation. |
Ztunnel proxies are automatically installed when one of the supported installation methods is used to install Istio Ambient mesh. The minimum Istio version required for the functionality described in this guide is 1.18.0. At this time, the ambient mode is only supported for deployment on Kubernetes clusters, support for deployment on non-Kubernetes endpoints such as Virtual machines is expected to be a future capability. Additionally, only single cluster deployments are supported for Ambient mode. Some limited multi-cluster scenarios may work currently in ambient mode but the behavior is not guaranteed and official support for multi-cluster operation is a future capability. Finally note that Ztunnel based L4 networking is primnarily focused on East-West mesh networking and can work with all of Istio's North-South networking options including Istio-native ingress and egress gateways as well as Kubernetes native Gateway API implementation. | ||
|
||
{{< tip >}} | ||
A single Istio mesh can include pods and endpoints some of which operate using the sidecar proxy mode while others use the node level proxy of the Ambient architecture. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A single Istio mesh can include pods and endpoints some of which operate using the sidecar proxy mode while others use the node level proxy of the Ambient architecture. | |
A single Istio mesh can include pods and endpoints some of which operate using the sidecar proxy mode while others use the node level proxy of the ambient architecture. |
|
||
### Installation using Helm charts | ||
|
||
An alternative to using istioctl is to use Helm based install of Istio Ambient. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
An alternative to using istioctl is to use Helm based install of Istio Ambient. | |
An alternative to using istioctl is to use Helm based install of Istio ambient. |
|
||
One of the goals for the ztunnel proxy design is to provide a usable configuration out of the box with a fixed feature set and that does not require much, or any, custom configuration. Hence currently there are no configuration options that need to be set other than the `ambient` profile setting. Once this profile is used, this in turn sets sets 2 internal configuration parameters (as illustrated in the examples below) within the istioOperator which eventually set the configuration of the `ambient` mesh. In future there may be some additional limited configurability for ztunnel proxies. For now, the pod to ztunnel proxy networking (sometimes also called ztunnel redirection), ztunnel proxy to ztunnel proxy networking as well as ztunnel to other sidecar proxy networing all use a fixed default configuration which is not customizable. In particular, currently, the only option for pod to ztunnel networking setup is currently via the `istio-cni` and only via an internal ipTables based ztunnel traffic redirect option. There is no option to use `init-containers` unlike with sidecar proxies. Alternate forms of ztunnel traffic redirect such as ebpf are also not currently supported, although may be supported in future. Of course, once the baseline `ambient` mesh is installed, features such as Authorization policy (both L4 and L7) as well as other istio functions such as PeerAuthentication options for mutual-TLS are fully configurable similar to standard Istio. In future release versions, some limited configurability may also be added to the ztunnel proxy layer. | ||
|
||
For the examples in this guide, we used a deployment of Istio Ambient on a `kind` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kind` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the examples in this guide, we used a deployment of Istio Ambient on a `kind` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kind` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. | |
For the examples in this guide, we used a deployment of Istio ambient on a `kind` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kind` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. |
Given all the recent changes, should we try and revive this PR @srampal? |
@craigbox so the original plan for ambient user guides was to have "install"/ "upgrade" related user guides as pages/ docs within the "User guides" folder. However a "Helm install" doc was added in the top level folder and the index.md in this commit was also somewhat out of date given all the changes we made to the ztunnel user's giude etc. So now the questions are: (1) Do we expect to have multiple user guides related to "install/upgrade" type operations for ambient ? (2) Should all such user guides including the "helm install" user guide in the parent folder be moved inside the overall "user guides" folder ? If yes, then lets first just move the helm install user guide into this folder for now and later add more install/ upgrade guides either via this PR/ issue and/or new ones. Thoughts ? |
By 1.22, I think we want to have a hierarchy which looks like /docs/setup/install/ /docs/ambient/setup/install (etc) So, for now, if the content is good and useful, let's get it merged in a place that makes sense for the current hierarchy - under Though the question remains, are both Helm and istioctl officially supported install methods for ambient mode? |
(See https://docs.google.com/spreadsheets/d/1ag5zhMOm2flEK7w5D7Sv3pbpHsx7afG2hs74-h2MHCY/edit#gid=0 which suggests that we will have install docs for Helm and istioctl both.) |
Do you think there's anything in this draft which we should lift out, or should we close it? @srampal |
PR needs rebase. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
Please provide a description for what this PR is for.
And to help us figure out who should review this PR, please
put an X in all the areas that this PR affects.