Skip to content
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.

Sign up for GitHub

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

Expand config profiles doc to mention helm + istioctl usage, and also mention platform profiles #16087

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Expand config profiles doc to mention helm + istioctl usage, and also mention platform profiles #16087

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
094033f
Expand the configuration profiles doc
bleggett Dec 12, 2024
6309497
Lints
bleggett Dec 12, 2024
5d954e8
fixup
bleggett Dec 12, 2024
d877ad8
Update content/en/docs/setup/additional-setup/config-profiles/index.md
bleggett Dec 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .spelling
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -474,6 +474,7 @@ edition.cnn.com
Eilers
Eitan
Ekansh
eks
Elasticsearch
embeddable
emojis
Expand Down Expand Up @@ -548,6 +549,7 @@ git
GitHub
GitOps
GKE
gke
glibc
Gloo
GlueCon
Expand Down Expand Up @@ -818,6 +820,7 @@ metaprotocol
metaresources
MiB
MicroK8s
microk8s
microservice
microservices
middleboxes
Expand Down Expand Up @@ -914,6 +917,7 @@ OpenID_Connect
OpenMetrics
OpenPolicyAgent
OpenShift
openshift
OpenSSL
openssl
OpenTelemetry
Expand Down
91 changes: 79 additions & 12 deletions content/en/docs/setup/additional-setup/config-profiles/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,60 @@ test: n/a
---

This page describes the built-in configuration profiles that can be used when
[installing Istio](/docs/setup/install/istioctl/).
The profiles provide customization of the Istio control plane and of the sidecars for the Istio data plane.
[installing Istio](/docs/setup/install).

You can start with one of [Istio’s built-in configuration profiles]({{< github_tree >}}/manifests/profiles) and then further
[customize the configuration](/docs/setup/additional-setup/customize-installation/)
for your specific needs. The following built-in configuration profiles are currently available:
Configuration profiles are simply named groups of Helm chart value overrides that are built into the charts,
and can be used when installing via either `helm` or `istioctl`.

The profiles provide high-level customization of the Istio control plane and data plane for common deployment topologies and target platforms.

{{< tip >}}
Configuration profiles compose with other values overrides or flags, so any individual value a configuration profile sets can be manually overridden by specifying a `--set` flag after it in the command.
{{< /tip >}}

There are 2 kinds of configuration profiles: _deployment_ profiles and _platform_ profiles, and using both is recommended.

- _deployment_ profiles are intended to provide good defaults for a given deployment topology (`default`, `remote`, `ambient`, etc).
- _platform_ profiles are intended to provide necessary platform-specific defaults, for a given target platform (`eks`, `gke`, `openshift`, etc).

For example, if you are installing `default` sidecar dataplane on `gke`, we recommend using the following deployment and platform profiles to get started:
bleggett marked this conversation as resolved.
Show resolved Hide resolved

{{< tabset category-name="install-method" >}}

{{< tab name="Helm" category-value="helm" >}}

For Helm, supply the same `profile` and `platform` for every chart you install, for example `istiod`:

{{< text syntax=bash snip_id=install_istiod_helm_platform >}}
$ helm install istiod istio/istiod -n istio-system --set profile=default --set global.platform=gke --wait
{{< /text >}}

{{< /tab >}}

{{< tab name="istioctl" category-value="istioctl" >}}

For `istioctl`, supply the same `profile` and `platform` as arguments:

{{< text syntax=bash snip_id=install_istiod_istioctl_platform >}}
$ istioctl install --set profile=default --set values.global.platform=gke
{{< /text >}}

{{< /tab >}}

{{< /tabset >}}

{{< warning >}}
Note that a key difference between `helm` and `istioctl` install mechanisms is that `istioctl` configuration profiles also include a list of Istio components that will be installed automatically by `istioctl`.

With `helm`, this is not the case - users are expected to install each required Istio component individually via `helm install`, and supply the desired configuration profile flags for each component manually.

You can think of this as `istioctl` and `helm` sharing exactly the same configuration profiles with the same names, but when you use `istioctl`, it will additionally choose what components to install for you based on the configuration profile you select, so only one command is needed to achieve the same result.
{{< /warning >}}

## Deployment Profiles

The following built-in deployment profiles are currently available for both `istioctl` and `helm` install mechanisms. Note that as these are just sets of Helm values overrides, using them is not strictly required to install Istio, but they do provide a convenient baseline and are recommended for new installs. Additionally, you may [customize the configuration](/docs/setup/additional-setup/customize-installation/)
beyond what the deployment profile includes, for your specific needs. The following built-in deployment profiles are currently available:

1. **default**: enables components according to the default settings of the
[`IstioOperator` API](/docs/reference/config/istio.operator.v1alpha1/).
Expand All @@ -38,19 +86,16 @@ for your specific needs. The following built-in configuration profiles are curre
{{< gloss >}}external control plane{{< /gloss >}} or by a control plane in a {{< gloss >}}primary cluster{{< /gloss >}}
of a [multicluster mesh](/docs/ops/deployment/deployment-models/#multiple-clusters).

1. **ambient**: the ambient profile is designed to help you get started with [ambient mode](/docs/ambient).

1. **empty**: deploys nothing. This can be useful as a base profile for custom configuration.

1. **preview**: the preview profile contains features that are experimental. This is intended to explore new features
coming to Istio. Stability, security, and performance are not guaranteed - use at your own risk.

1. **ambient**: the ambient profile is designed to help you get started with [ambient mode](/docs/ambient).

{{< tip >}}
Some additional vendor-specific configuration profiles are also available.
For more information, refer to the [setup instructions](/docs/setup/platform-setup) for your platform.
{{< /tip >}}
Istio's [deployment profile value sets are defined here]({{< github_tree >}}/manifests/helm-profiles), for both `istioctl` and `helm`.

The components marked as &#x2714; are installed within each profile:
For `istioctl` only, specifying configuration profiles additionally automatically selects certain Istio components for installation, as marked with &#x2714; below:

| | default | demo | minimal | remote | empty | preview | ambient |
| --- | --- | --- | --- | --- | --- | --- | --- |
Expand All @@ -61,5 +106,27 @@ The components marked as &#x2714; are installed within each profile:
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`CNI` | | | | | | | &#x2714; |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`Ztunnel` | | | | | | | &#x2714; |

{{< tip >}}
To further customize Istio, a number of addon components can also be installed.
Refer to [integrations](/docs/ops/integrations) for more details.
{{< /tip >}}

## Platform Profiles

The following built-in platform profiles are currently available for both `istioctl` and `helm` install mechanisms. Note that as these are just sets of Helm values overrides, using them is not strictly required to install Istio in these environments, but they do provide a convenient baseline and are recommended for new installs:

1. **gke**: Sets chart options required or recommended for installing Istio in Google Kubernetes Engine (GKE) environments.

1. **eks**: Sets chart options required or recommended for installing Istio in Amazon's Elastic Kubernetes Service (EKS) environments.

1. **openshift**: Sets chart options required or recommended for installing Istio in OpenShift environments.

1. **k3d**: Sets chart options required or recommended for installing Istio in [k3d](https://k3d.io/) environments.

1. **k3s**: Sets chart options required or recommended for installing Istio in [K3s](https://k3s.io/) environments.

1. **microk8s**: Sets chart options required or recommended for installing Istio in [MicroK8s](https://microk8s.io/) environments.

1. **minikube**: Sets chart options required or recommended for installing Istio in [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) environments.

Istio's [platform profiles are defined here]({{< github_tree >}}/manifests/helm-profiles), for both `istioctl` and `helm`.