From 094033f107db81f1cc6406e5124ba2e53f263ae3 Mon Sep 17 00:00:00 2001 From: Benjamin Leggett Date: Thu, 12 Dec 2024 18:21:00 -0500 Subject: [PATCH 1/4] Expand the configuration profiles doc Signed-off-by: Benjamin Leggett --- .../additional-setup/config-profiles/index.md | 90 ++++++++++++++++--- 1 file changed, 78 insertions(+), 12 deletions(-) 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 20a24fac5d01b..5c424fa9e41c6 100644 --- a/content/en/docs/setup/additional-setup/config-profiles/index.md +++ b/content/en/docs/setup/additional-setup/config-profiles/index.md @@ -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. + +{{< 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/). @@ -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 ✔ are installed within each profile: +For `istioctl` only, specifying configuration profiles additionally automatically selects certain Istio components for installation, as marked with ✔ below | | default | demo | minimal | remote | empty | preview | ambient | | --- | --- | --- | --- | --- | --- | --- | --- | @@ -61,5 +106,26 @@ The components marked as ✔ are installed within each profile: |       `CNI` | | | | | | | ✔ | |       `Ztunnel` | | | | | | | ✔ | +{{< 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`. From 6309497460bd6000192e4c237f827dc662038375 Mon Sep 17 00:00:00 2001 From: Benjamin Leggett Date: Thu, 12 Dec 2024 18:33:57 -0500 Subject: [PATCH 2/4] Lints Signed-off-by: Benjamin Leggett --- .spelling | 4 ++++ .../docs/setup/additional-setup/config-profiles/index.md | 7 ++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.spelling b/.spelling index 7708532d59d0d..9f812f42cc328 100644 --- a/.spelling +++ b/.spelling @@ -474,6 +474,7 @@ edition.cnn.com Eilers Eitan Ekansh +eks Elasticsearch embeddable emojis @@ -548,6 +549,7 @@ git GitHub GitOps GKE +gke glibc Gloo GlueCon @@ -818,6 +820,7 @@ metaprotocol metaresources MiB MicroK8s +microk8s microservice microservices middleboxes @@ -914,6 +917,7 @@ OpenID_Connect OpenMetrics OpenPolicyAgent OpenShift +openshift OpenSSL openssl OpenTelemetry 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 5c424fa9e41c6..929e35a44d749 100644 --- a/content/en/docs/setup/additional-setup/config-profiles/index.md +++ b/content/en/docs/setup/additional-setup/config-profiles/index.md @@ -12,7 +12,7 @@ test: n/a This page describes the built-in configuration profiles that can be used when [installing Istio](/docs/setup/install). -Configuration profiles are simply named groups of Helm chart value overrides that are built into the charts, +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. @@ -60,8 +60,8 @@ With `helm`, this is not the case - users are expected to install each required 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: @@ -112,13 +112,14 @@ 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. **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. From 5d954e8d9d8f77d989cbb195a356759f255b464c Mon Sep 17 00:00:00 2001 From: Benjamin Leggett Date: Thu, 12 Dec 2024 18:40:03 -0500 Subject: [PATCH 3/4] fixup Signed-off-by: Benjamin Leggett --- .../docs/setup/additional-setup/config-profiles/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 929e35a44d749..af62c26135858 100644 --- a/content/en/docs/setup/additional-setup/config-profiles/index.md +++ b/content/en/docs/setup/additional-setup/config-profiles/index.md @@ -26,13 +26,13 @@ There are 2 kinds of configuration profiles: _deployment_ profiles and _platform - _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. +For example, if you are installing `default` sidecar dataplane on `gke`, we recommend using the following deployment and platform profiles to get started: {{< 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`: + 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 @@ -42,7 +42,7 @@ For Helm, supply the same `profile` and `platform` for every chart you install, {{< tab name="istioctl" category-value="istioctl" >}} -For `istioctl`, supply the same `profile` and `platform` as arguments: + 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 @@ -95,7 +95,7 @@ beyond what the deployment profile includes, for your specific needs. The follow Istio's [deployment profile value sets are defined here]({{< github_tree >}}/manifests/helm-profiles), for both `istioctl` and `helm`. -For `istioctl` only, specifying configuration profiles additionally automatically selects certain Istio components for installation, as marked with ✔ below +For `istioctl` only, specifying configuration profiles additionally automatically selects certain Istio components for installation, as marked with ✔ below: | | default | demo | minimal | remote | empty | preview | ambient | | --- | --- | --- | --- | --- | --- | --- | --- | From d877ad876a80ad7db87336dab82df1b350519f2d Mon Sep 17 00:00:00 2001 From: Ben Leggett <854255+bleggett@users.noreply.github.com> Date: Fri, 13 Dec 2024 12:53:18 -0500 Subject: [PATCH 4/4] Update content/en/docs/setup/additional-setup/config-profiles/index.md Co-authored-by: Daniel Hawton --- content/en/docs/setup/additional-setup/config-profiles/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 af62c26135858..f72344be026f4 100644 --- a/content/en/docs/setup/additional-setup/config-profiles/index.md +++ b/content/en/docs/setup/additional-setup/config-profiles/index.md @@ -26,7 +26,7 @@ There are 2 kinds of configuration profiles: _deployment_ profiles and _platform - _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: +For example, if you are installing `default` sidecar dataplane on GKE, we recommend using the following deployment and platform profiles to get started: {{< tabset category-name="install-method" >}}