- Releasing OpenSearch
- Contributing
- Getting Help
- Code of Conduct
- Security
- License
- Copyright
Releasing OpenSearch
Releases and Versions
The OpenSearch project releases as versioned distributions of OpenSearch, OpenSearch Dashboards, and the OpenSearch plugins. It follows semantic versioning. Software, such as Data Prepper, clients, and the Logstash output plugin, are versioned independently of the OpenSearch Project. They also may have independent releases from the main project distributions. The OpenSearch Project may also release software under alpha, beta, release candidate, and generally available labels. The definition of when to use these labels is derived from the Wikipedia page on Software release lifecycle. Below is the definition of when to use each label.
Release labels:
- Alpha - The code is released with instructions to build. Built distributions of the software may not be available. Some features many not be complete. Additional testing and developement work is planned. Distributions will be postfixed with
-alphaXwhere "X" is the number of the alpha version (e.g., "2.0-alpha1"). - Beta - Built distributions of the software are available. All features are completed. Additional testing and developement work is planned. Distributions will be postfixed with
-betaXwhere "X" is the number of the beta version (e.g., "2.0.0-beta1"). - Release Candidate - Built distributions of the software are available. All features are completed. Code is tested and minimal validation remains. At this stage the software is potentially stable and will release unless signficant bugs emerge. Distributions will be postfixed with
-rcXwhere "X" is the number of the release candidate version (e.g., "2.0.0-rc1"). - Generally Available - Built distributions of the software are available. All features are completed and documented. All testing is completed. Distributions for generally available versions are not postfixed with an additional label (e.g., "2.0.0").
Creating a New Version
Each new OpenSearch release process starts when any one component increments a version, typically on the main branch. For example, OpenSearch#1192 incremented the version to 2.0. The version check automation workflow will notice this change or it can be triggered manually, and make a pull request (e.g. opensearch-build#514) that adds a new manifest (e.g. opensearch-2.0.0.yml. After that's merged, a GitHub issue is automatically opened by this workflow to make a new release using this release template (e.g. opensearch-build#566). Existing and new components (re)onboard into every release by submitting pull requests to each version's manifest.
Onboarding a New Plugin
Plugin owners can follow the Onboarding Process to onboard their plugins to the release process.
Building and Testing an OpenSearch Distribution
The distribution workflow builds a complete OpenSearch and OpenSearch Dashboards distribution from source. You can currently build 1.0, 1.1, 1.1-SNAPSHOT and 1.2 versions. This system performs a top-down build of all components required for a specific OpenSearch and OpenSearch Dashboards release, then assembles a distribution. The input to the system is a manifest that defines the order in which components should be built. All manifests for our current releases are here.
Building from Source
./build.sh manifests/1.3.0/opensearch-1.3.0.yml This builds OpenSearch 1.3.0 from source, placing the output into ./builds/opensearch.
See build workflow for more information.
Assembling a Distribution
./assemble.sh builds/opensearch/manifest.ymlThe assembling step takes output from the build step, installs plugins, and assembles a full distribition into the dist folder.
See assemble workflow for more information.
Building Patches
A patch release contains output from previous versions mixed with new source code. Manifests can mix such references. See opensearch-1.1.1.yml for an example.
OpenSearch is often released with changes in opensearch-min, and no changes to plugins other than a version bump. This can be performed by a solo Engineer following a cookbook. See also opensearch-build#1375 which aims to automate incrementing versions for the next development iteration.
CI/CD Environment
We build, assemble, and test our artifacts on docker containers. We provide docker files in docker/ci folder, and images on staging docker hub repositories. All Jenkins pipelines can be found in jenkins. Jenkins itself is in the process of being made public and its CDK open-sourced.
See jenkins and docker for more information.
Latest Distribution Url
The distribution url has a build number (from Jenkins job) embedded inside it. See this example where 3942 is the build number. https://ci.opensearch.org/ci/dbc/distribution-build-opensearch-dashboards/2.1.0/3942/linux/arm64/rpm/builds/opensearch-dashboards/manifest.yml
The feature of latest distribution url is to make it build number agnostic. For the example above, its corresponding latest distribution url is as follows.
It resolves latest to a specific build number by checking an index.json file. This file has contents like this.
{"latest":"3942"}
The file is updated when a distribution build job is completed for the given product and version (or is created when such distribution job succeeds for the first time). Since one distribution build job consists of multiple stages for diffferent combinations of distribution type, platform and architecture, the index.json is only modified once all stages succeed. With this said, the latest url only works when the distribution build job succeeds at least once for the given product and version.
The resolution logic exists in CloudFront url rewriter. The TTL (time to live) is set to 5 mins which means that the latest url may need up to 5 mins to get new contents after index.json is updated.
All the artifacts accessible through the regular distribution url can be accessed by the latest url. This includes both OpenSearch Core, OpenSearch Dashboards Core and their plugins.
Testing the Distribution
Tests the OpenSearch distribution, including integration, backwards-compatibility and performance tests.
./test.sh <test-type> <test-manifest-path> <path>See src/test_workflow for more information.
Signing Artifacts
The signing step takes the manifest file created from the build step and signs all its component artifacts using a tool called opensearch-signer-client (in progress of being open-sourced). The input requires a path to the build manifest and is expected to be inside the artifacts directory with the same directories mentioned in the build step.
./sign.sh builds/opensearch/manifest.ymlSee src/sign_workflow for more information.
Making a Release
Releasing for Linux
The Linux release is managed by a team at Amazon following this release template (e.g. opensearch-build#566).
Releasing for FreeBSD
The FreeBSD ports and packages for OpenSearch are managed by a community OpenSearch Team at FreeBSD. When a new release is rolled out, this team will update the port and commit it to the FreeBSD ports tree. Anybody is welcome to help the team by providing patches for upgrading the ports following the FreeBSD Porter's Handbook instructions.
Releasing for Windows
At this moment there's no official Windows distribution. However, this project does support building and assembling OpenSearch for Windows, with some caveats. See opensearch-build#33 for details.
Releasing for MacOS
At this moment there's no official MacOS distribution. However, this project does support building and assembling OpenSearch for MacOS. See opensearch-build#37 and #38 for more details.
Utilities
Checking Out Source
The checkout workflow checks out source code for a given manifest for further examination.
./checkout.sh manfiests/1.3.0/opensearch-1.3.0.ymlSee src/checkout_workflow for more information.
Cross-Platform Builds
You can perform cross-platform builds. For example, build and assemble a Windows distribution on MacOS.
export JAVA_HOME=$(/usr/libexec/java_home) # required by OpenSearch install-plugin during assemble
./build.sh manifests/1.3.0/opensearch-1.3.0.yml --snapshot --platform windows
./assemble.sh builds/opensearch/manifest.ymlThis will produce dist/opensearch-1.3.0-SNAPSHOT-windows-x64.zip on Linux and MacOS.
Sanity Checking the Bundle
This workflow runs sanity checks on every component present in the bundle, executed as part of the manifests workflow in this repository. It ensures that the component GitHub repositories are correct and versions in those components match the OpenSearch version.
The following example sanity-checks components in the the OpenSearch 1.3.0 manifest.
./ci.sh manifests/1.3.0/opensearch-1.3.0.yml --snapshotSee src/ci_workflow for more information.
Auto-Generating Manifests
The manifests workflow reacts to version increments in OpenSearch and its components by extracting Gradle properties from project branches. When a new version is found, a new input manifest is added to manifests, and a pull request is opened (e.g. opensearch-build#491).
Show information about existing manifests.
./manifests.sh listCheck for updates and create any new manifests.
./manifests.sh updateSee src/manifests_workflow for more information.
Deploying Infrastructure
Storage and access roles for the OpenSearch release process are codified in a CDK project.
Contributing
See developer guide and how to contribute to this project.
Getting Help
If you find a bug, or have a feature request, please don't hesitate to open an issue in this repository.
For more information, see project website and documentation. If you need help and are unsure where to open an issue, try forums.
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ, or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
Security
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.
License
This project is licensed under the Apache v2.0 License.
Copyright
Copyright OpenSearch Contributors. See NOTICE for details.