diff --git a/.gitbook.yaml b/.gitbook.yaml index ab87cb3bb..8d7219930 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -141,6 +141,11 @@ redirects: user-guide/clusters: user-guide/resource-browser.md usage/clusters: user-guide/resource-browser.md global-configurations/authorization/sso-login/okta: user-guide/global-configurations/authorization/sso/okta.md +<<<<<<< HEAD + 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 + usage/deploy-chart/overview-of-charts: user-guide/deploy-chart/README.md +======= global-configurations/custom-charts: user-guide/global-configurations/deployment-charts.md global-configurations/plugins-policy: user-guide/global-configurations/plugin-policy.md usage/sdh: user-guide/software-distribution-hub/README.md @@ -149,3 +154,4 @@ redirects: usage/deploy-chart/overview-of-charts: user-guide/deploy-chart/README.md usage/integrations/clair: user-guide/integrations/vulnerability-scanning/clair.md usage/resource-browser/devtron-intelligence: user-guide/devtron-intelligence.md +>>>>>>> main diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index ac0633fab..b8f813016 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -185,7 +185,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 11b84d1e0..162fd2260 100644 --- a/docs/user-guide/creating-application/workflow/cd-pipeline.md +++ b/docs/user-guide/creating-application/workflow/cd-pipeline.md @@ -32,7 +32,7 @@ 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) | @@ -44,7 +44,7 @@ This section expects four inputs from you: 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. + * **Registry** - Choose the OCI registry to which the helm chart package must be pushed. Only those registries that have [Push helm packages](../../global-configurations/container-registries.md#push-helm-packages) enabled will be shown in the dropdown. * **Repository** - Enter the repository name. You can find the username from your registry provider account (e.g., Docker Hub). {% endhint %} diff --git a/docs/user-guide/deploy-chart/README.md b/docs/user-guide/deploy-chart/README.md index df57a6be4..a12a067d3 100644 --- a/docs/user-guide/deploy-chart/README.md +++ b/docs/user-guide/deploy-chart/README.md @@ -1,6 +1,72 @@ # Chart Store ## Introduction +<<<<<<< HEAD + +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 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 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). 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. + +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 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) +======= A [Helm Chart](../../reference/glossary.md#helm-chartspackages) is like a blueprint for deploying your application on Kubernetes. It contains all the necessary configuration files needed to define what and how your application should run. The **Chart Store** in Devtron offers a wide variety of helm charts from different sources for you to select and install based on your requirement. It helps you in managing and organizing charts in the same way an app store helps you manage apps. @@ -74,4 +140,5 @@ Refer to: * [Deploy Charts](deployment-of-charts.md) - if you need to deploy, update, upgrade, disable, or delete charts. -* [Chart Groups](chart-group.md) - if you need to create a chart group and bulk deploy them. \ No newline at end of file +* [Chart Groups](chart-group.md) - if you need to create a chart group and bulk deploy them. +>>>>>>> main diff --git a/docs/user-guide/deploy-chart/chart-group.md b/docs/user-guide/deploy-chart/chart-group.md index 194abff15..123a428ee 100644 --- a/docs/user-guide/deploy-chart/chart-group.md +++ b/docs/user-guide/deploy-chart/chart-group.md @@ -2,6 +2,96 @@ ## Introduction +<<<<<<< HEAD +Using the Chart Group feature of Devtron, you can group and deploy one or more Helm charts in a single click. + +--- + +## 1. Create a Group + +1. Go to the **Chart Store** page and click **+ 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) + +2. In the **Create Chart Group** window, give a name and description (optional) to your chart group, and then click **Create 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) + +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. 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) + +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) + +--- + +## 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) + + + +![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) + +======= A Chart Group in Devtron is a collection of [Helm charts](../../reference/glossary.md#helm-chartspackages) grouped together (e.g., what a folder is to files) to help you create, manage, and deploy them easily. When setting up a new environment or a microservice, or when your application requires multiple Helm charts, you can simply group the required charts into a chart group. You can then view, manage, and deploy related charts together in one place instead of searching and installing each one individually. @@ -132,4 +222,5 @@ The **Advanced Options** page enables you to change the chart values, chart conf 5. Select the project in the **Project** drop-down box. -6. Click **Deploy** to deploy the charts. The deployment will be initiated. \ No newline at end of file +6. Click **Deploy** to deploy the charts. The deployment will be initiated. +>>>>>>> main diff --git a/docs/user-guide/deploy-chart/deployment-of-charts.md b/docs/user-guide/deploy-chart/deployment-of-charts.md index a739d3da0..a48af6d23 100644 --- a/docs/user-guide/deploy-chart/deployment-of-charts.md +++ b/docs/user-guide/deploy-chart/deployment-of-charts.md @@ -1,3 +1,14 @@ +<<<<<<< HEAD +# Deploy a Chart + +## Introduction + +Discover, Configure, Deploy, Update, Upgrade, Delete charts. + +--- + +## 1. Discover Chart from Chart Store +======= # Deploy Charts ## Introduction @@ -5,17 +16,60 @@ This document helps you deploy, update, upgrade, disable, and delete charts. --- +>>>>>>> main ## Configure and Deploy Charts +<<<<<<< HEAD +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/search-chart.jpg) +======= {% hint style="warning" %} +>>>>>>> main ### Who Can Perform This Action? +<<<<<<< HEAD +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/chart-details.jpg) + +--- +======= Only a [Super-Admin or an Admin](../global-configurations/authorization/user-access.md#helm-apps-permissions) can configure and deploy charts. +>>>>>>> main {% endhint %} +<<<<<<< HEAD +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) + +Click **Configure & Deploy** and enter the following details: + +| Key | Description | +| :--- | :--- | +| **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/values-field.jpg) + +You can choose your preferred chart version, chart value, and update the values.yaml using the editor on the right. + +Click **Deploy** to deploy 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 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/chart-app-details.jpg) +======= To configure and deploy Helm, follow the instructions below: 1. Navigate to **Chart Store**. @@ -47,11 +101,23 @@ To configure and deploy Helm, follow the instructions below: | **Deploy to Environment** | Select the environment where you want to deploy the chart | | **Chart Version** | Select the chart version you prefer to deploy| | **Chart Value** | Select the chart value you prefer to use. Kindly refer to [Preset Values](#preset-values) | +>>>>>>> main 6. Click **Deploy Chart**. Once you have deployed a chart, you will be redirected automatically to the **App Details** tab where the deployment status is shown. +<<<<<<< HEAD +3. In the **Configure** tab, you can update, upgrade, or delete your chart instance. + +4. From the `Chart used` section you can go to the charts page where you can see all the running instances of this chart. + +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/deploy-chart/deployment-of-charts/chart-deployment-history.jpg) + +--- +======= ![Figure 3: Check Deployment Status](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/app-installation-success.jpg) The Application Status should be `Healthy`, indicating that the application has been successfully deployed. @@ -61,9 +127,25 @@ The Application Status should be `Healthy`, indicating that the application has ## Refetch Charts When you click on **Refetch Charts**, the system fetches the latest Helm charts (e.g., `stable/mySQL`, `bitnami/mySQL`) and their latest available versions (e.g., v1.0, v1.1) that include improvements, features, and fixes. You can then either update a chart version or upgrade the chart itself in your environment. +>>>>>>> main To check the latest charts and chart versions, follow the instructions below: +<<<<<<< HEAD +For update, you can change its `Chart Version` or `values.yaml` and then click **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 `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/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. + + ![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/charts-status.jpg) + +--- +======= 1. Navigate to the **Configure** tab of your helm application. ![Figure 4: Update Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/deployment-of-charts/update-chart.jpg) @@ -77,9 +159,16 @@ To check the latest charts and chart versions, follow the instructions below: {% hint style="warning" %} ### Who Can Perform This Action? +>>>>>>> main Only a [Super-Admin or an Admin](../global-configurations/authorization/user-access.md#helm-apps-permissions) can update charts. +<<<<<<< HEAD +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) + +======= {% endhint %} When you update a Helm chart, the system actually deploys the selected latest version of a chart (e.g., `12.4.2`) in your environment, just like how you'd install the latest version of an app from the app store. @@ -188,10 +277,24 @@ You can delete a chart source in the following two ways: You cannot disable or delete the default charts provided by Devtron. +>>>>>>> main --- ## Extras +<<<<<<< HEAD +### 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) + +Click on `Save Template` to save the configurations. +======= ### Preset Values If you frequently deploy a particular chart, you can then predefine its configurations as a template, making it easier to deploy across environments. @@ -271,4 +374,5 @@ The **Application Status** should be `Healthy`, indicating that the application Service names makes it easier to find, connect to, and interact with your application. To extract the service name, navigate to **K8s Resources** → **Networking** → **Service**. The service name(s) are displayed in the **Name** column along with the URL in the **URL** column. -![Figure 14: Service Name](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/service-name.gif) \ No newline at end of file +![Figure 14: Service Name](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/service-name.gif) +>>>>>>> main diff --git a/docs/user-guide/global-configurations/chart-repo.md b/docs/user-guide/global-configurations/chart-repo.md index 33023af78..16cd77d6e 100644 --- a/docs/user-guide/global-configurations/chart-repo.md +++ b/docs/user-guide/global-configurations/chart-repo.md @@ -18,6 +18,8 @@ Only a [Super-Admin](../global-configurations/authorization/user-access.md#grant --- +--- + ## Add Chart Repository To add a chart repository, follow the steps below: diff --git a/docs/user-guide/global-configurations/cluster-and-environments.md b/docs/user-guide/global-configurations/cluster-and-environments.md index 01e2270b3..68adee838 100644 --- a/docs/user-guide/global-configurations/cluster-and-environments.md +++ b/docs/user-guide/global-configurations/cluster-and-environments.md @@ -104,6 +104,10 @@ To assign a category to a cluster, follow the steps below: ![Figure 10: Category Assigned](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/cluster-and-environments/assign-category-category-added-cluster.jpg) +{% hint style="info" %} +### Note +Refer [Get Cluster Credentials](#get-cluster-credentials) to know the process of getting Server URL and bearer token. +{% endhint %} ### Choose Method of Connection [![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/elements/EnterpriseTag.svg)](https://devtron.ai/pricing) diff --git a/docs/user-guide/global-configurations/container-registries.md b/docs/user-guide/global-configurations/container-registries.md index 846eea8e8..3dd2bc769 100644 --- a/docs/user-guide/global-configurations/container-registries.md +++ b/docs/user-guide/global-configurations/container-registries.md @@ -2,71 +2,90 @@ ## 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. +A [Container Registry](../../reference/glossary.md#container-registry) acts as a storage place for container [images](../../reference/glossary.md#image) whereas an OCI Registry acts as a storage place for container images, [Helm charts](../../reference/glossary.md#helm-charts-packages), as well as other OCI-compliant artifacts. -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. +You can pull Helm charts from either a public registry or a private registry (only if the registry contains Helm charts) and display them on the [Chart Store](../deploy-chart/README.md) page in Devtron. + +![Figure 1: Container/OCI Registry Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/container-oci-registry-home.jpg) + +{% hint style="warning" %} + +### Who Can Perform This Action? + +Only a Super-Admin can create, update, or delete a container/OCI registry. + +{% endhint %} --- -## Add Container Registry +## Add an OCI Registry ### Steps -1. From the left sidebar, go to **Global Configurations** → **Container/OCI Registry**. +To add a container/OCI registry, follow the steps below: - ![Figure 1: Container/OCI Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/add-registry.jpg) +1. Navigate to **Global Configurations** → **Container/OCI Registry**. + + ![Figure 2: Container/OCI Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/add-registry.jpg) 2. Click **Add Registry**. - ![Figure 2: Add a Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/add-container-registry-1.jpg) + ![Figure 3: Add a Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/add-container-registry-1.jpg) -3. Choose a provider from the **Registry provider** dropdown. View the [Supported Registry Providers](#supported-registry-providers). +3. Choose your preferred registry provider from the **Registry provider** drop-down box. Refer to [Supported Registry Providers](#supported-registry-providers) for more information. 4. Choose the Registry type: - * **Private Registry**: Choose this if your images or artifacts are hosted or should be hosted on a private registry restricted to authenticated users of that registry. Selecting this option requires you to enter your registry credentials (username and password/token). - * **Public Registry**: Unlike private registry, this doesn't require your registry credentials. Only the registry URL and repository name(s) would suffice. -5. Assuming your registry type is private, here are few of the common fields you can expect: + * **Private Registry**: Select this if your images or artifacts are hosted, or should be hosted, on a private registry restricted to the authenticated users. Selecting this option requires you to enter your registry credentials (username and password/token). + + * **Public Registry**: Unlike private registry, this option does not require credentials. You only need to provide the registry URL and repository name(s). + +5. Refer to the following table and enter the required details: | Fields | Description | | --- | --- | - | **Name** | Provide a name to your registry, this name will appear in the **Container Registry** drop-down list available within the [Build Configuration](../creating-application/docker-build-configuration.md) section of your application| - | **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 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 | + | **Name** | Enter your registry name. 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. This name will also appear in the **Container Registry** drop-down box available within the [Build Configuration](../creating-application/docker-build-configuration.md) section of your application| + | **Registry URL** | Enter your registry URL (**Note**: do not include `oci://`, `http://`, or `/https://` in the URL) | + | **Authentication Type** | Select your preferred authentication type. The credential input fields may differ depending on the registry provider, check [Registry Providers](#supported-registry-providers)| + |**Connection Method** | * `Direct`: Select this option to directly connect to an API server that is on the same network or publicly accessible.
* `via Proxy`: Select this option to connect to a remote server that is behind a proxy and not directly reachable.
* `via SSH Tunnel`: Select this option to connect to a server that is not publically accessible, using a secure SSH connection| + | **Push container images** | Enable this checkbox if you'd like to use the repository to push container images. This checkbox is enabled by default, and you may disable 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 as well, read [Registry Credential Access](#registry-credential-access) | + | **Push helm packages** | Enable this checkbox if you wish to [push Helm charts to your OCI registry](#push-helm-packages) | + | **Use as chart repository** | Enable 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** | Enable this checkbox to set your registry as the default registry hub for your images or artifacts | 6. Click **Save**. ### Push Helm Packages -Upon enabling this option, 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 airgapped deployments. In other words, it generates a helm package that you can use to deploy your application in air-gapped clusters. +This is possible through [isolated clusters](../global-configurations/cluster-and-environments.md#add-isolated-cluster) that facilitate airgapped deployments. In other words, it generates a Helm package that you can use to deploy your application in air-gapped clusters. -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: +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 4a: 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) +![Figure 4b: Pushed Helm Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/use-cases/oci-push/helm-chart.jpg) {% hint style="warning" %} +### Important Note + +Devtron does not support pushing Helm packages to chart repositories. + +{% endhint %} + ### Use as Chart Repository {% hint style="info" %} ### Prerequisite -OCI registry with `Use as chart repository` option enabled. +An 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. 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. +When you have your own Helm charts in a private registry and prefer to use them, enable the **Use as chart repository** checkbox. The OCI registry is then considered as a chart repository, and all the existing charts are fetched and displayed in the [Chart Store](../deploy-chart/README.md). #### Tutorial @@ -74,11 +93,122 @@ Upon enabling this option, Devtron can use your OCI registry as the chart source #### Steps -Search your OCI registry in the list and click it. +To use an OCI registry as a chart repository, follow the steps below: + +1. Navigate to **Global Configurations** → **Container/OCI Registry**. + +2. Search for your preferred OCI registry in the list and select it. + +3. Add your chart repositories (where the helm charts are present) in the **List of repositories** field. -In the **List of repositories** field, add your chart repo(s). 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 5: Adding Chart Repositories](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/use-as-cr.jpg) + +4. Click **Save**. + +--- + +## Registry Credential Access + +You can pull [images](../../reference/glossary.md#image) from a container/OCI registry, but when using private registries, it is important to control which clusters have acccess to pull the images. That is why managing registry credential access becomes crucial. + +You can choose to either auto-inject registry credentials to clusters or use a [Secret](../../reference/glossary.md#secrets) to pull an image for deployment to environments on specific clusters. When you choose to auto-inject registry credentials, the right authentication details (e.g., `username`/`password or token`) are automatically provided to a pod without the need of manual intervention. + +You can create a pod that uses a [Secret](../../reference/glossary.md#secrets) to pull an image from a private container registry of your choice (e.g., [Docker Hub](https://www.docker.com/products/docker-hub)). + +To manage the registry credential access, follow the steps below: + +1. Navigate back to the **Container/OCI Registry** page. + +2. Select your preferred registry. + +3. Click the **Manage** button displayed next to the **Registry credential access is auto injected to** label. + + ![Figure 6: Manage Access of Registry Credentials](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/manage-button.jpg) + + You can manage registry credential access in the following two ways: + + | Fields | Description | + | --- | --- | + | **Do not inject credentials to clusters** | Select the clusters where you do not want to inject credentials | + | **Auto-inject credentials to clusters** | Select the clusters where you want to inject credentials | +4. You can choose one of the two options for defining credentials: + * [Use Registry Credentials](#use-registry-credentials) + + * [Specify Image Pull Secret](#specify-image-pull-secret) + + ![Figure 7: Define Credentials](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/container-registries/manage-access-of-reg-creds.jpg) + +5. Click **Save**. + +### Use Registry Credentials + +If you select **Use Registry Credentials**, the clusters will be auto-injected with the registry credentials of your registry type. As an example, if you select **Docker** as the registry type, then the clusters will be auto-injected with the `username` and `password/token` associated with your Docker Hub account. + +![Figure 8: 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/Terminal. + +![Figure 9: 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) + +1. Navigate back to the **Container/OCI Registry** page. + +2. Enter the secret name (e.g., `regcred`) in the **Specify Image Pull Secret** section. + +3. Refer to the table below and enter the following command in the Command Line/Terminal to create a Secret: + +{% hint style="info" %} + +### Important Note + +Docker is used just as an example here. However, you can create Secrets with any registry provider of your choice. + +{% endhint %} + +```bash +kubectl create -n secret docker-registry regcred --docker-server= --docker-username= --docker-password= --docker-email= +``` + +| Key | Description | +| --- | --- | +| `namespace` | Specify your sub-cluster (e.g., **devtron-demo**) | +| `your-registry-server` | Specify your private Docker registry FQDN. For Docker Hub, use https://index.docker.io/v1/ | +| `your-name` | Specify your Docker registry username (e.g., `johndoe`) | +| `your-pword` | Specify your Docker password | +| `your-email` | Specify your Docker email id | + +You have successfully set your Docker credentials in the cluster as a Secret called `regcred`. + +{% hint style="warning" %} + +When you enter Secrets in the Command Line/Terminal while `kubectl` is running, the Secrets can get stored in your shell history unprotected, and can also be temporarily visible to other users. + +{% endhint %} + +## Delete an OCI Registry + +If you prefer to delete an OCI registry, follow the instructions below: + +1. Navigate back to **Container/OCI Registry** page. + + ![Figure 10: Delete an OCI Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/delete-oci-registry.jpg) + +2. Select your preferred OCI registry. + +3. Click the **Delete** button. The OCI registry will be deleted. + +{% hint style="warning" %} + +### Important Note + +If you used an OCI registry as a chart source, deleting the OCI registry will remove all its associated charts from the Chart Store. + +{% endhint %} + +--- ## Supported Registry Providers @@ -166,83 +296,7 @@ Provide below information if you select the registry type as `Other`. | **Advanced Registry URL Connection Options** |
  • **Allow Only Secure Connection**: Tick this option for the registry to allow only secure connections
  • **Allow Secure Connection With CA Certificate**: Tick this option for the registry to allow secure connection by providing a private CA certificate (ca.crt)
  • **Allow Insecure Connection**: Tick this option to make an insecure communication with the registry (for e.g., when SSL certificate is expired)
| {% hint style="info" %} -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 - -You can create a Pod that uses a [Secret](../../reference/glossary.md#secrets) to pull an image from a private container registry. You can use any private container registry of your choice, for e.g., [Docker Hub](https://www.docker.com/products/docker-hub). - -Super-admin users can decide if they want to auto-inject registry credentials or use a secret to pull an image for deployment to environments on specific clusters. - -1. To manage the access of registry credentials, click **Manage**. - -There are two options to manage the access of registry credentials: - -| Fields | Description | -| --- | --- | -| **Do not inject credentials to clusters** | Select the clusters for which you do not want to inject credentials | -| **Auto-inject credentials to clusters** | Select the clusters for which you want to inject credentials | - -2. You can choose one of the two options for defining credentials: - -* [Use Registry Credentials](#use-registry-credentials) -* [Specify Image Pull Secret](#specify-image-pull-secret) - -### Use Registry Credentials - -If you select **Use Registry Credentials**, the clusters will be auto-injected with the registry credentials of your registry type. As an example, If you select `Docker` as Registry Type, then the clusters will be auto-injected with the `username` and `password/token` which you use on the Docker Hub account. -Click **Save**. - -![Figure 4: 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 5: 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): - -```bash -kubectl create -n secret docker-registry regcred --docker-server= --docker-username= --docker-password= --docker-email= -``` - -where, - -* **namespace** is your sub-cluster, e.g., devtron-demo -* **your-registry-server** is your Private Docker Registry FQDN. Use https://index.docker.io/v1/ for Docker Hub. -* **your-name** is your Docker username -* **your-pword** is your Docker password -* **your-email** is your Docker email - -You have successfully set your Docker credentials in the cluster as a Secret called `regcred`. - -{% hint style="warning" %} -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**. - -## Delete an OCI Registry - -If you prefer to delete an OCI registry, follow the instructions below: - -1. Navigate back to **Container/OCI Registry** page. - - ![Figure 6: Delete an OCI Registry](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/deploy-chart/delete-oci-registry.jpg) - -2. Select your preferred OCI registry. - -3. Click the **Delete** button. The OCI registry will be deleted. - - {% hint style="warning" %} - - ### Important Note - - If you used an OCI registry as a chart source, deleting the OCI registry will remove all its associated charts from the Chart Store. +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 %} \ No newline at end of file +{% endhint %} \ No newline at end of file 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..d5a5b7223 --- /dev/null +++ b/docs/user-guide/use-cases/airgapped-app-deployment.md @@ -0,0 +1,39 @@ +# 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. \ No newline at end of file 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 %} - -