From 55f371b613ccf630d73ced5e7b57323772c6f019 Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Tue, 8 Oct 2024 21:06:55 +0530 Subject: [PATCH 1/4] Rough Restructuring + Changes --- .gitbook.yaml | 3 +- docs/SUMMARY.md | 5 +- docs/user-guide/deploy-chart/README.md | 14 +- docs/user-guide/deploy-chart/chart-group.md | 95 ++++++++-- .../deploy-chart/deployment-of-charts.md | 87 ++++++--- .../deploy-chart/overview-of-charts.md | 104 ---------- .../cluster-and-environments.md | 179 ++++++++++++------ .../container-registries.md | 49 +++-- 8 files changed, 288 insertions(+), 248 deletions(-) delete mode 100644 docs/user-guide/deploy-chart/overview-of-charts.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 777f5fc9a..4a720ddca 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -128,4 +128,5 @@ redirects: usage/clusters: user-guide/resource-browser.md global-configurations/authorization/sso-login/okta: user-guide/global-configurations/authorization/sso/okta.md usage/applications/creating-application/ci-pipeline/ci-build-pre-post-plugins: user-guide/creating-application/workflow/ci-build-pre-post-plugins.md - global-configurations/custom-charts: user-guide/global-configurations/deployment-charts.md \ No newline at end of file + global-configurations/custom-charts: user-guide/global-configurations/deployment-charts.md + usage/deploy-chart/overview-of-charts: user-guide/deploy-chart/README.md \ No newline at end of file diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 136be17a3..90cb78d81 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -113,12 +113,11 @@ * [Resource Browser](user-guide/resource-browser.md) * [Resource Watcher](user-guide/resource-watcher.md) * [Charts](user-guide/deploy-chart/README.md) - * [Charts Overview](user-guide/deploy-chart/overview-of-charts.md) - * [Deploy & Observe](user-guide/deploy-chart/deployment-of-charts.md) + * [Deploy a Chart](user-guide/deploy-chart/deployment-of-charts.md) + * [Deploy a Chart Group](user-guide/deploy-chart/chart-group.md) * [Examples](user-guide/deploy-chart/examples/README.md) * [Deploying Mysql Helm Chart](user-guide/deploy-chart/examples/deploying-mysql-helm-chart.md) * [Deploying MongoDB Helm Chart](user-guide/deploy-chart/examples/deploying-mongodb-helm-chart.md) - * [Chart Group](user-guide/deploy-chart/chart-group.md) * [Security](user-guide/security-features.md) * [Security Scans](user-guide/security-features/security-scans.md) * [Security Policies](user-guide/security-features/security-policies.md) diff --git a/docs/user-guide/deploy-chart/README.md b/docs/user-guide/deploy-chart/README.md index 8c341c864..56c8856ff 100644 --- a/docs/user-guide/deploy-chart/README.md +++ b/docs/user-guide/deploy-chart/README.md @@ -1,14 +1,10 @@ -# Deploy Chart +# Chart Store -Welcome! This is the documentation for Deploying Charts. +Charts can be [deployed individually](./deployment-of-charts.md) or by creating a [group of charts](./chart-group.md) -**Parts of Documentation** +* [Create, Update, Upgrade, Deploy, and Delete Chart](deployment-of-charts.md) -[Overview of Charts](overview-of-charts.md) +* [Create Chart Group and Deploy](chart-group.md) -[Charts Create, Update, Upgrade, Deploy, Delete](deployment-of-charts.md) - -[Chart Group Create Edit And Deploy](chart-group.md) - -[Examples](examples/README.md) +* [Examples](examples/README.md) diff --git a/docs/user-guide/deploy-chart/chart-group.md b/docs/user-guide/deploy-chart/chart-group.md index ee24c4b56..1841cd2dc 100644 --- a/docs/user-guide/deploy-chart/chart-group.md +++ b/docs/user-guide/deploy-chart/chart-group.md @@ -2,40 +2,95 @@ ## Introduction -Using Devtron UI, one or more Helm charts can be grouped and deployed together with a single click. +Using the Chart Group feature of Devtron, you can group and deploy one or more Helm charts in a single click. -## 1. Create Group +--- -1. In the left pane, select `Charts`. -2. On the `Chart Store` page, select `Create Group` from the upper-right corner. +## 1. Create a Group -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-1.jpg) +1. Go to the **Chart Store** page and click **+ Create Group**. -3. In the `Create Chart Group` screen, enter `name` and `description`(optional) for the chart group, and then select `Create Group`. + ![Figure 1: Creating a Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/create-group.jpg) -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-2.jpg) +2. In the **Create Chart Group** window, give a name and description (optional) to your chart group, and then click **Create Group**. -Once you create the group, you can now select and add the charts to this chart group. + ![Figure 2: Adding Group Data](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/create-group-window.jpg) -## 2. Add Charts To Group +Once you create a group, you can now select and add charts to it. -1. To add a chart to the group, click the `+` sign at the top-right corner of a chart, and then select `Save`. +--- -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-3.jpg) +## 2. Add Charts to the Group -2. Click on `Group Detail` to see all the running instances and group details. You can also edit the chart group from here. +1. To add a chart to the group, click the `+` sign next to the chart you wish to add. -## 3.Bulk Deploy and Edit Option for Charts + ![Figure 3: Adding Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/add-chart.jpg) -You can see all the charts in the chart group in the right panel. -1. Select `Deploy to..`. + You also can add multiple copies of the same chart in the chart group as your requirements. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-4.jpg) +2. Once you have finalized the charts for your group, click **Save**. -2. In the `Deploy Selected Charts`, select the `Project` and `Deploy to Environment` values where you want to deploy the chart group. + ![Figure 4: Saving Chart Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/save-chart.jpg) -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-5.jpg) +--- -3. Select `Advanced Options` for more deploy options, such as editing the `values.yaml` or changing the `Environment` and `Project` for each chart. +## 3. Bulk Deploy and Edit Option for Charts + +1. By default, a chart group will show all the charts you added to it. However, you may choose to deploy only selected charts and deselect the rest from the chart group. + + ![Figure 5: Selecting Charts for Deployment](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/deploy-selected-charts.jpg) + +2. In the **Deploy Selected Charts** window, select the project and environment where you wish to deploy the chart group. You may use the [Advanced Options](#advanced-options) if you wish to edit the chart configurations too. + + ![Figure 6: Deploying Selected Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/deploy-chart-group-window.jpg) + +3. Click **Deploy** to initiate the deployment of the selected charts in the Chart Group. + + ![Figure 7: Deploying Chart Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/deploy-chart.jpg) + +### Advanced Options + +Before deploying your chart group, you may click **Advanced Options** to edit the chart configuration of any chart in the group. + +![Figure 8: Using Advanced Options](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/advanced-options.jpg) + +{% hint style="warning" %} +If you selected specific charts for deployment, and then if you use **Advanced Options**, you may have to select the charts again and deselect the ones you don't wish to deploy. +{% endhint %} + +![Figure 9: Editing Individual Chart Configurations](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/advanced-options-2.jpg) + +You can edit the following fields and also the YAML file of the corresponding chart. + +| Key | Description | +| :--- | :--- | +| **App name** | Name of the app | +| **Deploy to Environment** | Select the environment in which the chart has to be deployed | +| **Chart version** | Select the version of the chart to be used | +| **Values** | You can use a default value or custom value. Ensure the value that you select for the chart is compatible with the 'Chart Version' you selected. | + +After changing the configurations, select your project and click **Deploy** + +![Figure 10: Deploying Chart Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/project-selection.jpg) + +--- + +## Extras + +### Edit a Chart Group + +You can rename a chart group, remove charts from it, or add new charts to the group. To edit a chart group, click it and use the **Edit** button. + +{% embed url="https://www.youtube.com/watch?v=4bsxuUyRYTI" caption="Editing Chart Group in Devtron" %} + +You may click **Group Detail** to view the charts added to the group and check their running instances. + + +### Delete a Chart Group + +To delete a chart group, click it and use the **Delete** button. + +![Figure 11: Deleting a Chart Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/delete-chart-group.gif) + +### Checking Running Instances of Chart -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-6.jpg) diff --git a/docs/user-guide/deploy-chart/deployment-of-charts.md b/docs/user-guide/deploy-chart/deployment-of-charts.md index db1439776..ad4e0a550 100644 --- a/docs/user-guide/deploy-chart/deployment-of-charts.md +++ b/docs/user-guide/deploy-chart/deployment-of-charts.md @@ -1,80 +1,105 @@ -# Chart Operations +# Deploy a Chart ## Introduction -Discover, Create, Deploy, Update, Upgrade, Delete charts. +Discover, Configure, Deploy, Update, Upgrade, Delete charts. -## 1. Discover the chart from the Chart Store +--- + +## 1. Discover Chart from Chart Store Select the `Charts` section from the left pane, you will be landed to the `Chart Store` page. Search `nginx` or any other charts in search filter. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-1.jpg) +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/search-chart.jpg) Click on chart and it will redirect you to `Chart Details` page where you can see a number of instances deployed by using the same chart. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-2.jpg) +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/chart-details.jpg) + +--- ## 2. Configure the Chart -After selecting the version and values, click on `Deploy` +You may refer the `README.md` attached to the chart to know more about the chart configurations. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-2.jpg) -Enter the following details, to deploy chart: +Click **Configure & Deploy** and enter the following details: | Key | Description | | :--- | :--- | -| `App Name` | Name of the Chart Unique| -| `Project` | Project in which you want to deploy the chart | -| `Environment` | Environment in which you want to deploy the chart | -| `Chart Version` | Chart version | -| `Chart Value` | Latest default value or create a custom value | +| **App Name** | Unique name of the chart| +| **Project** | Select the project of the application | +| **Deploy to Environment** | Environment in which you want to deploy the chart | +| **Chart Version** | Shows all available versions of the chart. Select the version of the chart to be used. | +| **Chart Value** | Shows the latest default value or you may [create a custom value](#create-a-custom-value) | -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-3.jpg) +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/values-field.jpg) -you can choose any chart version, values and update it on values.yaml +You can choose your preferred chart version, chart value, and update the values.yaml using the editor on the right. -Click on `Deploy` to deploy the Chart +Click **Deploy** to deploy the chart. -## 3. Status of Deployment +--- -After clicking on `Deploy` you will land on a page that shows the status of the deployment of the Chart. +## 3. Check Deployment Status + +After clicking the **Deploy** button, you will land on the **App Details** page that shows the status of the chart deployment. The status of the chart should be `Healthy`. It might take a few seconds after initiating the deployment of the chart. -In case the status of the deployment is `Degraded` or takes a long time to get deployed, click on `Details` in `Application Status` section on the same page or check the logs of the pods to debug the issue. +In case the status of the deployment shows `Degraded` or if takes a long time to get deployed, click **Details** in `Application Status` section on the same page or check the logs of the pods to debug the issue. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-4-2.jpg) +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/chart-app-details.jpg) 1. Shows status of deployed chart. 2. Shows the controller service accounts being used. -3. Clicking on `values` will land you on the page where you can update, upgrade or delete chart. +3. In the **Configure** tab, you can update, upgrade, or delete your chart instance. -4. Clicking on `View Chart` will land you to the page where you can see all the running instances of this chart. +4. From the `Chart used` section you can go to the charts page where you can see all the running instances of this chart. -To see deployment history of Helm application, click on `Deployment history` from `App details` page. +5. Click the **Deployment history** tab to view the deployment history of Helm application and values.yaml corresponding to the deployment. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/hyperion/user-guide/deploy-charts/overview-of-charts/overview-of-charts-9.jpg) + ![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/chart-deployment-history.jpg) +--- ## 4. Update or Upgrade Chart -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-5-2.jpg) +For update, you can change its `Chart Version` or `values.yaml` and then click **Update And Deploy**. -For update you can change its `chart version` or `values.yaml` and then click on `Update And Deploy`. + ![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/update-chart.jpg) -For upgrade click on `Repo/Chart` field and search any chart name like `nginx-ingress` and change values corresponding to that chart and Click on `Update And Deploy`. +For upgrade, click on `Helm Chart` field, search a chart name, change its values corresponding, and click **Update And Deploy**. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-6-2.jpg) + ![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/upgrade-chart.jpg) +After an update or upgrade, you will land on the **App Details** page where you can check the pods and service name. -After an update or upgrade you again will land on `App Detail` page, where you can check pods and service name. + ![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-status.jpg) -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-7-2.jpg) +--- ## 5. Chart Details and Delete Charts -By clicking on `View Chart` in `Chart Used` section on `App Details` page, it will redirect you to `Chart Details` page where you can see number of instances installed by this chart and also you can delete the chart instance from here. +Clicking on `View Chart` in `Chart Used` section in the **App Details** page will redirect you to the `Chart Details` page where you can see the number of instances installed by that chart along with an option to delete those chart instances too. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/delete-chart-instance.jpg) + +--- + +## Extras + +### Create a Custom Value + +You can use the default values or create custom value by clicking on `Create Custom`. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-7.jpg) + +You can name your Custom Value, select the Chart Version and change the configurations in YAML file. +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-8-2.jpg) -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-8-2.jpg) +Click on `Save Template` to save the configurations. diff --git a/docs/user-guide/deploy-chart/overview-of-charts.md b/docs/user-guide/deploy-chart/overview-of-charts.md deleted file mode 100644 index 38b97e2e9..000000000 --- a/docs/user-guide/deploy-chart/overview-of-charts.md +++ /dev/null @@ -1,104 +0,0 @@ -# Overview Of Charts - -## Deploying Charts - -Charts can be deployed individually or by creating a group of Charts. Both methods are mentioned here. - -### Deploying Chart - -To deploy any chart or chart group, visit the `Charts` section from the left panel and then select the chart that you want to use. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-1.jpg) - -Click on `README.md` to get more ideas about the configurations of the chart. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-2.jpg) - -Select the Chart Version that you want to use and Chart Value, you can either use the Default Values or Custom Values. - -To know about Custom Values, Click On: [Custom Values](overview-of-charts.md#custom-values) - -The configuration values can be edited in the section given below Chart Version. - -| Key | Description | -| :--- | :--- | -| `App Name` | Name of the app | -| `Project` | Project of the app | -| `Environment` | Environment of the app to be deployed in | -| `Chart Version` | Version of the chart to be used | - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-3.jpg) - -Readme.md present on the left can be used by the user to set configuration values. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-4.jpg) - -Click on `Deploy Chart` to deploy the chart. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-5-2.jpg) - -Click on `App Details` to see the status and details of the deployed chart and click on `Values` to reconfigure the deployment. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-6-2.jpg) - -Configuration values can be edited over here by the help of Readme.md. - -Click on `Update And Deploy` to update new settings. -You can also see deployment history of Helm application and values.yaml corresponding to the deployment by clicking on `Deployment history`. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-9-2.jpg) - -### Custom Values - -You can use the default values or create Custom value by clicking on `Create Custom`. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-7.jpg) - -You can name your Custom Value, select the Chart Version and change the configurations in YAML file. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-8-2.jpg) - -Click on `Save Template` to save the configurations. - -### Deploying Chart Groups - -You can deploy multiple applications and work with them simultaneously by creating `Chart Group`. -To create chart group click on `Create Group`. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-1.jpg) - -Add the `Group Name` and `Description`(optional), and select `Create Group`. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-2.jpg) - -You can select the Charts that you want to add to your Chart Group by clicking on '+' sign. You also can add multiple copies of the same chart in the chart group according to your requirements. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/chart-group-3.jpg) - -Select the `Version` and `Values` for your charts. -You can use Default Values or the Custom Values, just make sure the value that you select for the chart is compatible with the version of the chart that you are using. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-9.jpg) - -To edit the chart configuration, Click on `Edit`. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-10.jpg) - -You can `Add` more charts or `Delete` charts from your existing Chart Group. -After making any changes, click on `Save` to save changes for the Chart Group. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-11.jpg) - -If you wish to edit the chart configuration of any chart in the chart group, click on that Chart and edit the configurations in YAML file. You also can edit the `App Name`, `Chart Version`, `Values`, `Deploy Environment` and the YAML file from here. - -| Key | Description | -| :--- | :--- | -| `App Name` | Name of the app | -| `Project` | Name of Project in which app has to be created | -| `Environment` | Name of the Environment in which app has to be deployed | -| `Chart Version` | Select the Version of the chart to be used | - -After changing the configurations, click on `Deploy` to initiate the deployment of the chart in the Chart Group. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/overview-of-charts-12.jpg) - diff --git a/docs/user-guide/global-configurations/cluster-and-environments.md b/docs/user-guide/global-configurations/cluster-and-environments.md index 76618baaa..1e9c6b784 100644 --- a/docs/user-guide/global-configurations/cluster-and-environments.md +++ b/docs/user-guide/global-configurations/cluster-and-environments.md @@ -1,68 +1,52 @@ # Clusters and Environments -You can add your existing Kubernetes clusters and environments on the `Clusters and Environments` section. You must have a [super admin](./authorization/user-access.md#assign-super-admin-permissions) access to add a cluster. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/cluster-and-environments.png) - -## Add Cluster: +## Introduction -To add cluster, go to the `Clusters & Environments` section of `Global Configurations`. Click **Add cluster**. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-clusters.png) - -### Add Clusters Using Server URL & Bearer Token +You can add your existing Kubernetes clusters and environments on the `Clusters and Environments` section. You must have a [super admin](./authorization/user-access.md#assign-super-admin-permissions) access to add a cluster. +![Figure 1: Clusters and Environments in Devtron](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/cluster-and-environments.jpg) -To add a Kubernetes cluster on Devtron using `server url` and the `bearer token`, provide the information in the following fields: +Refer the following: -| Field | Description | -| :--- | :--- | -| `Name` | Enter a name of your cluster. | -| `Server URL` | Server URL of a cluster.
Note: We recommended to use a [self-hosted URL](#benefits-of-self-hosted-url) instead of cloud hosted URL.
| -| `Bearer Token` | Bearer token of a cluster. | +* [Add Kubernetes Cluster](#add-kubernetes-cluster) +* [Add Isolated Cluster](#add-isolated-cluster) -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-cluster-cred.jpg) +--- -### Get Cluster Credentials +## Add Kubernetes Cluster ->**Prerequisites:** `kubectl` must be installed on the bastion. +Use this option to add a managed or on-premise Kubernetes cluster. -**Note**: We recommend to use a self-hosted URL instead of cloud hosted URL. Refer the benefits of [self-hosted URL](#benefits-of-self-hosted-url). +1. Go to **Global Configurations** → **Clusters & Environments**. -You can get the **`Server URL`** & **`Bearer Token`** by running the following command depending on the cluster provider: +2. Click the **Add Cluster** button on the top-right corner. -{% tabs %} -{% tab title="k8s Cluster Providers" %} -If you are using EKS, AKS, GKE, Kops, Digital Ocean managed Kubernetes, run the following command to generate the server URL and bearer token: -```bash -curl -O https://raw.githubusercontent.com/devtron-labs/utilities/main/kubeconfig-exporter/kubernetes_export_sa.sh && bash kubernetes_export_sa.sh cd-user devtroncd -``` -{% endtab %} -{% tab title="Microk8s Cluster" %} -If you are using a **`microk8s cluster`**, run the following command to generate the server URL and bearer token: + ![Figure 2: Adding a Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-clusters.jpg) -```bash -curl -O https://raw.githubusercontent.com/devtron-labs/utilities/main/kubeconfig-exporter/kubernetes_export_sa.sh && sed -i 's/kubectl/microk8s kubectl/g' \ -kubernetes_export_sa.sh && bash kubernetes_export_sa.sh cd-user \ -devtroncd -``` -{% endtab %} -{% endtabs %} +3. Click **Add Kubernetes Cluster**. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/generate-cluster-credentials.png) + ![Figure 3: Adding a Kubernetes Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-clusters.jpg) +You can choose to add your Kubernetes cluster using either of the following: + * [Server URL & Bearer Token](#add-clusters-using-server-url--bearer-token) + * [Kubeconfig](#add-clusters-using-kubeconfig) +### Add Clusters Using Server URL & Bearer Token -### Benefits of Self-hosted URL +{% hint style="info" %} +### Note +Refer [Get Cluster Credentials](#get-cluster-credentials) to know the process of getting Server URL and bearer token. +{% endhint %} -* Disaster Recovery: - * It is not possible to edit the server URL of a cloud specific provider. If you're using an EKS URL (e.g.` *****.eu-west-1.elb.amazonaws.com`), it will be a tedious task to add a new cluster and migrate all the services one by one. - * But in case of using a self-hosted URL (e.g. `clear.example.com`), you can just point to the new cluster's server URL in DNS manager and update the new cluster token and sync all the deployments. +To add a Kubernetes cluster on Devtron using a Server URL and bearer token, provide the information in the following fields: -* Easy Cluster Migrations: - * In case of managed Kubernetes clusters (like EKS, AKS, GKE etc) which is a cloud provider specific, migrating your cluster from one provider to another will result in waste of time and effort. - * On the other hand, migration for a self-hosted URL is easy as the URL is of single hosted domain independent of the cloud provider. +| Field | Description | +| :--- | :--- | +| `Name` | Enter a name of your cluster | +| `Server URL` | Server URL of a cluster.
Note: We recommended to use a [self-hosted URL](#benefits-of-self-hosted-url) instead of cloud hosted URL.
| +| `Bearer Token` | Bearer token of a cluster | +![Figure 4: Entering Cluster Credentials](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-cluster-cred-v2.jpg) ### Add Clusters Using Kubeconfig @@ -76,23 +60,29 @@ To add clusters using kubeconfig, follow these steps: 4. Afterward, click on the `Get cluster` button. This action will display the cluster details alongside the kubeconfig. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-cluster-kubeconfig.jpg) + ![Figure 5: Using Kubeconfig](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-cluster-kubeconfig.jpg) 5. Select the desired cluster and click on `Save` to successfully add the cluster to Devtron. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/kubeconfig-save-cluster.jpg) + ![Figure 6: Saving Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/kubeconfig-save-cluster.jpg) +{% hint style="info" %} +### Note +Please ensure that the kubeconfig file you use has `admin permissions`. It is crucial for Devtron to have the necessary administrative privileges; otherwise, it may encounter failures or disruptions during deployments and other operations. Admin permission is essential to ensure the smooth functioning of Devtron and to prevent any potential issues that may arise due to insufficient privileges. +{% endhint %} -**Note:** Please ensure that the kubeconfig file you use has `admin permissions`. It is crucial for Devtron to have the necessary administrative privileges; otherwise, it may encounter failures or disruptions during deployments and other operations. Admin permission is essential to ensure the smooth functioning of Devtron and to prevent any potential issues that may arise due to insufficient privileges. ### Configure Prometheus (Enable Applications Metrics) If you want to see application metrics against the applications deployed in the cluster, Prometheus must be deployed in the cluster. Prometheus is a powerful tool to provide graphical insight into your application behavior. ->**Note:** Make sure that you install `Monitoring (Grafana)` from the `Devtron Stack Manager` to configure prometheus. +{% hint style="warning" %} +### Note +Make sure that you install `Monitoring (Grafana)` from the `Devtron Stack Manager` to configure prometheus. If you do not install `Monitoring (Grafana)`, then the option to configure prometheus will not be available. +{% endhint %} -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/enable-app-metrics.png) +![Figure 7: Enabling App Metrics](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/enable-app-metrics.png) Enable the application metrics to configure prometheus and provide the information in the following fields: @@ -108,15 +98,45 @@ Now, click `Save Cluster` to save your cluster on Devtron. Your Kubernetes cluster gets mapped with Devtron when you save the cluster configurations. Now, the Devtron agent must be installed on the added cluster so that you can deploy your applications on that cluster. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/install-devtron-agent.png) +![Figure 8: Installing Devtron Agent](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/install-devtron-agent.png) When the Devtron agent starts installing, click `Details` to check the installation status. -![Install Devtron Agent](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/gc-cluster-agents.jpg) +![Figure 9: Running Agent](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/gc-cluster-agents.jpg) A new window pops up displaying all the details about the Devtron agent. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/cluster_gc5.jpg) +![Figure 10: Agent Details](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/cluster_gc5.jpg) + +--- + +## Add Isolated Cluster + +Deploying to an isolated environment will generate and push the helm package to your chart repository (if need be). Further, this package can be used to deploy to an air-gapped cluster via third party tools or manually. + +1. Go to **Global Configurations** → **Clusters & Environments**. + +2. Click the **Add Cluster** button on the top-right corner. + + ![Figure 11: Adding a Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/add-cluster.jpg) + +3. Select **Add Isolated Cluster** (2nd option). + + ![Figure 12: Adding an Isolated Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/adding-cluster.jpg) + +4. Add a cluster name (let's say, *demo*) and click **Save Cluster**. + +5. Since the newly created cluster has no environments, click **Add Environment**. + +6. Add an environment name and namespace. Click **Save**. + + ![Figure 13: Adding an Environment](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/adding-env.jpg) + +You have successfully configured an isolated cluster. + +![Figure 14: Isolated Cluster Successfully Created](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/added-env.jpg) + +--- ## Add Environment @@ -130,11 +150,12 @@ A new environment window pops up. | `Enter Namespace` | Enter a namespace corresponding to your environment.
**Note**: If this namespace does not already exist in your cluster, Devtron will create it. If it exists already, Devtron will map the environment to the existing namespace.
| | `Environment Type` | Select your environment type: Note: Devtron shows deployment metrics (DORA metrics) for environments tagged as `Production` only. | -Click `Save` and your environment will be created. +Click **Save** and your environment will be created. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/gc-cluster-add-environment.jpg) +![Figure 15: Adding an Environment in Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/gc-cluster-add-environment.jpg) +--- ## Update Environment @@ -142,3 +163,51 @@ Click `Save` and your environment will be created. * You can change `Production` and `Non-Production` options only. * You cannot change the `Environment Name` and `Namespace Name`. * Make sure to click **Update** to update your environment. + +--- + +## Extras + +### Get Cluster Credentials + +{% hint style="info" %} +### Prerequisites +`kubectl` must be installed on the bastion. +{% endhint %} + +{% hint style="info" %} +### Note +We recommend to use a self-hosted URL instead of cloud hosted URL. Refer the benefits of [self-hosted URL](#benefits-of-self-hosted-url). +{% endhint %} + +You can get the **Server URL** and **Bearer Token** by running the following command depending on the cluster provider: + +{% tabs %} +{% tab title="k8s Cluster Providers" %} +If you are using EKS, AKS, GKE, Kops, Digital Ocean managed Kubernetes, run the following command to generate the server URL and bearer token: +```bash +curl -O https://raw.githubusercontent.com/devtron-labs/utilities/main/kubeconfig-exporter/kubernetes_export_sa.sh && bash kubernetes_export_sa.sh cd-user devtroncd +``` +{% endtab %} +{% tab title="Microk8s Cluster" %} +If you are using a **`microk8s cluster`**, run the following command to generate the server URL and bearer token: + +```bash +curl -O https://raw.githubusercontent.com/devtron-labs/utilities/main/kubeconfig-exporter/kubernetes_export_sa.sh && sed -i 's/kubectl/microk8s kubectl/g' \ +kubernetes_export_sa.sh && bash kubernetes_export_sa.sh cd-user \ +devtroncd +``` +{% endtab %} +{% endtabs %} + +![Figure 16: Generating Cluster Credentials](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/generate-cluster-credentials.png) + +### Benefits of Self-hosted URL + +* Disaster Recovery: + * It is not possible to edit the server URL of a cloud specific provider. If you're using an EKS URL (e.g.` *****.eu-west-1.elb.amazonaws.com`), it will be a tedious task to add a new cluster and migrate all the services one by one. + * But in case of using a self-hosted URL (e.g. `clear.example.com`), you can just point to the new cluster's server URL in DNS manager and update the new cluster token and sync all the deployments. + +* Easy Cluster Migrations: + * In case of managed Kubernetes clusters (like EKS, AKS, GKE etc) which is a cloud provider specific, migrating your cluster from one provider to another will result in waste of time and effort. + * On the other hand, migration for a self-hosted URL is easy as the URL is of single hosted domain independent of the cloud provider. \ No newline at end of file diff --git a/docs/user-guide/global-configurations/container-registries.md b/docs/user-guide/global-configurations/container-registries.md index 48ed1ff3f..61d10eb4e 100644 --- a/docs/user-guide/global-configurations/container-registries.md +++ b/docs/user-guide/global-configurations/container-registries.md @@ -1,12 +1,17 @@ # Container/OCI Registry +## Introduction + While [container registries](../../reference/glossary.md#container-registry) are typically used for storing [images](../../reference/glossary.md#image) built by the CI Pipeline, an OCI registry can store container images as well as other artifacts such as [helm charts](../../reference/glossary.md#helm-charts-packages). In other words, all container registries are OCI registries, but not all OCI registries are container registries. You can configure a container registry using any registry provider of your choice. It allows you to build, deploy, and manage your container images or charts with easy-to-use UI. +--- ## Add Container Registry +### Steps + 1. From the left sidebar, go to **Global Configurations** → **Container/OCI Registry**. ![Figure 1: Container/OCI Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/add-registry.jpg) @@ -29,12 +34,27 @@ You can configure a container registry using any registry provider of your choic | **Registry URL** | Provide the URL of your registry in case it doesn't come prefilled (do not include `oci://`, `http://`, or `/https://` in the URL) | | **Authentication Type** | The credential input fields may differ depending on the registry provider, check [Registry Providers](#supported-registry-providers) | | **Push container images** | Tick this checkbox if you wish to use the repository to push container images. This comes selected by default and you may untick it if you don't intend to push container images after a CI build. If you wish to to use the same repository to pull container images too, read [Registry Credential Access](#registry-credential-access). | - | **Push helm packages** | Tick this checkbox if you wish to push helm charts to your registry | - | **Use as chart repository** | Tick this checkbox if you want Devtron to pull helm charts from your registry and display them on its chart store. Also, you will have to provide a list of repositories (present within your registry) for Devtron to successfully pull the helm charts. | + | **Push helm packages** | Tick this checkbox if you wish to [push helm charts to your registry](#push-helm-packages) | + | **Use as chart repository** | Tick this checkbox if you want Devtron to [pull helm charts from your registry and display them on chart store](#use-as-chart-repository). Also, you will have to provide a list of repositories (present within your registry) for Devtron to successfully pull the helm charts. | | **Set as default registry** | Tick this checkbox to set your registry as the default registry hub for your images or artifacts | 6. Click **Save**. +### Push Helm Packages + +Devtron supports the pushing of helm charts to your OCI registry. + +This is possible through isolated clusters that facilitate virtual deployments. In other words, it generates a helm package that you can use to deploy in air-gapped clusters not connected to Devtron. + +{% hint style="info" %} +Devtron doesn't support pushing helm packages to [chart repositories](../global-configurations/chart-repo.md) +{% endhint %} + + + +### Use as Chart Repository + +--- ## Supported Registry Providers @@ -125,6 +145,7 @@ Provide below information if you select the registry type as `Other`. You can use any registry which can be authenticated using `docker login -u -p `. However these registries might provide a more secured way for authentication, which we will support later. {% endhint %} +--- ## Registry Credential Access @@ -181,26 +202,4 @@ You have successfully set your Docker credentials in the cluster as a Secret cal Typing secrets on the command line may store them in your shell history unprotected, and those secrets might also be visible to other users on your PC during the time when kubectl is running. {% endhint %} -Enter the Secret name in the field and click **Save**. - - - - - - - - - - - - - - - - - - - - - - +Enter the Secret name in the field and click **Save**. \ No newline at end of file From 949329bb2a5ac9571e11b835a96a191eff85b95d Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Wed, 9 Oct 2024 13:51:38 +0530 Subject: [PATCH 2/4] Rewrote for OCI pull and push --- .../workflow/cd-pipeline.md | 9 +++ docs/user-guide/deploy-chart/README.md | 67 ++++++++++++++++- docs/user-guide/deploy-chart/chart-group.md | 2 - .../global-configurations/chart-repo.md | 6 +- .../cluster-and-environments.md | 2 +- .../container-registries.md | 34 +++++++-- docs/user-guide/use-cases/oci-pull.md | 73 ------------------- 7 files changed, 106 insertions(+), 87 deletions(-) delete mode 100644 docs/user-guide/use-cases/oci-pull.md diff --git a/docs/user-guide/creating-application/workflow/cd-pipeline.md b/docs/user-guide/creating-application/workflow/cd-pipeline.md index 08ad07e7a..0d71a4259 100644 --- a/docs/user-guide/creating-application/workflow/cd-pipeline.md +++ b/docs/user-guide/creating-application/workflow/cd-pipeline.md @@ -29,6 +29,15 @@ This section expects four inputs from you: | Trigger | When to execute the deployment pipeline | **Automatic**: Deployment triggers automatically when a new image completes the previous stage (build pipeline or another deployment pipeline)
**Manual**: Deployment is not initiated automatically. You can trigger deployment with a desired image. | | Deployment Approach | How to deploy the application | **Helm** or **GitOps**
Refer [GitOps](../../global-configurations/gitops.md) | +{% hint style="info" %} +### Deploying to an Isolated Environment? +In case you choose an [isolated cluster environment](../../global-configurations/cluster-and-environments.md#add-isolated-cluster) for deployment, you get additional options to choose from ([check snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/create-cd2.jpg)): + * **Do not push** - A link to download the helm package will be available when you trigger a deployment. However, it will not push the helm package to the OCI registry. + * **Push to registry** - This will generate and [push the helm package to the OCI registry](../../global-configurations/container-registries.md#push-helm-packages). Upon selecting this option, you will get two more fields: + * **Registry** - Choose the OCI registry to which the helm chart package must be pushed. Only those registries that have `Push helm packages` enabled will be shown in the dropdown. + * **Repository** - Write the repository name in the format `username/repo-name`. You can find the username from your registry provider account. +{% endhint %} + ### Deployment Strategy Devtron supports multiple deployment strategies depending on the [deployment chart type](../../creating-application/deployment-template.md#select-chart-from-default-charts). diff --git a/docs/user-guide/deploy-chart/README.md b/docs/user-guide/deploy-chart/README.md index 56c8856ff..306943155 100644 --- a/docs/user-guide/deploy-chart/README.md +++ b/docs/user-guide/deploy-chart/README.md @@ -1,10 +1,69 @@ # Chart Store -Charts can be [deployed individually](./deployment-of-charts.md) or by creating a [group of charts](./chart-group.md) +## Introduction + +Devtron makes it easier for you to populate your charts from multiple sources to the [chart store](../../reference/glossary.md#chart-store). These sources are: +* [Chart Respository](../global-configurations/chart-repo.md) +* [OCI Registry](../global-configurations/container-registries.md#use-as-chart-repository) + +![Figure 1: Chart Store](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/chart-store-main.jpg) + +### Prerequisites + +* Helm Chart(s) +* Chart Repository added to Devtron +* OCI-Compliant Registry (e.g. Docker Hub and [many more](../global-configurations/container-registries.md#supported-registry-providers)) with + +--- + +## Populating your Charts to the Chart Store + +1. From the left sidebar, go to **Chart Store**. + +2. You can find your chart(s) either by using the search bar or by selecting your chart source. + + ![Figure 2: Searching your Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-search.jpg) + +You have successfully pulled your charts to the chart store. + +![Figure 3: Uploaded Helm Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-list.jpg) + +### Unable to find your Charts? + +Deprecated charts won't show up in the Chart Store unless you enable the **Show deprecated charts** filter as shown below + +![Figure 4: Checking Deprecated Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/deprecated.jpg) + +Or, you may try performing a resync as shown below + +![Figure 5: Performing a Resync](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-sync.jpg) + +--- + + +## Removing your Chart from the Chart Store + +{% hint style="warning" %} +### Who Can Perform This Action? +You cannot remove a chart from the Chart Store if the source was a [chart repository](../global-configurations/chart-repo.md). In that case, deleting the chart repository from Devtron will work; however, it will remove all the charts associated with that respository from the Chart store. +{% endhint %} + +1. Go to your OCI registry settings in Devtron. + +2. In the **List of repositories** field, remove the unwanted chart repo. + + ![Figure 6: Removing a Chart Repo](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/remove-chart-repo.jpg) + +3. Click **Update**. + +The removed chart would no longer appear in the Chart Store. + +{% hint style="info" %} +Deleting a chart repo from your OCI registry will not lead to the removal of chart from the Chart Store +{% endhint %} + + -* [Create, Update, Upgrade, Deploy, and Delete Chart](deployment-of-charts.md) -* [Create Chart Group and Deploy](chart-group.md) -* [Examples](examples/README.md) diff --git a/docs/user-guide/deploy-chart/chart-group.md b/docs/user-guide/deploy-chart/chart-group.md index 1841cd2dc..68ed79232 100644 --- a/docs/user-guide/deploy-chart/chart-group.md +++ b/docs/user-guide/deploy-chart/chart-group.md @@ -92,5 +92,3 @@ To delete a chart group, click it and use the **Delete** button. ![Figure 11: Deleting a Chart Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/delete-chart-group.gif) -### Checking Running Instances of Chart - diff --git a/docs/user-guide/global-configurations/chart-repo.md b/docs/user-guide/global-configurations/chart-repo.md index 1a2c12815..4426db659 100644 --- a/docs/user-guide/global-configurations/chart-repo.md +++ b/docs/user-guide/global-configurations/chart-repo.md @@ -1,9 +1,11 @@ # Chart Repository -You can add more chart repositories to Devtron. Once added, they will be available in the `All Charts` section of the [Chart Store](../deploy-chart/overview-of-charts.md). +You can add more chart repositories to Devtron. Once added, they will be available in the `All Charts` section of the [Chart Store](../deploy-chart/README.md). **Note**: After the successful installation of Devtron, click `Refetch Charts` to sync and download all the default charts listed on the dashboard. +--- + ## Add Chart Repository To add chart repository, go to the `Chart Repositories` section of `Global Configurations`. Click **Add repository**. @@ -19,7 +21,7 @@ Provide below information in the following fields: | **Name** | Provide a `Name` of your chart repository. This name is added as prefix to the name of the chart in the listing on the helm chart section of application. | | **URL** | This is the URL of your chart repository. E.g. https://charts.bitnami.com/bitnami | - +--- ## Update Chart Repository diff --git a/docs/user-guide/global-configurations/cluster-and-environments.md b/docs/user-guide/global-configurations/cluster-and-environments.md index 1e9c6b784..55a467de2 100644 --- a/docs/user-guide/global-configurations/cluster-and-environments.md +++ b/docs/user-guide/global-configurations/cluster-and-environments.md @@ -25,7 +25,7 @@ Use this option to add a managed or on-premise Kubernetes cluster. 3. Click **Add Kubernetes Cluster**. - ![Figure 3: Adding a Kubernetes Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-clusters.jpg) + ![Figure 3: Adding a Kubernetes Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/add-kubernetes-cluster.jpg) You can choose to add your Kubernetes cluster using either of the following: * [Server URL & Bearer Token](#add-clusters-using-server-url--bearer-token) diff --git a/docs/user-guide/global-configurations/container-registries.md b/docs/user-guide/global-configurations/container-registries.md index 61d10eb4e..26282e2ce 100644 --- a/docs/user-guide/global-configurations/container-registries.md +++ b/docs/user-guide/global-configurations/container-registries.md @@ -42,17 +42,41 @@ You can configure a container registry using any registry provider of your choic ### Push Helm Packages +{% hint style="info" %} +### Prerequisite +OCI registry with `Push helm packages` option enabled. +{% endhint %} + Devtron supports the pushing of helm charts to your OCI registry. -This is possible through isolated clusters that facilitate virtual deployments. In other words, it generates a helm package that you can use to deploy in air-gapped clusters not connected to Devtron. +This is possible through [isolated clusters](../global-configurations/cluster-and-environments.md#add-isolated-cluster) that facilitate virtual deployments. In other words, it generates a helm package that you can use to deploy in air-gapped clusters not connected to Devtron. -{% hint style="info" %} +If you have [configured your CD pipeline](../creating-application/workflow/cd-pipeline.md#deploying-to-an-isolated-environment) to push the helm package to your OCI registry, you can view the pushed helm package in your registry as shown below: + +![Figure 3a: OCI Registry Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/pushed-artifacts.jpg) + +![Figure 3b: Pushed Helm Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/helm-chart.jpg) + +{% hint style="warning" %} Devtron doesn't support pushing helm packages to [chart repositories](../global-configurations/chart-repo.md) {% endhint %} +### Use as Chart Repository +{% hint style="info" %} +### Prerequisite +OCI registry with `Use as chart repository` option enabled. +{% endhint %} -### Use as Chart Repository +Unlike Helm repos, OCI registries do not have an index file to discover all the charts. Devtron supports the pulling of helm charts from your OCI registry and display them on your [chart store](../deploy-chart/README.md). + +{% embed url="https://www.youtube.com/watch?v=9imC5MMz9gs" caption="Pulling Charts from an OCI Registry to Devtron" %} + +Search your OCI registry in the list, and click it. + +In the **List of repositories**, add your chart repo(s). The format should be `username/chartname`. You can find the username from your registry provider account. + +![Figure 4: Adding Chart Repos](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/container-config.jpg) --- @@ -173,14 +197,14 @@ If you select **Use Registry Credentials**, the clusters will be auto-injected w Click **Save**. -![Figure 3: Using Registry Credentials](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/use-registry-credentials-1.jpg) +![Figure 5: Using Registry Credentials](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/use-registry-credentials-1.jpg) ### Specify Image Pull Secret You can create a Secret by providing credentials on the command line. -![Figure 4: Using Image Pull Secret](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/specify-image-pull-secret-1.jpg) +![Figure 6: Using Image Pull Secret](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/specify-image-pull-secret-1.jpg) Create this Secret and name it `regcred` (let's say): diff --git a/docs/user-guide/use-cases/oci-pull.md b/docs/user-guide/use-cases/oci-pull.md deleted file mode 100644 index d62cc0a75..000000000 --- a/docs/user-guide/use-cases/oci-pull.md +++ /dev/null @@ -1,73 +0,0 @@ -# Pull Helm Charts from OCI Registry - -## Introduction - -Devtron supports the installation of [Helm charts](../../reference/glossary.md#helm-chartspackages) from both: Helm [repos](../../reference/glossary.md#repo) and [Container/OCI registries](../../reference/glossary.md#containeroci-registry). Unlike Helm repos, OCI registries do not have an index file to discover all the charts. However, Devtron makes it easier for you to populate your charts from multiple sources to the [chart store](../../reference/glossary.md#chart-store). - -**Prerequisites** - -* Helm Chart(s) -* OCI-compliant Registry (e.g. Docker Hub and [many more](../global-configurations/container-registries.md#supported-registry-providers)) - -You must [add your OCI registry](../global-configurations/container-registries.md) to Devtron with the `Use as chart repository` option enabled. - ---- - -## Tutorial - -{% embed url="https://www.youtube.com/watch?v=9imC5MMz9gs" caption="Pulling Charts from an OCI Registry to Devtron" %} - ---- - -## Populating your Charts to the Chart Store - -1. Go to **Global Configurations** → **Container/OCI Registry**. - -2. Search your OCI registry in the list, and click it. - -3. In the **List of repositories**, add the chart repo(s). The format should be `username/chartname`. You can find the username from your registry provider account. - - ![Figure 1: Adding Chart Repos](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/container-config.jpg) - -4. Click **Save** or **Update**. - -5. From the left sidebar, go to **Chart Store**. - -6. You can find your chart(s) either by using the search bar or by selecting your chart source. - - ![Figure 2: Searching your Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-search.jpg) - -You have successfully pulled your charts to the chart store. - -![Figure 3: Uploaded Helm Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-list.jpg) - -### Unable to find your Charts? - -Deprecated charts won't show up in the Chart Store unless you enable the **Show deprecated charts** filter as shown below - -![Figure 4: Checking Deprecated Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/deprecated.jpg) - -Or, you may try performing a resync as shown below - -![Figure 5: Performing a Resync](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-sync.jpg) - ---- - - -## Removing your Chart from the Chart Store - -1. Go to your OCI registry settings in Devtron. - -2. In the **List of repositories** field, remove the unwanted chart repo. - - ![Figure 6: Removing a Chart Repo](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/remove-chart-repo.jpg) - -3. Click **Update**. - -The removed chart would no longer appear in the Chart Store. - -{% hint style="info" %} -Deleting a chart repo from your OCI registry will not lead to the removal of chart from the Chart Store -{% endhint %} - - From c3b0d80dbd545220c3d78ca9871b2d2fd6f6ca4b Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Wed, 9 Oct 2024 16:49:23 +0530 Subject: [PATCH 3/4] Added Airgapped Usecase --- docs/SUMMARY.md | 2 +- .../workflow/cd-pipeline.md | 8 ++-- docs/user-guide/deploy-chart/README.md | 14 +++---- docs/user-guide/deploy-chart/chart-group.md | 4 +- .../cluster-and-environments.md | 2 +- .../container-registries.md | 23 ++++++----- docs/user-guide/use-cases/README.md | 2 + .../use-cases/airgapped-app-deployment.md | 40 +++++++++++++++++++ 8 files changed, 67 insertions(+), 28 deletions(-) create mode 100644 docs/user-guide/use-cases/airgapped-app-deployment.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 90cb78d81..8381702e2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -164,7 +164,7 @@ * [Connect SpringBoot with Mysql Database](user-guide/use-cases/connect-springboot-with-mysql-database.md) * [Connect Expressjs With Mongodb Database](user-guide/use-cases/connect-expressjs-with-mongodb-database.md) * [Connect Django With Mysql Database](user-guide/use-cases/connect-django-with-mysql-database.md) - * [Pull Helm Charts from OCI Registry](user-guide/use-cases/oci-pull.md) + * [Deploying Software on Air-gapped Environment](user-guide/use-cases/airgapped-app-deployment.md) * [Telemetry Overview](user-guide/telemetry.md) * [Devtron on Graviton](reference/graviton.md) * [Release Notes](https://github.com/devtron-labs/devtron/releases) diff --git a/docs/user-guide/creating-application/workflow/cd-pipeline.md b/docs/user-guide/creating-application/workflow/cd-pipeline.md index 0d71a4259..924d301b2 100644 --- a/docs/user-guide/creating-application/workflow/cd-pipeline.md +++ b/docs/user-guide/creating-application/workflow/cd-pipeline.md @@ -24,18 +24,18 @@ This section expects four inputs from you: | Setting | Description | Options | | ----------- | ---------------------------------------------------------- | ------------------------- | -| Environment | Select the environment where you want to deploy your application | (List of available environments) | +| Environment | Select the environment where you want to deploy your application. | (List of available environments) | | Namespace | Automatically populated based on the selected environment | Not Applicable | | Trigger | When to execute the deployment pipeline | **Automatic**: Deployment triggers automatically when a new image completes the previous stage (build pipeline or another deployment pipeline)
**Manual**: Deployment is not initiated automatically. You can trigger deployment with a desired image. | | Deployment Approach | How to deploy the application | **Helm** or **GitOps**
Refer [GitOps](../../global-configurations/gitops.md) | {% hint style="info" %} ### Deploying to an Isolated Environment? -In case you choose an [isolated cluster environment](../../global-configurations/cluster-and-environments.md#add-isolated-cluster) for deployment, you get additional options to choose from ([check snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/create-cd2.jpg)): - * **Do not push** - A link to download the helm package will be available when you trigger a deployment. However, it will not push the helm package to the OCI registry. +In case you are choosing an [isolated environment](../../global-configurations/cluster-and-environments.md#add-isolated-cluster) for deployment, you will get two additional options to choose from in the 'Deploy to Environment' window ([check snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/create-cd2.jpg)): + * **Do not push** - A link to download the helm package will be available after the deployment. However, it will not push the helm package to the OCI registry. * **Push to registry** - This will generate and [push the helm package to the OCI registry](../../global-configurations/container-registries.md#push-helm-packages). Upon selecting this option, you will get two more fields: * **Registry** - Choose the OCI registry to which the helm chart package must be pushed. Only those registries that have `Push helm packages` enabled will be shown in the dropdown. - * **Repository** - Write the repository name in the format `username/repo-name`. You can find the username from your registry provider account. + * **Repository** - Write the repository name in the format `username/repo-name`. You can find the username from your registry provider account (e.g., Docker Hub). {% endhint %} ### Deployment Strategy diff --git a/docs/user-guide/deploy-chart/README.md b/docs/user-guide/deploy-chart/README.md index 306943155..88d710750 100644 --- a/docs/user-guide/deploy-chart/README.md +++ b/docs/user-guide/deploy-chart/README.md @@ -34,18 +34,18 @@ Deprecated charts won't show up in the Chart Store unless you enable the **Show ![Figure 4: Checking Deprecated Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/deprecated.jpg) -Or, you may try performing a resync as shown below +Or, you may try performing a chart resync as shown below: ![Figure 5: Performing a Resync](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/chart-sync.jpg) --- -## Removing your Chart from the Chart Store +## Removing your Charts from the Chart Store {% hint style="warning" %} ### Who Can Perform This Action? -You cannot remove a chart from the Chart Store if the source was a [chart repository](../global-configurations/chart-repo.md). In that case, deleting the chart repository from Devtron will work; however, it will remove all the charts associated with that respository from the Chart store. +You cannot remove a chart from the Chart Store if the source was a [chart repository](../global-configurations/chart-repo.md). Removal is possible only if the charts [come from OCI registry](../global-configurations/container-registries.md#push-helm-packages). {% endhint %} 1. Go to your OCI registry settings in Devtron. @@ -56,14 +56,12 @@ You cannot remove a chart from the Chart Store if the source was a [chart reposi 3. Click **Update**. -The removed chart would no longer appear in the Chart Store. +The removed chart will no longer appear in the Chart Store. {% hint style="info" %} Deleting a chart repo from your OCI registry will not lead to the removal of chart from the Chart Store {% endhint %} +A light alternative is to disable the chart source as shown below, but this doesn't imply the removal of a chart. - - - - +![Figure 7: Disabling a Chart Source](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/overview-of-charts/disable-chart-source.jpg) \ No newline at end of file diff --git a/docs/user-guide/deploy-chart/chart-group.md b/docs/user-guide/deploy-chart/chart-group.md index 68ed79232..5d4bbfb23 100644 --- a/docs/user-guide/deploy-chart/chart-group.md +++ b/docs/user-guide/deploy-chart/chart-group.md @@ -22,12 +22,10 @@ Once you create a group, you can now select and add charts to it. ## 2. Add Charts to the Group -1. To add a chart to the group, click the `+` sign next to the chart you wish to add. +1. To add a chart to the group, click the `+` sign next to the chart you wish to add. You also can add multiple copies of the same chart in the chart group as per your requirements. ![Figure 3: Adding Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/add-chart.jpg) - You also can add multiple copies of the same chart in the chart group as your requirements. - 2. Once you have finalized the charts for your group, click **Save**. ![Figure 4: Saving Chart Group](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/save-chart.jpg) diff --git a/docs/user-guide/global-configurations/cluster-and-environments.md b/docs/user-guide/global-configurations/cluster-and-environments.md index 55a467de2..f9782f803 100644 --- a/docs/user-guide/global-configurations/cluster-and-environments.md +++ b/docs/user-guide/global-configurations/cluster-and-environments.md @@ -112,7 +112,7 @@ A new window pops up displaying all the details about the Devtron agent. ## Add Isolated Cluster -Deploying to an isolated environment will generate and push the helm package to your chart repository (if need be). Further, this package can be used to deploy to an air-gapped cluster via third party tools or manually. +Deploying to an isolated environment will generate and [push the helm package](../global-configurations/container-registries.md#push-helm-packages) to your OCI registry (if need be). Further, this package can be used to [deploy to an air-gapped environment](../use-cases/airgapped-app-deployment.md) via Internet or non-Internet mediums. 1. Go to **Global Configurations** → **Clusters & Environments**. diff --git a/docs/user-guide/global-configurations/container-registries.md b/docs/user-guide/global-configurations/container-registries.md index 26282e2ce..f25dca86b 100644 --- a/docs/user-guide/global-configurations/container-registries.md +++ b/docs/user-guide/global-configurations/container-registries.md @@ -34,7 +34,7 @@ You can configure a container registry using any registry provider of your choic | **Registry URL** | Provide the URL of your registry in case it doesn't come prefilled (do not include `oci://`, `http://`, or `/https://` in the URL) | | **Authentication Type** | The credential input fields may differ depending on the registry provider, check [Registry Providers](#supported-registry-providers) | | **Push container images** | Tick this checkbox if you wish to use the repository to push container images. This comes selected by default and you may untick it if you don't intend to push container images after a CI build. If you wish to to use the same repository to pull container images too, read [Registry Credential Access](#registry-credential-access). | - | **Push helm packages** | Tick this checkbox if you wish to [push helm charts to your registry](#push-helm-packages) | + | **Push helm packages** | Tick this checkbox if you wish to [push helm charts to your OCI registry](#push-helm-packages) | | **Use as chart repository** | Tick this checkbox if you want Devtron to [pull helm charts from your registry and display them on chart store](#use-as-chart-repository). Also, you will have to provide a list of repositories (present within your registry) for Devtron to successfully pull the helm charts. | | **Set as default registry** | Tick this checkbox to set your registry as the default registry hub for your images or artifacts | @@ -42,14 +42,9 @@ You can configure a container registry using any registry provider of your choic ### Push Helm Packages -{% hint style="info" %} -### Prerequisite -OCI registry with `Push helm packages` option enabled. -{% endhint %} - -Devtron supports the pushing of helm charts to your OCI registry. +Upon enabling this option, Devtron supports the pushing of helm charts to your OCI registry. -This is possible through [isolated clusters](../global-configurations/cluster-and-environments.md#add-isolated-cluster) that facilitate virtual deployments. In other words, it generates a helm package that you can use to deploy in air-gapped clusters not connected to Devtron. +This is possible through [isolated clusters](../global-configurations/cluster-and-environments.md#add-isolated-cluster) that facilitate virtual deployments. In other words, it generates a helm package that you can use to [deploy your application in air-gapped clusters](../use-cases/airgapped-app-deployment.md). If you have [configured your CD pipeline](../creating-application/workflow/cd-pipeline.md#deploying-to-an-isolated-environment) to push the helm package to your OCI registry, you can view the pushed helm package in your registry as shown below: @@ -68,13 +63,19 @@ Devtron doesn't support pushing helm packages to [chart repositories](../global- OCI registry with `Use as chart repository` option enabled. {% endhint %} -Unlike Helm repos, OCI registries do not have an index file to discover all the charts. Devtron supports the pulling of helm charts from your OCI registry and display them on your [chart store](../deploy-chart/README.md). +Unlike Helm repos, OCI registries do not have an index file to discover all the charts. If you have helm packages pushed to your OCI registry, you can that registry as a chart repository. + +Upon enabling this option, Devtron can use your OCI registry as the chart source and pull the helm charts to display them on your [Chart Store](../deploy-chart/README.md) for easy deployment. + +#### Tutorial {% embed url="https://www.youtube.com/watch?v=9imC5MMz9gs" caption="Pulling Charts from an OCI Registry to Devtron" %} -Search your OCI registry in the list, and click it. +#### Steps + +Search your OCI registry in the list and click it. -In the **List of repositories**, add your chart repo(s). The format should be `username/chartname`. You can find the username from your registry provider account. +In the **List of repositories** field, add your chart repo(s). The format should be `username/chartname`. You can [find the username](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/find-username.jpg) from your registry provider account. ![Figure 4: Adding Chart Repos](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-pull/container-config.jpg) diff --git a/docs/user-guide/use-cases/README.md b/docs/user-guide/use-cases/README.md index e0bdab866..b817d0e42 100644 --- a/docs/user-guide/use-cases/README.md +++ b/docs/user-guide/use-cases/README.md @@ -11,3 +11,5 @@ In this comprehensive guide, you will find a wide range of use cases, illustrati [Connect Expressjs With Mongodb Database](connect-expressjs-with-mongodb-database.md) [Connect Django With Mysql Database](connect-django-with-mysql-database.md) + +[Deploying Software on Air-gapped Environment](airgapped-app-deployment.md) diff --git a/docs/user-guide/use-cases/airgapped-app-deployment.md b/docs/user-guide/use-cases/airgapped-app-deployment.md new file mode 100644 index 000000000..18dbe0664 --- /dev/null +++ b/docs/user-guide/use-cases/airgapped-app-deployment.md @@ -0,0 +1,40 @@ +# Deploying Software to Air-Gapped Environments with Devtron + +## Problem Statement + +Industries such as healthcare, banking, and finance, have regulations that require certain data to be stored and processed in air-gapped environments. Air-gapped environments are more secure and since they are not exposed to the public, they are less vulnerable to attacks. However, this isolation brings challenges when it comes to receiving and deploying software updates, security patches, bug fixes which generally depend on Internet availability. + +Devtron ensures reliable delivery of software updates regardless of whether your air-gapped environment has Internet access or not. By using Devtron’s OCI push/pull features and helm package generation, vendors and clients can overcome the challenges posed by air-gapped environments + +--- + +## How Devtron Helps Solve the Problem: + +### Scenario 1: Air-Gapped Cluster has access to OCI registry + +In cases where the air-gapped cluster gets controlled access to the Internet, Devtron's OCI push/pull feature helps in delivering your software via OCI registry. + +1. **Vendor Action:** + + - The vendor uses Devtron to generate and [push Helm package](../global-configurations/container-registries.md#push-helm-packages) to an OCI registry (accessible to both vendor and client) by deploying to an [isolated cluster](../creating-application/workflow/cd-pipeline.md#deploying-to-an-isolated-environment). + +2. **Client Action:** + - The client can install the helm package from the OCI registry using their existing deployment tools, or use Devtron to [pull the Helm package](../global-configurations/container-registries.md#use-as-chart-repository) from the OCI registry to their [Chart Store](../deploy-chart/README.md). + - Once the Helm package is pulled, it [appears in the Chart Store](../deploy-chart/README.md#populating-your-charts-to-the-chart-store), allowing easy deployment to the air-gapped environment. + + +### Scenario 2: Air-Gapped Cluster has no Internet Access + +In fully air-gapped environments with no Internet access, the vendor and client may rely on physical transfer of Helm packages. Devtron facilitates this as follows: + +1. **Vendor Action:** + - Similar to [Scanario 1](#scenario-1-air-gapped-cluster-has-access-to-oci-registry), the vendor generates a helm package by deploying the application to an [isolated cluster](../global-configurations/cluster-and-environments.md#add-isolated-cluster). + - Since the client has no access to the Internet, the vendor need not push it to the OCI registry but rather download the generated Helm package either from [App Details](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/app-details-page.jpg) or [Deployment History](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/deployment-history-page.jpg) page of the app in Devtron. + - The Helm package (available in .tgz format) is handed over by the vendor to the client via a portable storage device (e.g., USB drive). + +2. **Client Action:** + - The client manually uploads the Helm package to their air-gapped cluster by mounting the storage device. + - The client deploys the package to the environment using their deployment tools, CLI, or [Cluster Terminal in Devtron's Resource Browser](../resource-browser.md#cluster-terminal). + +This method ensures that clients using air-gapped clusters, even without Internet access, can securely receive software updates. + From 7400798e169fc60d0808bb9726a734c0793ce817 Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Wed, 9 Oct 2024 18:57:29 +0530 Subject: [PATCH 4/4] Commented chart reselection in chart group --- docs/user-guide/deploy-chart/chart-group.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/deploy-chart/chart-group.md b/docs/user-guide/deploy-chart/chart-group.md index 5d4bbfb23..673fe9e82 100644 --- a/docs/user-guide/deploy-chart/chart-group.md +++ b/docs/user-guide/deploy-chart/chart-group.md @@ -52,9 +52,9 @@ Before deploying your chart group, you may click **Advanced Options** to edit th ![Figure 8: Using Advanced Options](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/advanced-options.jpg) -{% hint style="warning" %} + ![Figure 9: Editing Individual Chart Configurations](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/chart-group/advanced-options-2.jpg)