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

     1  # Updating charts and values.yaml
     2  
     3  ## Acceptable Pull Requests
     4  
     5  Helm charts `values.yaml` represent a complex user facing API that tends to grow uncontrollably over time
     6  due to design choices in Helm.
     7  The underlying Kubernetes resources we configure have 1000s of fields; given enough users and bespoke use cases,
     8  eventually someone will want to customize every one of those fields.
     9  If all fields are exposed in `values.yaml`, we end up with an massive API that is also likely worse than just using the Kubernetes API directly.
    10  
    11  To avoid this, the project attempts to minimize additions to the `values.yaml` API where possible.
    12  
    13  If the change is a dynamic runtime configuration, it probably belongs in the [MeshConfig API](https://github.com/istio/api/blob/master/mesh/v1alpha1/config.proto).
    14  This allows configuration without re-installing or restarting deployments.
    15  
    16  If the change is to a Kubernetes field (such as modifying a Deployment attribute), it will likely need to be install-time configuration.
    17  However, that doesn't necessarily mean a PR to add a value will be accepted.
    18  The `values.yaml` API is intended to maintain a *minimal core set of configuration* that most users will use.
    19  For bespoke use cases, [Helm Chart Customization](https://istio.io/latest/docs/setup/additional-setup/customize-installation-helm/#advanced-helm-chart-customization) can be used
    20  to allow arbitrary customizations.
    21  
    22  If the change truly is generally purpose, it is generally preferred to have broader APIs. For example, instead of providing
    23  direct access to each of the complex fields in [affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/), just providing
    24  a single `affinity` field that is passed through as-is to the Kubernetes resource.
    25  This provides maximum flexibility with minimal API surface overhead.
    26  
    27  ## Making changes
    28  
    29  ## Step 1. Make changes in charts and values.yaml in `manifests` directory
    30  
    31  Be sure to provide sufficient documentation and example usage in values.yaml.
    32  If the chart has a `values.schema.json`, that should be updated as well.
    33  
    34  ## Step 2. Update the istioctl/Operator values
    35  
    36  If you are modifying the `gateway` chart, you can stop here.
    37  All other charts, however, are exposed by `istioctl` and need to follow the steps below.
    38  
    39  The charts in the `manifests` directory are used in istioctl to generate an installation manifest.
    40  
    41  If `values.yaml` is changed, be sure to update corresponding values changes in [../profiles/default.yaml](../profiles/default.yaml)
    42  
    43  ## Step 3. Update istioctl schema
    44  
    45  Istioctl uses a [schema](../../operator/pkg/apis/istio/v1alpha1/values_types.proto) to validate the values. Any changes to
    46  the schema must be added here, otherwise istioctl users will see errors.
    47  Once the schema file is updated, run:
    48  
    49  ```bash
    50  $ make operator-proto
    51  ```
    52  
    53  This will regenerate the Go structs used for schema validation.
    54  
    55  ## Step 4. Update the generated manifests
    56  
    57  Tests of istioctl use the auto-generated manifests to ensure that the istioctl binary has the correct version of the charts.
    58  To regenerate the manifests, run:
    59  
    60  ```bash
    61  $ make copy-templates update-golden
    62  ```
    63  
    64  ## Step 5. Create a PR using outputs from Steps 1 to 4
    65  
    66  Your PR should pass all the checks if you followed these steps.