add istioctl install page for ambient and improve install docs experience

[craigbox]

Add docs on how to install ambient with istioctl.
When @bleggett's changes to Helm docs are in, I'll modify ths further to bring the two in line.

• Ambient
• Docs

[craigbox]

/test doc.test.profile-default

(#15576)

[bleggett]

Suggested change

	The following configurations apply to all platforms, when certain {{< gloss "CNI" >}}CNI plugins{{< /gloss >}} are used:
	The following configurations apply to any platform when specific {{< gloss "CNI" >}}CNIs{{< /gloss >}} are used:

[bleggett]

plugin is an impl detail that's not relevant to any of this, and I want to continually reinforce that you already have a CNI (which may ship one or more plugins + lots of other bits), which is not Istio.

We can say "CNI provider" here if we want.

When we say "CNI" or "CNI provider" -> that's the universe of not-Istio
When we say "CNI plugin" -> that's the only thing Istio does that's CNI related, and the phrase "CNI plugin" should be used very sparingly outside of the CNI detailed docs.

People are already confused enough about this.

[craigbox]

It would be more correct to say "CNI runtime"? But less understood, I would think. Kubernetes uses the term 'CNI plugin', as do many of the people that make them:

Kubernetes uses the Container Network Interface (CNI) to interact with networking providers like Calico. The Calico binary that presents this API to Kubernetes is called the CNI plugin and must be installed on every node in the Kubernetes cluster.

and thus I think this is a fight that is lost outside of the universe of people who actually write CNI implementations.

We were trying to have our thing be called the 'CNI node agent' to differentiate it. Is that not sensible?

(p.s. I see you)

[bleggett]

CNI node agent is the most sensible, I mostly just don't want to say CNI plugin and have it not be clear if we're talking about our thing (which is not a CNI, and consists of more than a plugin) or the thing you already have (which is, and consists of more than a plugin).

[bleggett]

Suggested change

	`istioctl` supports a number of [configuration profiles](/docs/setup/additional-setup/config-profiles/) that include different default options,
	and can be customized for your production needs. Support for ambient mode is included in the `ambient` profile. Install Istio with the
	following command:
	Support for ambient mode is included in the `ambient` profile. Install Istio with the
	following command:

The profiles support between istioctl and helm is 1-to-1 - they are the same profiles, in fact.

So either we need to blurb this on the helm page too ("hey, we have other profiles, go look") - or do what that page does, and don't blurb it.

Either way, should be consistent.

[craigbox]

The sidecar installation docs haven't been meaningfully updated from the time when they were the only installation method.

I agree that a complete overhaul of this is a good idea but I'm not going to boil the ocean in this PR. I haven't created an issue for this one because I believe that istio/istio#52702 should be general enough for sidecars too.

[craigbox]

On the topic of ambient specifically, with istioctl you need profile=ambient in order to tell it to install ztunnel and istio-cni. It's reasonable to point that out here - if you only did istioctl install, you wouldn't get working ambient mode.

Given that, in the Helm docs, we explicitly say you need to install Helm charts A B C and D, individually including ztunnel and CNI. What use are profiles there? Why are these two lines different?

$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
$ helm install ztunnel istio/ztunnel -n istio-system --wait 

[craigbox]

OK, it's explained in https://github.com/istio/istio/blob/master/manifests/helm-profiles/ambient.yaml that they are just sets of values, not groups of components.

an IstioOperator profile is a list of components and a link to a Helm profile.

this isn't half confusing.

[bleggett]

Profiles for both are almost entirely (and primarily) sets of values, and in fact both the Istio and helm ones are derived from the same file IIRC.

(they could be both sets of values and of components for both helm and istioctl pretty easily if we did chart composition in helm, but we do not).

[craigbox]

The ambient Helm profile contains environment variables and flags.

The ambient istioctl profile contains a list of components to enable, and an instruction to Helm to use the ambient Helm profile.

So yes, you're mostly right, but in the specific case of ambient, the istioctl profile is necessary to say "install ztunnel", where that is spelled out in the Helm docs.

This has been a useful exercise to understand the distinction, and if we could get chart composition - I assume you get that through dependencies? - then it would be possible to get the same outcome yes, though not through something called a profile. :)

[howardjohn]

I doubt the helm profiles would work via dependencies unfortunately... helm doesn't have native 'profile' concept so we hack it in a way that would apply the config after it has chosen which dependencies to enable I suspect (untested) (https://blog.howardjohn.info/posts/advanced-helm/)

[bleggett]

Dependencies in helm can be enabled or disabled based on values.yaml properties, so I would expect if you disabled a component but a profile still supplied values for it, that would just no-op in the templating and give you ~roughly the same behavior as istioctl install <specific component> -f large-operator-yaml-with-many-settings-that-do-not-apply-to-that-component.yaml today.

but yeah, need to test. Helm can do what istioctl install does, we just don't use Helm in a way that lets us use those features.

[craigbox]

I've addressed all of Ben's comments with a bunch of "will fix later" issues, and what would you know, I think I've fixed #15576.

@dhawton for approval, or telling me to split the fix into its own PR first.

[kfaseela]

LGTM

[howardjohn]

LGTM

[howardjohn]

off topic but we should automate this or warn in istioctl

[howardjohn]

also off topic, we should automagically detect this, k3s, and microk8s

[craigbox]

/test doc.test.profile-demo

[craigbox]

/cherry-pick release-1.23

[istio-testing]

@craigbox: new pull request created: #15597

In response to this:

/cherry-pick release-1.23

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.