diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0e895aeab..75ecc1098 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -176,6 +176,7 @@ * [Terraform CLI](user-guide/plugins/terraform-cli.md) * [Vulnerability Scanning](user-guide/plugins/vulnerability-scanning.md) * [Using Devtron Intelligence](user-guide/devtron-intelligence.md) +* [Enable GitOps Deployments with FluxCD](user-guide/creating-application/fluxcd.md) ## Resources diff --git a/docs/user-guide/creating-application/fluxcd.md b/docs/user-guide/creating-application/fluxcd.md new file mode 100644 index 000000000..db846b8db --- /dev/null +++ b/docs/user-guide/creating-application/fluxcd.md @@ -0,0 +1,169 @@ +# Enable GitOps Deployments with FluxCD + +{% hint style="info" %} +### Prerequisite + +Make sure to install: + +1. [Build and Deploy (CI/CD) integration](../integrations/build-and-deploy-ci-cd.md) + +2. [GitOps (ArgoCD) integration](../integrations/argocd.md) + +{% endhint %} + +Devtron supports FluxCD to enable GitOps-based deployments. With FluxCD, you can: + +* Deploy applications via GitOps (via FluxCD). + +* Deploy Helm charts via FluxCD. + +* Migrate existing FluxCD applications into Devtron. + +Your Git repository becomes the single source of truth for your Kubernetes workloads. Any changes you make in Git are automatically applied to your Kubernetes cluster by FluxCD. Refer to the [FluxCD documentation](https://fluxcd.io/flux/) to learn more. + + +## Installation + +{% hint style="warning" %} +### Who Can Perform This Action? +The user must have permissions to: + * Edit the ConfigMaps of 'default-cluster' + * Restart the pods +{% endhint %} + +To enable deployments through GitOps via FluxCD, you need to enable a specific feature flag for the `default_cluster` in Devtron. + + |Feature|Flag|Description| + |:---|:---|:---| + |**Deployments via FluxCD**|`FEATURE_FLUX_DEPLOYMENTS_ENABLE: "true"`|This flag will enable deployments through GitOps via FluxCD.| + |**Migrating existing FluxCD applications**|`FEATURE_LINK_EXTERNAL_FLUX_ENABLE: "true"`|This flag will enable migrations for external FluxCD apps into Devtron.| + + {% hint style="warning" %} + ### Deployment Strategies for FluxCD Deployments + + Application deployments through GitOps (via FluxCD) are supported only when using the `Deployment` or `Rollout` deployment strategies with the latest chart versions. Other deployment strategies are currently not supported. + {% endhint %} + +### Enabling Feature Flags + +1. Navigate to Devtron's **Resource Browser**. + + ![Figure 1: Navigating to Resource Browser](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-resource-browser.jpg) + +2. Select the `default_cluster` to enable the feature flags. + + ![Figure 2: Selecting 'default_cluster'](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-select-cluster.jpg) + +3. Go to Config & Storage → ConfigMap, and click `dashboard-cm` ConfigMap + + ![Figure 3: Clicking 'dashboard-cm'](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-select-dashboard-cm.jpg) + +4. Edit the `dashboard-cm` ConfigMap by clicking **Edit live manifest**. + + ![Figure 4: Editing Live Manifest](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-edit-live-manifest.jpg) + 1. To enable deployments via FluxCD, check if the below entries are present in the ConfigMap (create one if it doesn't exist) and select **Apply changes**.
+ + ```yaml + FEATURE_FLUX_DEPLOYMENTS_ENABLE: "true" + ``` + + 2. To enable migration for external FluxCD applications, check if the below entries are present in the ConfigMap (create one if it doesn't exist) and select **Apply changes**.
+ + ```yaml + FEATURE_LINK_EXTERNAL_FLUX_ENABLE: "true" + ``` + +
+ + ![Figure 5: Adding Feature Flags](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-add-flags.jpg) + +5. Restart the deployment: + 1. **For OSS Users:** + 1. Navigate to Devtron's Resource Browser. + + 2. Select the cluster for which you have enabled the feature flags. + + 3. Click the **Terminal** tab. + + 4. Restart the deployment using the following command: + + ```yaml + kubectl rollout restart deployment dashboard -n devtroncd + ``` + + ![Figure 6: Restarting Deployment](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-restart-deployment.gif) + 2. **For Enterprise Users:** + 1. Go to **Resource Browser** → (select the cluster in which you have enabled the feature flags) → **Workloads** → **Deployment** + + 2. Click the checkbox next to the `dashboard` Deployment workloads and restart them using the `⟳` button. + + ![Figure 7: Restart 'dashboard' deployment workloads](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/devtron-intelligence/restart-deployments.jpg) + +6. Perform a hard refresh of the browser to clear the cache: + + * **Mac**: Hold down Cmd and Shift and then press R. + + * **Windows/Linux**: Hold down Ctrl and then press F5. + +### Installing FluxCD Controller (Only for Deployments) + +After enabling the feature flag for deployments, the next step is to install FluxCD Controller in every cluster (including the default cluster) in which you want to deploy the FluxCD applications. + +You can install FluxCD Controller by any of the following ways: + + 1. [Install FluxCD controller via Cluster Terminal](#install-fluxcd-controller-via-cluster-terminal) (Recommended) + + 2. [Install FluxCD controller via Chart Store](#install-fluxcd-controller-via-chart-store) + + +#### Install FluxCD controller via Cluster Terminal. + +1. Navigate to Devtron's Resource Browser. + +2. Select the cluster for which you have enabled the feature flags. + +3. Click the **Terminal** tab. + +4. Run the following command to install the FluxCD Controller: + + ```yaml + kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v0.35.0/install.yaml + ``` + + ![Figure 8: Installing FluxCD Controller](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-install-controller.gif) + +5. After the command is executed successfully, you can deploy or migrate your applications in that cluster through GitOps (via FluxCD). + +#### Install FluxCD controller via Chart Store. + +To install FluxCD controller via Chart Store, follow the below steps. + + 1. Add FluxCD controller repository, `https://fluxcd-community.github.io/helm-charts` in the chart repositories (if not already added) in Global Configurations. Refer [Chart Repositories](../global-configurations/chart-repo.md#add-chart-repository) to learn more. + + ![Figure 9: Adding FluxCD Chart Repository](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-add-chart-repo.gif) + + 2. Add a new environment in the cluster in which you want to deploy the application via FluxCD linked to namespace as `flux-system`. Refer [Clusters and Environments](../global-configurations/cluster-and-environments.md#add-environment-to-a-cluster) to lean more. + + ![Figure 10: Adding Environment linked to 'flux-system' namespace](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-add-env.gif) + + 3. Navigate to **Chart Store** and select the `flux2` chart. + + ![Figure 11: Selecting 'flux2' Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-flux2.jpg) + + 4. Click **Configure and Deploy**. + + ![Figure 12: Deploying 'flux2' Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-deploy-chart.jpg) + + 5. Configure the following configurations: + + |Field Name|Description| + |:---|:---| + |**App Name**|Define a name for the chart.| + |**Project**|Select a project from the dropdown| + |**Deploy to Environment**|Select the environment which you have created in your preferred cluster linked to `flux-system` namespace.| + + ![Figure 13: Configuring 'flux2' Chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/fluxcd/fluxcd-chart-config.jpg) + + 6. Click **Deploy** and the chart will be deployed. + +After the chart is successfully deployed, you can deploy applications though GitOps (via FluxCD). \ No newline at end of file diff --git a/docs/user-guide/creating-application/workflow/cd-pipeline.md b/docs/user-guide/creating-application/workflow/cd-pipeline.md index 11b84d1e0..0295edd76 100644 --- a/docs/user-guide/creating-application/workflow/cd-pipeline.md +++ b/docs/user-guide/creating-application/workflow/cd-pipeline.md @@ -13,7 +13,7 @@ A basic `Create deployment pipeline` window will pop up. ![Figure 2: Creating CD Pipeline](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/workflow-cd-pipeline/new-cd-pipeline.jpg) Here, you get two tabs: -* [New Deployment](#new-deployment) - Use this option to create new Helm/GitOps deployment. +* [New Deployment](#new-deployment) - Use this option to create a new Helm/GitOps deployment. * [Migrate to Devtron](#migrate-to-devtron) - Use this option if you wish to migrate your existing Helm Release/Argo CD Apps to Devtron. --- @@ -30,12 +30,20 @@ The **New Deployment** tab displays the following sections: This section expects four inputs from you: -| Setting | Description | Options | +| Setting | Description | Options | | ----------- | ---------------------------------------------------------- | ------------------------- | | 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) | +| Deployment Approach | How to deploy the application | **Helm**, [GitOps(ArgoCD)](../../integrations/argocd.md) or [Gitops (FluxCD)](../../creating-application/fluxcd.md)
Refer [GitOps](../../global-configurations/gitops.md) to learn more | + +{% hint style="warning" %} + ### FluxCD Deployment Failed + * Make sure that the FluxCD controller is installed in the cluster in which you want to deploy the application. Refer [Enable GitOps Deployments with FluxCD](../../creating-application/fluxcd.md#installing-fluxcd-controller-only-for-deployments) to learn more. + + * Application deployments through GitOps (via FluxCD) are supported only when using the `Deployment` or `Rollout` deployment strategies with the latest chart versions. Other deployment strategies are currently not supported. + +{% endhint %} {% hint style="info" %} @@ -55,7 +63,7 @@ Devtron supports multiple deployment strategies depending on the [deployment cha ![Figure 3: Strategies Supported by Chart Type](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/workflow-cd-pipeline/chart-and-strategy.jpg) -Refer [Deployment Strategies](#deployment-strategies) to know more about each strategy in depth. +Refer to [Deployment Strategies](#deployment-strategies) to know more about each strategy in depth. The next section is [Advanced Options](#advanced-options) and it comes with additional capabilities. This option is available at the bottom of the `Create deployment pipeline` window. However, if you don't need them, you may proceed with a basic CD pipeline and click **Create Pipeline**. @@ -97,7 +105,7 @@ If you want to use some configuration files and secrets in pre-deployment stages 4. **Execute tasks in application environment** -These `Pre-deployment CD / Post-deployment CD` pods can be created in your deployment cluster or the devtron build cluster. If your scripts/tasks has some dependency on the deployment environment, you may run these pods in the deployment cluster. Thus, your scripts \(if any\) can interact with the cluster services that may not be publicly exposed. +These `Pre-deployment CD / Post-deployment CD` pods can be created in your deployment cluster or the Devtron build cluster. If your scripts/tasks have some dependency on the deployment environment, you may run these pods in the deployment cluster. Thus, your scripts \(if any\) can interact with the cluster services that may not be publicly exposed. Some tasks require extra permissions for the node where Devtron is installed. However, if the node already has the necessary permissions for deploying applications, there is no need to assign them again. Instead, you can enable the **Execute tasks in application environment** option for the pre-CD or post-CD steps. By default, this option is disabled. @@ -115,14 +123,14 @@ Make sure your cluster has [devtron-agent](../../global-configurations/cluster-a * After the deployment, edit the devtron-cm configmap and add the following key-value pair: - ```bash + ```bash ORCH_HOST: /orchestrator/webhook/msg/nats Example: ORCH_HOST: http://xyz.devtron.com/orchestrator/webhook/msg/nats - ``` + ``` `ORCH_HOST` value should be same as of `CD_EXTERNAL_LISTENER_URL` value which is passed in values.yaml. @@ -138,7 +146,7 @@ Make sure your cluster has [devtron-agent](../../global-configurations/cluster-a ![Figure 9: 'migration-incluster-cd' chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/workflow-cd-pipeline/migration-incluster-chart.jpg) -* Edit the `cluster-name` and `secret name` values within the chart. The `cluster name` refers to the name used when adding the cluster in the global configuration and for which you are going to enable `Execute tasks in application environment` option. +* Edit the `cluster-name` and `secret name` values within the chart. The `cluster name` refers to the name used when adding the cluster in the global configuration, and for which you are going to enable the `Execute tasks in application environment` option. ![Figure 10: Configuration](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/workflow-cd-pipeline/migration-incluster.jpg) @@ -148,7 +156,7 @@ Make sure your cluster has [devtron-agent](../../global-configurations/cluster-a #### Pipeline Name -Pipeline name will be auto-generated; however, you are free to modify the name as per your requirement. +The pipeline name will be auto-generated; however, you are free to modify the name as per your requirement.