istio.io/istio@v0.0.0-20240520182934-d79c90f27776/manifests/charts/README.md (about)

     1  # Istio Installer
     2  
     3  Note: If making any changes to the charts or values.yaml in this dir, first read [UPDATING-CHARTS.md](UPDATING-CHARTS.md)
     4  
     5  Istio installer is a modular, 'a-la-carte' installer for Istio. It is based on a
     6  fork of the Istio helm templates, refactored to increase modularity and isolation.
     7  
     8  Goals:
     9  - Improve upgrade experience: users should be able to gradually roll upgrades, with proper
    10  canary deployments for Istio components. It should be possible to deploy a new version while keeping the
    11  stable version in place and gradually migrate apps to the new version.
    12  
    13  - More flexibility: the new installer allows multiple 'environments', allowing applications to select
    14  a set of control plane settings and components. While the entire mesh respects the same APIs and config,
    15  apps may target different 'environments' which contain different instances and variants of Istio.
    16  
    17  - Better security: separate Istio components reside in different namespaces, allowing different teams or
    18  roles to manage different parts of Istio. For example, a security team would maintain the
    19  root CA and policy, a telemetry team may only have access to Prometheus,
    20  and a different team may maintain the control plane components (which are highly security sensitive).
    21  
    22  The install is organized in 'environments' - each environment consists of a set of components
    23  in different namespaces that are configured to work together. Regardless of 'environment',
    24  workloads can talk with each other and obey the Istio configuration resources, but each environment
    25  can use different Istio versions and different configuration defaults.
    26  
    27  `istioctl kube-inject` or the automatic sidecar injector are used to select the environment.
    28  In the case of the sidecar injector, the namespace label `istio-env: <NAME_OF_ENV>` is used instead
    29  of the conventional `istio-injected: true`. The name of the environment is defined as the namespace
    30  where the corresponding control plane components (config, discovery, auto-injection) are running.
    31  In the examples below, by default this is the `istio-control` namespace. Pod annotations can also
    32  be used to select a different 'environment'.
    33  
    34  ## Installing
    35  
    36  The new installer is intended to be modular and very explicit about what is installed. It has
    37  far more steps than the Istio installer - but each step is smaller and focused on a specific
    38  feature, and can be performed by different people/teams at different times.
    39  
    40  It is strongly recommended that different namespaces are used, with different service accounts.
    41  In particular access to the security-critical production components (root CA, policy, control)
    42  should be locked down and restricted.  The new installer allows multiple instances of
    43  policy/control/telemetry - so testing/staging of new settings and versions can be performed
    44  by a different role than the prod version.
    45  
    46  The intended users of this repo are users running Istio in production who want to select, tune
    47  and understand each binary that gets deployed, and select which combination to use.
    48  
    49  Note: each component can be installed in parallel with an existing Istio 1.0 or 1.1 installation in
    50  `istio-system`. The new components will not interfere with existing apps, but can interoperate,
    51  and it is possible to gradually move apps from Istio 1.0/1.1 to the new environments and
    52  across environments ( for example canary -> prod )
    53  
    54  Note: there are still some cluster roles that may need to be fixed, most likely cluster permissions
    55  will need to move to the security component.
    56  
    57  ## Everything is Optional
    58  
    59  Each component in the new installer is optional. Users can install the component defined in the new installer,
    60  use the equivalent component in `istio-system`, configured with the official installer, or use a different
    61  version or implementation.
    62  
    63  For example, you may use your own Prometheus and Grafana installs, or you may use a specialized/custom
    64  certificate provisioning tool, or use components that are centrally managed and running in a different cluster.
    65  
    66  This is a work in progress - building on top of the multi-cluster installer.
    67  
    68  As an extreme, the goal is to be possible to run Istio workloads in a cluster without installing any Istio component
    69  in that cluster. Currently, the minimum we require is the security provider (node agent or citadel).
    70  
    71  ### Install Istio CRDs
    72  
    73  This is the first step of the installation. Please do not remove or edit any CRD - config currently requires
    74  all CRDs to be present. On each upgrade it is recommended to reapply the file, to make sure
    75  you get all CRDs.  CRDs are separated by release and by component type in the CRD directory.
    76  
    77  Istio has strong integration with certmanager.  Some operators may want to keep their current certmanager
    78  CRDs in place and not have Istio modify them. In this case, it is necessary to apply CRD files individually.
    79  
    80  ```bash
    81  kubectl apply -k github.com/istio/installer/base
    82  ```
    83  
    84  or
    85  
    86  ```bash
    87  kubectl apply -f base/files
    88  ```
    89  
    90  ### Install Istio-CNI
    91  
    92  This is an optional step - CNI must run in a dedicated namespace, it is a 'singleton' and extremely
    93  security sensitive. Access to the CNI namespace must be highly restricted.
    94  
    95  **NOTE:** The environment variable `ISTIO_CLUSTER_ISGKE` is assumed to be set to `true` if the cluster
    96  is a GKE cluster.
    97  
    98  ```bash
    99  ISTIO_CNI_ARGS=
   100  # TODO: What k8s data can we use for this check for whether GKE?
   101  if [[ "${ISTIO_CLUSTER_ISGKE}" == "true" ]]; then
   102      ISTIO_CNI_ARGS="--set cni.cniBinDir=/home/kubernetes/bin"
   103  fi
   104  iop kube-system istio-cni $IBASE/istio-cni/ ${ISTIO_CNI_ARGS}
   105  ```
   106  
   107  TODO. It is possible to add Istio-CNI later, and gradually migrate.
   108  
   109  ### Install Control plane
   110  
   111  This can run in any cluster. A mesh should have at least one cluster should run Pilot or equivalent XDS server,
   112  and it is recommended to have Pilot running in each region and in multiple availability zones for multi cluster.
   113  
   114  ```bash
   115  iop istio-control istio-discovery $IBASE/istio-control/istio-discovery \
   116              --set global.istioNamespace=istio-system
   117  
   118  # Second istio-discovery, using master version of istio
   119  TAG=latest HUB=gcr.io/istio-testing iop istio-master istio-discovery-master $IBASE/istio-control/istio-discovery \
   120              --set policy.enable=false \
   121              --set global.istioNamespace=istio-master
   122  ```
   123  
   124  ### Gateways
   125  
   126  A cluster may use multiple Gateways, each with a different load balancer IP, domains and certificates.
   127  
   128  Since the domain certificates are stored in the gateway namespace, it is recommended to keep each
   129  gateway in a dedicated namespace and restrict access.
   130  
   131  For large-scale gateways it is optionally possible to use a dedicated pilot in the gateway namespace.
   132  
   133  ### Additional test templates
   134  
   135  A number of helm test setups are general-purpose and should be installable in any cluster, to confirm
   136  Istio works properly and allow testing the specific installation.