devtron-labs · ashokdevtron · Jul 23, 2024 · Jul 8, 2024 · Jul 8, 2024 · Jul 8, 2024
@@ -104,6 +104,9 @@
   * [Trigger Job](user-guide/jobs/triggering-job.md)
   * [Overview](user-guide/jobs/overview-job.md) 
 * [Application Groups](user-guide/application-groups.md)
+* [Software Distribution Hub](user-guide/sdh/README.md)
+  * [Tenants](user-guide/sdh/tenants.md)
+  * [Release Hub](user-guide/sdh/release-hub.md)
 * [Resource Browser](user-guide/resource-browser.md)   
 * [Resource Watcher](user-guide/resource-watcher.md) 
 * [Charts](user-guide/deploy-chart/README.md)

@@ -0,0 +1,79 @@
+# Software Distribution Hub
+
+## Introduction [![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/elements/EnterpriseTag.svg)](https://devtron.ai/pricing)
+
+Software Distribution Hub is a platform that simplifies the packaging, versioning, and delivery of your software products. By using it, you can manage your software release across multiple clients ([tenants](#release-versions)).
+
+![Figure: Software Distribution Hub](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/sdh-eagle-eye.gif)
+
+
+### When and Why to Use
+
+Devtron's Software Distribution Hub Devtron is designed to be used in scenarios where:
+
+* **Multi-Tenant Deployments**: You build software solutions for multiple clients (tenants) who require updates deployed to their distinct environments. For one client you may have to deploy a separate instance of your application, which has separate application layer and data layer on their infrastructure.
+
+* **Complex Release Management**: You need a centralized solution to manage the deployment of software updates across various environments and ensure smooth collaboration between different teams involved in the release process.
+
+* **Enhanced Visibility and Monitoring**: You need improved visibility into the release process for stakeholders such as Release Managers, Developers, DevOps teams, System Reliability Engineers (SREs), Tenant Points of Contact (POCs), and other stakeholders. They need to monitor releases, debug issues, and have access to current operational statuses.
+
+* **Standardized Deployment Processes**: You want to standardize and automate deployment processes to ensure error-free releases and streamline operations across multiple tenant environments.
+
+* **Comprehensive Release Documentation**: You require detailed documentation and checklists for each release, specifying versioning, dependencies, configuration changes, and deployment prerequisites to ensure consistent and successful deployments.
+
+---
+
+## Advantages
+
+Devtron's Software Distribution Hub goes beyond basic deployment by providing end-to-end release management. Deployments involving manual processes might be prone to human error. However, Software Distribution Hub automates the [rollout](#rollout) process by enforcing [requirements](#requirements) for each release, and not just for one environment but multiple tenant environments.
+
+### Normal Deployment vs SDH
+
+| Aspect                                     | Normal Deployment                            | Software Distribution Hub                                      |
+|--------------------------------------------|----------------------------------------------|----------------------------------------------------------------|
+| **Release Management**                     | No versioned deployments                     | Centralizes versioning and deployment into a unified platform  |
+| **Visibility**                             | Limited visibility (Apps/App Groups)         | Comprehensive visibility                                       |
+| **Automated and Standardized Deployments** | Relies on manual scripts or basic automation (jobs) | Automates and standardizes deployments for consistency  |
+| **End-to-End Release Management**          | Focuses on pushing changes quickly           | Manages entire release lifecycle from planning to post-release |
+
+---
+
+## Concepts
+
+Devtron's Software Distribution Hub has 2 sections:
+
+* [Tenants](./tenants.md)
+* [Release Hub](./release-hub.md)
+
+
+Feel free to familiarize yourself with the following concepts (terms) before you proceed to Software Distribution Hub.
+
+### Tenants
+
+Tenants are organizations or clients that use your software. You can think of each tenant as a separate customer. For example, if Microsoft and Google both use your software, they are considered separate tenants. Each tenant has its own environment to ensure their data and operations are kept separate from others.
+
+### Installations
+
+One installation is equivalent to one deployment of your software for a specific [tenant](#tenants). Each installation is a different instance of the software tailored to different stages of use. For example, Microsoft might have three installations: 
+
+* **Production Installation**: Where the live environment of the software runs for everyday use.
+* **Development Installation**: Used for testing new features and changes before they go live.
+* **QA Installation**: Dedicated to quality assurance testing to ensure the software works correctly before it reaches users.
+
+### Release Tracks
+
+A Release Track in Devtron is where you organize software releases, similar to a project or application. Each release within a Release Track is a unique version of your software. For example, think of Kubernetes as a release track, with "v1.28.8" as one of its releases. This helps in managing different versions and updates of a software project in a structured manner, ensuring that all versions are tracked and organized within their respective tracks.
+
+### Requirements
+
+Requirements refer to specific steps that should be taken before deployment of applications. This includes selecting specific images for each application, specifying the [release order](#release-orderstage) of applications, adding release instructions, and locking these requirements to ensure readiness before a [rollout](#rollout). 
+
+### Release Order/Stage
+
+This is a part of [requirements](#requirements) where you decide the stages in which applications are deployed. This ensures that all dependencies are met and the software is implemented correctly. For example, you might need to deploy a database update before deploying a new application feature that relies on that update. In such a case, release order ensures that the backend applications are deployed in first stage and then the frontend applications deploy as intended.
+
+### Rollout
+
+The process of deploying a release to the tenant's environment involves all necessary steps and stages to ensure successful deployment.
+
+
@@ -0,0 +1,238 @@
+# Release Hub
+
+{% hint style="warning" %}
+### Prerequisite
+Create a [Tenant](./tenants.md) before proceeding with any action in Release Hub.
+{% endhint %}
+
+This section allows you to define [release tracks](./README.md#release-tracks), create and version software releases, add applications, select container images, and deploy releases to specified tenant [installations](./README.md#installations).
+
+## Creating Release Tracks and Versions
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to create release track.
+{% endhint %}
+
+This involves the creation of release tracks and software versions. A release track helps you organize and keep track of different versions of your software. So if you ship multiple products (say HRMS, Web Builder, Video Editing Tools), you can create separate release tracks for each.
+
+1. Click **+ Release Track**.
+
+    ![Figure 1: Creating New Release Track](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/add-track.jpg)
+
+2. Give a name to the track, e.g., `numero`
+
+3. (Optional) Add a description of the track.
+
+4. Click **Create Release Track**.
+
+    ![Figure 2: Entering Track Details](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/track-creation.jpg)
+
+5. Click **+ Create Release**.
+
+    ![Figure 3: Creating New Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/create-release.jpg)
+
+6. Select a track (e.g., *numero*) from the **Release Track** dropdown.
+
+    ![Figure 4: Choosing Release Track](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/track-selection.jpg)
+
+7. Enter a [semantic version](https://semver.org/) in **Release Version** field, e.g., `1.0.0`
+
+    ![Figure 5: Versioning the Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/semantic-versioning.jpg)
+
+8. (Optional) Give a name to the release, e.g., `numero-beta`. If you don’t provide one, the name will be same as release version (i.e., 1.0.0).
+
+9. (Optional) Add a description of the release.
+
+10. Click **Create Release**.
+
+    ![Figure 6: Saving Release Details](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/release-version.jpg)
+
+If you are creating your first release, you may proceed with the **Create from scratch** option. However, for subsequent versions of your release (say 1.0.1), you may clone an existing release (e.g., 1.0.0) as shown below. Please note, you can only clone releases belonging to the same track.
+
+![Figure 7: Cloning an Existing Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/clone-release.jpg)
+
+---
+
+## Adding Applications
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to add applications to a release track.
+{% endhint %}
+
+This involves the inclusion of applications you wish to rollout in the release version created by you.
+
+1. Click **+ Add Application** button present within the release you created.
+
+    ![Figure 8: Adding Apps to Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/add-apps.jpg)
+
+2. Click the **Search and add applications** dropdown.
+
+3. Use the checkbox to add applications from your projects.
+
+    ![Figure 9: Choosing Applications](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/search-apps.gif)
+
+4. Click **Add Release Stage**.
+
+    ![Figure 10: Dividing Release in Stages](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/add-release-stage.jpg)
+
+{% hint style="info" %}
+### Importance of Release Stages
+By default, your selected applications will be set to release in one go. However, you can also release them in stages. In other words, you can decide which set of applications should be released first, subsequently which ones to release next, and the ones to release last. <br /><br /> For example, if you have a new login feature (backend) and a dashboard update (frontend), you might want to release the login feature first to ensure users can log in before seeing the updated dashboard. 
+{% endhint %}
+
+5. Use the drag-and-drop feature to move applications from one stage to another.
+
+    ![Figure 11: Rearranging the Sequence](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/release-stage-v2.gif)
+
+{% hint style="warning" %}
+The drag-and-drop feature is not meant for changing the sequence of applications within a stage. Use it solely for moving applications from one release stage to another.
+{% endhint %}
+
+6. Once you have finalized the sequence and stages, click **Save Changes**.
+
+---
+
+## Selecting Images
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to select images for selected applications.
+{% endhint %}
+
+1. Select a workflow available for your application. All the [images](../../reference/glossary.md#image) available in the selected workflow will appear.
+
+    ![Figure 12: Selecting Image from Specific Workflow](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/workflow-selection.gif)
+
+2. Click **SELECT** next to the image you wish to deploy from the list.
+
+3. Repeat the above steps for other applications you added in the release.
+
+    ![Figure 13: Repeating Steps for Other Applications](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/image-selections.gif)
+
+4. Click **Save**.
+
+{% hint style="info" %}
+### Tip
+In case you don’t have the correct images ready for any of your applications, you can partially save your changes at this point, and return once they are ready.
+{% endhint %}
+
+5. You may add release instructions for each application using the in-built Markdown editor. This can be detailed deployment notes and configuration guidelines for the team.
+
+    ![Figure 14: Adding Release Instructions](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/release-instructions-v2.gif)
+
+6. Before freezing the requirements, make sure the release order is correct, add applications if needed, and include environments in tenants (if not done already). Once you have finalized them, click **Lock Requirements**. 
+
+    ![Figure 15: Locking Requirements](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/freeze-requirements.gif)
+
+{% hint style="info" %}
+Once you lock the requirements, Devtron will prevent any unsolicited modifications to your release by anyone (including you). However, you can re-edit it by clicking **Unlock To Edit**.
+{% endhint %}
+
+---
+
+## Deploying Release
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to deploy a release.
+{% endhint %}
+
+{% hint style="info" %}
+### Prerequisite
+All your requirements need to be locked and [tenants](./tenants.md) must be configured.
+{% endhint %}
+
+This involves the deployment of the release to the specified tenant installations.
+
+1. Go to the **Rollout Release** tab.
+
+    ![Figure 16: Rollout Release Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/rollout-release.jpg)
+
+2. Your release needs to be marked as ready to proceed further. If it isn’t, you can mark it **Ready for release** from this screen.
+
+    ![Figure 17: Marking a Release as Ready](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/ready-release.gif)
+
+
+    Optionally, you can also do so by changing the status from **Draft** state to **Ready for release** within your release track. 
+
+    ![Figure 18: Alternative Way of Marking](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/ready-for-release.jpg)
+
+3. Use the checkbox to select the applications belonging to the first release stage. You may use the filters on the left-hand side to make it easier.
+
+    {% embed url="https://www.youtube.com/watch?v=HPYZ4-hhoDM" caption="First Release Stage" %}
+
+4. Click **Deploy**.
+
+    If the application workflow has pre-deployment/post-deployment stage, you get a dropdown where you can specifically trigger either pre-deployment, deployment, or post-deployment stage.
+
+    ![Figure 19: Pre/Post Deployment](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/trigger-deployment.gif)
+
+5. Once the applications from the first release stage are successfully deployed, select the applications from the subsequent release stage and deploy.
+
+    {% embed url="https://www.youtube.com/watch?v=ioGZP1CCuxI" caption="Last Release Stage" %}
+
+{% hint style="warning" %}
+An application can be deployed on the tenant in the next release stage only if other applications in the previous stage are deployed successfully on the given tenant.
+{% endhint %}
+
+Here we covered the process of performing a production installation on one tenant. Similarly, you can per
+
+---
+
+## Extras
+
+### Viewing Rollout Status
+
+You can view the status of installations under `Rollout Status`. Moreover, you can go to **Rollout History** tab to view the deployment history.
+
+![Figure 20: Checking Rollout Status](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/rollout-status-history.gif)
+
+If the applications are partially released, the release status shows `Partially released`.
+
+![Figure 21: Partial Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/partial-release.jpg)
+
+If all the applications in a release are successfully deployed, the release status shows `Completely Released`.
+
+![Figure 22: Full Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/complete-release.jpg)
+
+You can view the status directly in the release track too.
+
+![Figure 23: Alternative Way of Checking Status](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/complete-release-2.jpg)
+
+### Putting a Release on Hold
+
+If a release is put on hold, none of the applications (in any release stage) can be deployed in that release. However, deploying from [Build & Deploy page](../deploying-application/README.md) of [Applications](../applications.md) or [Application Groups](../application-groups.md) will still be possible.
+
+![Figure 24: Pausing a Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/release-onhold.gif)
+
+**When to use**:
+
+* When a release was marked as ready, but is still not ready for deployment
+* If issues are found during pre-deployment checks
+* When waiting for approval from stakeholders before proceeding
+
+**Why to use**:
+
+* To prevent the release from being deployed prematurely
+* To allow time for additional testing, review, or completion of necessary tasks
+* To ensure that all requirements and dependencies are met before deployment
+
+### Rescinding a Release
+
+When a release is rescinded, it is marked as invalid or buggy, and cannot be used for further deployments. This action ensures that that the release cannot be modified further and no applications within the rescinded release can be deployed. However, deploying from the [Build & Deploy page](../deploying-application/README.md) of [Applications](../applications.md) or [Application Groups](../application-groups.md) will still be possible.
+
+![Figure 25: Cancelling a Release](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/sdh/rescind-release.gif)
+
+**When to use**:
+
+* When a release is found to be buggy or has critical issues
+* If the release does not meet the required standards or specifications
+* When a decision is made to cancel the release entirely
+
+**Why to use**:
+
+* To ensure that faulty or incomplete software is not deployed
+* To maintain the integrity and reliability of the software environment
+* To provide a clear indication that the release is no longer valid and should not be used