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

     1  # Istio Release Notes
     2  
     3  This directory contains the release notes, upgrade notes, and security notes for Istio.
     4  Notes should be created as part of the pull request for any user facing changes. Before
     5  a release, the release notes utility will be run in order to generate a release notes file
     6  which will be reviewed by the release managers and documentation team.
     7  
     8  ## When to Add Release Notes
     9  
    10  Release notes should be added for any user facing changes. These include:
    11  * CLI changes
    12  * API changes
    13  * Configuration schema change
    14  * Behavioral change
    15  * Change in non-functional attributes such as efficiency or availability, availability of a new platform
    16  * A warning about a deprecation
    17  * Fix of a previous Known Issue
    18  * Promoting features
    19  
    20  No release notes are required for changes to:
    21  * Tests
    22  * Build Infrastructure
    23  * Fixes of bugs that have not been released.
    24  
    25  ## Adding a Release Note
    26  
    27  To create a release note, create a new file in the [./notes](./notes) directory based on
    28  the [template](./template.yaml). The filename doesn't matter as long as it ends with a `.yaml`
    29  extension and matches the format specified in the template. However, please make names descriptive.
    30  
    31  ```yaml
    32  apiVersion: release-notes/v2
    33  kind: bug-fix
    34  area: traffic-management
    35  
    36  # issue is a list of GitHub issues resolved in this note.
    37  issue:
    38    - https://github.com/istio/istio/issues/23622
    39    - 23624
    40  
    41  docs:
    42   - '[usage] https://istio.io/latest/docs/tasks/traffic-management/request-routing/'
    43   - '[reference] https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/'
    44  
    45  releaseNotes:
    46  - |
    47    **Fixed** an issue preventing the operator from recreating watched resources if they are deleted
    48  
    49  upgradeNotes:
    50    - title: Change the readiness port of gateways
    51      content: |
    52        If you are using the 15020 port to check the health of your Istio ingress gateway with your Kubernetes network load balancer, change the port from 15020 to 15021.
    53  
    54  securityNotes:
    55  - |
    56    __[CVE-2020-15104](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-15104)__:
    57    When validating TLS certificates, Envoy incorrectly allows a wildcard DNS Subject Alternative Name to apply to multiple subdomains. For example, with a SAN of `*.example.com`, Envoy incorrectly allows `nested.subdomain.example.com`, when it should only allow `subdomain.example.com`.
    58      - CVSS Score: 6.6 [AV:N/AC:H/PR:H/UI:N/S:C/C:H/I:L/A:N/E:F/RL:O/RC:C](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:H/PR:H/UI:N/S:C/C:H/I:L/A:N/E:F/RL:O/RC:C&version=3.1)
    59  ```
    60  
    61  Some release notes may affect multiple types of notes. For those, please fill in all respective areas. For notes that only affect one or two areas, please fill in only those sections. Sections that don't have content can be omitted.
    62  
    63  ### Area
    64  
    65  This field describes the area of Istio that the note affects. Valid values include:
    66  * traffic-management
    67  * security
    68  * telemetry
    69  * extensibility
    70  * installation
    71  * istioctl
    72  * documentation
    73  
    74  ### Issue
    75  
    76  While many pull requests will only fix a single GitHub issue, some pull requests may fix multiple issues. Please list all fixed GitHub issues. Issues written as numbers only will be interpreted as being reported against the `istio/istio` repo, while issues recorded as URLs will be read as the supplied URLs.
    77  
    78  ## docs
    79  
    80  The `docs` field should be used to list related documentation. These will be turned into links and appended to the note alongside the issues. Quotes are **required** for docs entries or you may see YAML errors such as `did not find expected alphabetic or numeric character`.
    81  
    82  ### Release Notes
    83  
    84  These notes detail bug fixes, feature additions, removals, or other general content that has an impact to users. Release notes should be written in complete sentences, and the first word should be an action presented in the format `**Action**`. Acceptable actions are: `**Added**`, `**Deprecated**`, `**Enabled**`, `**Fixed**`, `**Optimized**`, `**Improved**`, `**Removed**`, `**Promoted**`, and `**Upgraded**`.
    85  
    86  ### Upgrade Notes
    87  
    88  These notes detail the changes which purposefully break backwards compatibility with the previous version of Istio. The notes also mention changes which preserve backwards compatibility while introducing new behavior. Changes are only included if the new behavior would be unexpected to a user. These should be written in paragraph format with a title and content.
    89  
    90  ### Security Notes
    91  
    92  These notes detail fixes to security issues in Istio. These may be upgrades to vulnerable libraries, fixes for CVEs, or related content. Security Notes should start with the first the CVE ID in the format `__[CVE-2020-15104](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-15104)__` followed by a description and then the CVSS score in the format `CVSS Score: 6.6 [AV:N/AC:H/PR:H/UI:N/S:C/C:H/I:L/A:N/E:F/RL:O/RC:C](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:H/PR:H/UI:N/S:C/C:H/I:L/A:N/E:F/RL:O/RC:C&version=3.1)`
    93  
    94  ## Adding a release note to multiple Istio Releases
    95  
    96  Just as code fixes should be added to master first, notes should as well. To add a note to multiple releases, just cherrypick them over to the appropriate release and the release notes tooling will include them in its generation.