diff --git a/_data/home-content.yml b/_data/home-content.yml index 47880b321..3f6020641 100644 --- a/_data/home-content.yml +++ b/_data/home-content.yml @@ -19,14 +19,10 @@ icon: images/home-icons/tutorial.svg url: "" links: - - title: Create Codefresh account - localurl: /docs/quick-start/create-codefresh-account/ - title: CI/CD quick starts - localurl: /docs/quick-start/ci-quick-start/ + localurl: /docs/ci-quick-start/ci-quick-start/ - title: GitOps quick starts - localurl: /docs/quick-start/gitops-quick-start/ - - title: Promotions - localurl: /docs/promotions/promotion-scenarios/ + localurl: /docs/gitops-quick-start/gitops-quick-start/ - title: Products icon: images/home-icons/product.svg @@ -143,8 +139,6 @@ - title: Pipeline integrations icon: images/home-icons/cloud-integrations.png links: - - title: Hosted GitOps - localurl: /docs/integrations/codefresh-hosted-gitops/ - title: Git providers localurl: /docs/integrations/git-providers/ - title: OpenID Connect diff --git a/_data/nav.yml b/_data/nav.yml index c326a52d4..8b631687c 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -14,39 +14,60 @@ - title: Global Search & Navigation url: "/command-bar" -- title: Quick starts - url: "/quick-start" +- title: CI/CD quick starts + url: "/ci-quick-start" pages: - title: Create Codefresh account url: "/create-codefresh-account" - - title: CI/CD quick starts - url: "/ci-quick-start" - sub-pages: - - title: Pipeline quick start - url: "/create-ci-pipeline" - - title: Kubernetes deployment quick start - url: "/deploy-to-kubernetes" - - title: Helm quick start - url: "/deploy-with-helm" - - title: On-demand environment quick start - url: "/on-demand-environments" - - title: GitOps quick starts + - title: Pipeline quick start + url: "/create-ci-pipeline" + - title: Kubernetes deployment quick start + url: "/deploy-to-kubernetes" + - title: Helm quick start + url: "/deploy-with-helm" + - title: On-demand environment quick start + url: "/on-demand-environments" + +- title: GitOps quick starts + url: "/gitops-quick-start" + pages: + - title: About GitOps quick starts url: "/gitops-quick-start" - sub-pages: - - title: Provision a Hosted GitOps Runtime - url: "/install-hosted" - - title: Prepare for Hybrid GitOps Runtime installation - url: "/verify-requirements" - - title: Install a Hybrid GitOps Runtime - url: "/runtime" - - title: Create an application - url: "/create-app-ui" - - title: Create and commit resources for application - url: "/create-app-specs" - - title: Update the image tag for application - url: "/create-rollout" - - title: Work with Environments & Products - url: "/gitops-products" + - title: Create Codefresh account + url: "/create-codefresh-account" + - title: GitOps Runtimes & Git Sources + url: "/gitops-runtimes" + sub-pages: + - title: Preparing for Hybrid GitOps Runtime installation + url: "/verify-requirements" + - title: Installing a Hybrid GitOps Runtime + url: "/runtime" + - title: Creating Git Sources + url: "/create-git-source" + - title: Environments, Products, Applications + url: "/products" + sub-pages: + - title: Creating environments + url: "/quick-start-gitops-environments" + - title: Creating products + url: "/quick-start-product-create" + - title: Creating applications + url: "/create-app-ui" + - title: Exploring the Product Dashboard + url: "/quick-start-product-dashboard" + - title: Promotions + url: "/promotions" + sub-pages: + - title: Drag-and-drop promotion + url: "/drag-and-drop" + - title: Multi-environment sequential promotion + url: "/multi-env-sequential-flow" + - title: Multi-environment promotion with gates + url: "/policy-multi-env-promotion" + - title: Multi-environment parallel promotion + url: "/parallel-multi-env-promotion" + - title: Multi-environment promotion with dependencies + url: "/dependency-multi-env-promotion" - title: Dashboards & insights url: "/dashboards" @@ -397,23 +418,12 @@ url: "/promotions-overview" - title: Getting started url: "/getting-started" + - title: Promotion tutorials + url: "/promotion-scenarios" - title: Promotion building blocks url: "/promotion-components" - title: Promotion setup guidelines url: "/create-promotion-sequence" - - title: Promotion tutorials - url: "/promotion-scenarios" - sub-pages: - - title: Drag-and-drop - url: "/drag-and-drop" - - title: Multi-environment sequential promotion - url: "/multi-env-sequential-flow" - - title: Multi-environment promotion with conditions - url: "/policy-multi-env-promotion" - - title: Multi-environment promotion with parallel environments - url: "/parallel-multi-env-promotion" - - title: Multi-environment promotion with dependencies - url: "/dependency-multi-env-promotion" - title: Entity configuration url: "/entities" sub-pages: diff --git a/_docs/quick-start/ci-quick-start.md b/_docs/ci-quick-start/ci-quick-start.md similarity index 100% rename from _docs/quick-start/ci-quick-start.md rename to _docs/ci-quick-start/ci-quick-start.md diff --git a/_docs/quick-start/ci-quick-start/create-ci-pipeline.md b/_docs/ci-quick-start/create-ci-pipeline.md similarity index 100% rename from _docs/quick-start/ci-quick-start/create-ci-pipeline.md rename to _docs/ci-quick-start/create-ci-pipeline.md diff --git a/_docs/quick-start/ci-quick-start/deploy-to-kubernetes.md b/_docs/ci-quick-start/deploy-to-kubernetes.md similarity index 100% rename from _docs/quick-start/ci-quick-start/deploy-to-kubernetes.md rename to _docs/ci-quick-start/deploy-to-kubernetes.md diff --git a/_docs/quick-start/ci-quick-start/deploy-with-helm.md b/_docs/ci-quick-start/deploy-with-helm.md similarity index 100% rename from _docs/quick-start/ci-quick-start/deploy-with-helm.md rename to _docs/ci-quick-start/deploy-with-helm.md diff --git a/_docs/quick-start/ci-quick-start/on-demand-environments.md b/_docs/ci-quick-start/on-demand-environments.md similarity index 100% rename from _docs/quick-start/ci-quick-start/on-demand-environments.md rename to _docs/ci-quick-start/on-demand-environments.md diff --git a/_docs/gitops-quick-start/create-codefresh-account.md b/_docs/gitops-quick-start/create-codefresh-account.md new file mode 100644 index 000000000..b96081cbd --- /dev/null +++ b/_docs/gitops-quick-start/create-codefresh-account.md @@ -0,0 +1,117 @@ +--- +title: "Creating a Codefresh account" +description: "Start working in Codefresh" +group: gitops-quick-start +redirect_from: + - /docs/getting-started/create-a-codefresh-account/ + - /docs/ + - /docs/create-an-account/ + - /docs/getting-started/ + - /docs/getting-started/introduction/ +toc: true +--- +Once you have installed Codefresh, the next step is to create an account in Codefresh. + +After you select the IdP (identity provider), Codefresh requests permission to access your basic details, and for Git providers, to access your Git repositories. The Permissions window that is displayed differs according to the IdP selected. +The permissions requested by Codefresh are needed in order to build and deploy your projects. + +## Supported IdPs +Codefresh currently supports the following IdPs: +* GitHub +* Bitbucket +* GitLab +* Azure +* Google +* LDAP + +If you need an IdP that is not in the list, please [contact us](https://codefresh.io/contact-us/){:target="\_blank"} with the details. + + +>**NOTE** +For Git repositories, the login method is less important, as you can access Git repositories through [Git integrations]({{site.baseurl}}/docs/integrations/git-providers/), regardless of your sign-up process.

+If you have multiple sign-up methods, as long as you use the same email address in all the sign-ups, Codefresh automatically redirects you to the account dashboard. + +## Create Codefresh account +1. Select the identity provider (IdP) to use: + 1. Go to the [Codefresh Sign Up page](https://g.codefresh.io/signup). + 1. Select the IdP for sign-up. + +{% include +image.html +lightbox="true" +file="/images/administration/create-account/select-identity-provider.png" +url="/images/administration/create-account/select-identity-provider.png" +alt="Codefresh sign-up page" +caption="Codefresh sign-up page" +max-width="40%" +%} + +{:start="2"} +1. Accept the permissions request for the selected IdP: + * For GitHub: To continue, click **Authorize codefresh-io**. + * For Bitbucket: To continue, click **Grant access**. + * For GitLab: To continue, click **Authorize**. + + Once you confirm the permissions for your Git provider, Codefresh automatically connects to your Git provider and fetches your basic account details, such as your email. + +{:start="3"} +1. Review the details for your new account, make the relevant changes, and click **NEXT**. + +{% include +image.html +lightbox="true" +file="/images/administration/create-account/codefresh-signup.png" +url="/images/administration/create-account/codefresh-signup.png" +alt="Codefresh account details" +caption="Codefresh account details" +max-width="40%" +%} + +{:start="4"} +1. Enter a name for your account, and click **NEXT**. + +{% include +image.html +lightbox="true" +file="/images/administration/create-account/codefresh-accountname.png" +url="/images/administration/create-account/codefresh-accountname.png" +alt="Codefresh account name" +caption="Codefresh account name" +max-width="40%" +%} + +{:start="5"} +1. Finally, answer the questions to personalize your account and click **FINISH**. + +{% include +image.html +lightbox="true" +file="/images/administration/create-account/codefresh-personalize.png" +url="/images/administration/create-account/codefresh-personalize.png" +alt="Codefresh personalize account" +caption="Codefresh personalize account" +max-width="40%" +%} + +Congratulations! Your new Codefresh account is now ready. + +{% include +image.html +lightbox="true" +file="/images/administration/create-account/codefresh-dashboard.png" +url="/images/administration/create-account/codefresh-dashboard.png" +alt="Codefresh dashboard" +caption="Codefresh dashboard" +max-width="40%" +%} + + +## What's next +Verify that you are ready to install the GitOps Hybrid Runtime, the foundation for GitOps operations. + +[Quick start: Preparing for Hybrid GitOps Runtime installation]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/verify-requirements/) + + + + + diff --git a/_docs/gitops-quick-start/gitops-quick-start.md b/_docs/gitops-quick-start/gitops-quick-start.md new file mode 100644 index 000000000..ff07479c4 --- /dev/null +++ b/_docs/gitops-quick-start/gitops-quick-start.md @@ -0,0 +1,35 @@ +--- +title: "GitOps quick starts" +description: "" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/quick-start/gitops-quick-start/ +--- + +Codefresh GitOps is all about streamlining application delivery through automation, consistency, and scalability. With Codefresh, you can go from zero to deployment-ready in just a few steps. +The GitOps quick start guides provide step-by-step walkthroughs for you to fully leverage Codefresh GitOps. Starting with account creation, the guides walk you through essential setup leading up to the ultimate goal: deploying and promoting applications seamlessly in your environments. + +##### Our quick start walkthroughs + +* [Creating an Account]({{site.baseurl}}/docs/gitops-quick-start/create-codefresh-account/) + Get started by setting up your Codefresh account. + +* [Installing a GitOps Runtime]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/) + Learn how to install a GitOps Runtime, the single pane of glass component that bridges Git repositories, Kubernetes clusters, applications, and other GitOps entities. + +* [Creating environments]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/) + Define and manage environments, enabling structured application deployments across different stages. + +* [Creating products]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-create/) + Organize related applications under a single product, providing context and control for managing deployments. + +* [Creating applications]({{site.baseurl}}/docs/gitops-quick-start/products/create-app-ui/) + Add applications to your product and configure their source repositories, manifests, and deployment paths. + +* [Promoting products and applications]({{site.baseurl}}/docs/gitops-quick-start/promotions/) + Deploy, validate, and promote changes across environments through automated promotion flows. + +##### From start to deployment +The quick-start journey begins with creating your account and concludes with promotions for applications. Each quick start builds on the last, equipping you with the knowledge and tools to confidently promote and deploy applications in production environments. + diff --git a/_docs/gitops-quick-start/gitops-runtimes.md b/_docs/gitops-quick-start/gitops-runtimes.md new file mode 100644 index 000000000..7256cad10 --- /dev/null +++ b/_docs/gitops-quick-start/gitops-runtimes.md @@ -0,0 +1,35 @@ +--- +title: "Quick start: Runtimes & Git Sources in Codefresh GitOps" +description: "Install GitOps Runtime and create Git Sources" +group: gitops-quick-start +toc: true +--- + + + + + +If you have created your account, you can install the GitOps Runtime. + +The GitOps Runtime is the cornerstone of Codefresh’s GitOps capabilities, simplifying the complexity of managing deployments at scale with Argo CD. It provides unique benefits that enhance visibility, scalability, and security, making deployment management seamless and efficient. + + + +## Benefits of GitOps Runtimes + +* **Unified visibility** + All Argo CD instances are managed through a single control plane, providing comprehensive visibility into all installed Runtimes. The GitOps Runtimes page displays essential details about each Runtime and offers tools for streamlined management. + +* E**ffortless maintenance** + Easily track and upgrade Runtime versions. The Runtimes page includes a version column that alerts you when updates are available, with links to detailed changelogs for transparent decision-making. + +* **Flexible scalability** + Simplify the management of multiple Argo CD instances by installing additional instances, or scale down by connecting extra remote clusters to an existing GitOps Runtime. + + + +Explore these quick starts to prepare your setup, install a GitOps Runtime, and create a Git source, before you continue with application promotions and deployments. + +[Quick start: Preparing for Hybrid GitOps Runtime installation]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/verify-requirements/) +[Quick start: Installing a Hybrid GitOps Runtime]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/runtime/) +[Quick start: Creating a Git Source]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/create-git-source/) \ No newline at end of file diff --git a/_docs/gitops-quick-start/gitops-runtimes/create-git-source.md b/_docs/gitops-quick-start/gitops-runtimes/create-git-source.md new file mode 100644 index 000000000..97d43f9f1 --- /dev/null +++ b/_docs/gitops-quick-start/gitops-runtimes/create-git-source.md @@ -0,0 +1,73 @@ +--- +title: "Quick start: Creating a Git Source" +description: "Add a Git Source to Runtimes to store application manifests" +group: gitops-quick-start +toc: true +--- + +In this quick start, we'll focus on creating a Git Source for the GitOps Runtime we installed in the previous quick start. + +##### Why create a Git Source? +A Git Source is a unique entity for use with GitOps Runtimes in Codefresh. +The Git Source connects to a Git repository within your organization, serving as an easy way to manage the deployment and configuration of Argo CD applications on clusters. + +The Git repository referenced by the Git Source stores application manifests and other resources which are always synced to the cluster. You can manage the Git Source itself as an Argo CD application. + +For details, see [Managing Git Sources in GitOps Runtimes]({{site.baseurl}}/docs/gitops-quick-start/products/). + + + +## Create a Git Source +Create the Git Source for the Runtime installed earlier to reference the Git repo corresponding to the Git Source. +You can automatically create the repo at the same time as the Git Source. + +1. In the Codefresh UI, on the toolbar, click the **Settings** icon. +1. From Runtimes in the sidebar, select **GitOps Runtimes**. +1. In the List View, select the Runtime you installed earlier, and then click the **Git Sources** tab. +1. Click **Create Git Source**, and in the Create Git Source panel, define the settings for the Git Source. + * **Git Source Name**: A name for the Git Source, `demo-trio-gitsource` for the quick start to tie in with set of applications we'll create later. + * **Type**: Retain **Standard Git Source**. + * **Source**: + * Select **Create a new repository** to automatically create the repository in GitHub. + * **Repository**: Enter the full path to the repository, including the `.git` extension. For the quick start, we'll define `https://github.com/codefresh-sandbox/demo-git-source.git`. + * **Branch**: `main`. + Leave all other settings as is. + + + + {% include + image.html + lightbox="true" + file="/images/quick-start/runtimes/qs-runtime-create-gitsource.png" + url="/images/quick-start/runtimes/qs-runtime-create-gitsource.png" + alt="Runtime quick start: Create Git Source" + caption="Runtime quick start: Create Git Source" + max-width="50%" +%} + + +{:start="5"} +1. Click **+ Create**. + +Here's an example of the Git repository referenced in GitHub by the Git source. + + {% include + image.html + lightbox="true" + file="/images/quick-start/runtimes/qs-runtime-gitsource-repo.png" + url="/images/quick-start/runtimes/qs-runtime-gitsource-repo.png" + alt="Runtime quick start: Git repo for Git Source" + caption="Runtime quick start: Git repo for Git Source" + max-width="60%" +%} + +## What's next +With a Git Source set up, you are now ready to create applications. Before diving into application creation, let’s focus on two key entities essential for promoting and deploying applications: Environments and Products. + +* Environments represent stages in your software development lifecycle, providing a structured way to track and manage your applications. +* Products group related applications under a single entity, enabling better organization, visibility, and control when promoting changes and deploying applications. + +Let’s continue by creating environments. + +[Quick start: Creating Environments]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/) + diff --git a/_docs/gitops-quick-start/gitops-runtimes/runtime.md b/_docs/gitops-quick-start/gitops-runtimes/runtime.md new file mode 100644 index 000000000..e0d8efcbb --- /dev/null +++ b/_docs/gitops-quick-start/gitops-runtimes/runtime.md @@ -0,0 +1,80 @@ +--- +title: "Quick start: Installing a Hybrid GitOps Runtime" +description: "Install the Helm-based Hybrid GitOps Runtime" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/quick-start/gitops-quick-start/runtime/ +--- + + + +If you've reviewed and verified that you meet the requirements for a GitOps Runtime, let's go ahead and install the Runtime. + +## Before you begin +Verify you have completed the [prerequisites]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/verify-requirements/) + +## Install the GitOps Runtime +1. In the Welcome page, select **+ Install Runtime**. +1. From Runtimes in the sidebar, select **GitOps Runtimes**. +1. Click **Hybrid Runtimes**, and then click **Add**. +1. Install the Hybrid GitOps Runtime: + 1. Click **Generate** to create a new API key. + 1. Retain the default values for the GitOps Runtime name and namespace, `codefresh`. + 1. Copy the command in _Step 3_ and run it to install the Helm chart for the Hybrid GitOps Runtime: + where: + * `cf-gitops-runtime` is the default name of the Helm release, which you can change if needed. + * `codefresh` is the default namespace in which to install the Hybrid GitOps runtime. + * `` is mandatory for _tunnel-based Hybrid GitOps Runtimes_, and is automatically populated by Codefresh in the command. + * `` is the API key you generated, and is also automatically populated in the command. + * `codefresh` is the default name of the Runtime. + * `oci://quay.io/codefresh/gitops-runtime` is the name of the Helm chart, predefined by Codefresh, and cannot be changed. + +{% include +image.html +lightbox="true" +file="/images/runtime/helm/helm-install-hybrid-runtime.png" +url="/images/runtime/helm/helm-install-hybrid-runtime.png" +alt="Runtime quick start: Install Hybrid GitOps Runtime" +caption="Runtime quick start: Install Hybrid GitOps Runtime" +max-width="60%" +%} + +{:start="5"} +1. Wait for a few minutes, and then click **Close**. + You are taken to the List View for GitOps Runtimes, where the Sync Status column displays Complete Installation. +1. In the Sync Status column, click **Complete Installation**. + Codefresh displays the steps to complete installing the GitOps Runtime. + + {% include +image.html +lightbox="true" +file="/images/runtime/helm/helm-complete-install-widgets.png" +url="/images/runtime/helm/helm-complete-install-widgets.png" +alt="Runtime quick start: Steps to complete installation" +caption="Runtime quick start: Steps to complete installation" +max-width="60%" +%} + +{:start="7"} +1. Click **Add** to integrate the Runtime token for your Git provider account: + 1. If not GitHub, select the Git provider. + 1. Define the provider's API URL. + 1. Define the URL of the **Shared Configuration Repository**. +1. Click **Add** to add the user token for your Git provider account, and then paste the token in the field. +1. Complete the installation by clicking **Configure as Argo Application**. + There is no need for any further action from you, as Codefresh takes care of the configuration. + By configuring the Hybrid GitOps Runtime as an Argo Application, you can ensure that GitOps is the single source of truth for the Runtime, view and monitor Runtime components. + + + + +## What's next +Let's create a Git Source to which we'll link the applications we'll create later in the quick start series. +Explore Git Sources and why we need them in [Managing Git Sources in GitOps Runtimes]({{site.baseurl}}/docs/installation/gitops/git-sources/). + +[Quick start: Creating a Git Source]({{site.baseurl}}/docs/gitops-quick-start/gitops-runtimes/create-git-source/) + + + + diff --git a/_docs/gitops-quick-start/gitops-runtimes/verify-requirements.md b/_docs/gitops-quick-start/gitops-runtimes/verify-requirements.md new file mode 100644 index 000000000..4e43bffc6 --- /dev/null +++ b/_docs/gitops-quick-start/gitops-runtimes/verify-requirements.md @@ -0,0 +1,102 @@ +--- +title: "Quick start: Preparing for GitOps Runtime installation" +description: "Verify you're ready for Hybrid GitOps Runtime installation" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/quick-start/gitops-quick-start/verify-requirements/ +--- + + + +The Hybrid GitOps Runtime is installed through a Helm chart. +For configuration details, refer to the Codefresh `values.yaml` file, which includes all available arguments (mandatory and optional) with descriptions. Go to [values.yaml](https://github.com/codefresh-io/gitops-runtime-helm/blob/main/charts/gitops-runtime/){:target="\_blank"}. + +## Quick start assumptions for Runtime installation + +### First GitOps Runtime in account +The quick start assumes you are installing the first Hybrid GitOps Runtime in your Codefresh account. + +### Tunnel-based access mode +Hybrid GitOps Runtimes support tunnel-based and ingress-based access modes. +For the quick start, we'll use the default tunnel-based access mode, which does not require an ingress controller. + +For details on access modes, see [GitOps Runtime architecture]({{site.baseurl}}/docs/installation/gitops/runtime-architecture/). + +### GitHub as the Git provider +The Hybrid GitOps Runtime requires a Git Runtime token for authentication to the Git installation repository based on your Git provider, and a Git user token to authenticate Git-based actions for the Runtime. + +The quick start uses GitHub as the Git provider. For other Git providers and token requirements, see [Git tokens for GitOps]({{site.baseurl}}/docs/security/git-tokens/). + +##### Git Runtime token +Have your GitHub Runtime token ready with a valid expiration date and access permissions: + * Expiration: Either the default of 30 days or any duration you consider logical. + * Access scopes: Set to `repo` and `admin-repo.hook` + + {% include + image.html + lightbox="true" + file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" + url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" + alt="GitHub PAT permissions" + caption="GitHub PAT permissions" + max-width="30%" + %} + +##### Git user token +Have your GitHub user token ready with a valid expiration date and access permissions: +{::nomarkdown}{:/} + + +For detailed information on GitHub tokens, see the [GitHub article](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). + +### Shared Configuration Repository +As part of the installation, you will be required to define the Shared Configuration Repository for your account. The shared repo stores account-level configuration settings and manifests, common to all Runtimes in the account. + +Because the Shared Configuration Repo is defined at the account-level, the Git provider you select for the first Runtime in your account is used for all the other Runtimes in the same account. + +Learn more on the [Shared Configuration Repository]({{site.baseurl}}/docs/installation/gitops/shared-configuration/). + + +## Prerequisites + +### System requirements +Verify that your deployment environment meets the minimum requirements for Hybrid GitOps Runtimes. +Check the [system requirements]({{site.baseurl}}/docs/installation/gitops/hybrid-gitops-helm-installation/#minimum-system-requirements). + + +### Argo project components & CRDs +Ensure that the target cluster does not include Argo project components or Custom Resource Definitions (CRDs), such as Argo Rollouts, Argo CD, Argo Events, and Argo Workflows. + +You can handle Argo project CRDs in two ways: +* Outside the Helm chart +* Adopt the CRDs to be managed by the GitOps Runtime Helm release (recommended) + +#### Handle Argo project CRDs outside the Helm chart + +Disable CRD installation for each of the Argo projects in the Helm chart by setting the following flag:
+ `--set .crds.install=false`
+ where:
+ `` is the Argo project component to replace: `argo-cd`, `argo-workflows`, `argo-rollouts` and `argo-events`. + +See [Argo's Helm chart README](https://github.com/argoproj/argo-helm/blob/main/README.md){:target="\_blank"}. + +#### Adopt the CRDs into the Helm release +Allow the `gitops-runtime helm release` to manage CRDs for automatic upgrades whenever you upgrade the Hybrid GitOps Runtime. + +Run this script _before_ installation: + +``` +#!/bin/sh +RELEASE= +NAMESPACE= +kubectl label --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) app.kubernetes.io/managed-by=Helm +kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-name=$RELEASE +kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-namespace=$NAMESPACE +``` + + +## What's next +You are now ready to install the GitOps Runtime. + +[Quick start: Installing a Hybrid GitOps Runtime]({{site.baseurl}}/docs/quick-start/gitops-quick-start/runtime/) diff --git a/_docs/gitops-quick-start/products.md b/_docs/gitops-quick-start/products.md new file mode 100644 index 000000000..053f9dcc8 --- /dev/null +++ b/_docs/gitops-quick-start/products.md @@ -0,0 +1,43 @@ +--- +title: "Quick start: Environments, products and applications in Codefresh GitOps" +description: "Explore how to create and work with entities to promote and deploy applications" +group: gitops-quick-start +redirect_from: + - /docs/quick-start/gitops-quick-start/gitops-products/ +toc: true +--- + + +In GitOps-driven promotions with Codefresh, environments, products, and applications are the foundational entities that enable seamless deployment and lifecycle management. + +* **Environments** represent the various stages in your software delivery process, such as testing, staging, or production. Each environment serves a specific purpose, ensuring visibility into applications as they progress through development before reaching production. +For details, see [Environments dashboard]({{site.baseurl}}/docs/dashboards/gitops-environments/). + +* **Products** bridge the gap between environments and applications. By grouping and managing applications as cohesive units, products simplify coordination, enhance organization, and amplify your ability to manage complex deployments. +For details, see [About Products]({{site.baseurl}}/docs/products/about-products/). + +* **Applications** are the core building blocks of your software delivery process. They represent the deployable artifacts, services, or microservices that power your business. Managing applications effectively is essential for ensuring reliability and efficiency in production. +For details, see [Creating Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/create-application/). + +Explore these quick starts to get started with environments, products, and applications: +[Quick start: Creating environments]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/) +[Quick start: Creating products]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-create/) +[Quick start: Creating applications]({{site.baseurl}}/_docs/gitops-quick-start/products/create-app-ui/) +[Quick start: Exploring the Product Dashboard]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-dashboard/) + + + + + + + + + + + + + + + + + diff --git a/_docs/gitops-quick-start/products/create-app-ui.md b/_docs/gitops-quick-start/products/create-app-ui.md new file mode 100644 index 000000000..39aba82e2 --- /dev/null +++ b/_docs/gitops-quick-start/products/create-app-ui.md @@ -0,0 +1,180 @@ +--- +title: "Quick start: Creating applications" +description: "Create Argo CD applications in Codefresh" +group: gitops-quick-start +toc: true +redirect_from: + - docs/quick-start/gitops-quick-start/create-app-ui/ +--- + +We've created two of the three core entities essential for GitOps promotions: [Environments]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/) and [products]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-create/). +In this quick start, we'll create applications—the fundamental building blocks of software delivery. +The ultimate goal is to deploy and maintain these applications efficiently, ensuring they run reliably in production. + +In Codefresh, applications are Argo CD applications that represent the Kubernetes resources deployed and managed through GitOps principles. +* By linking applications to Git Sources, you have a centralized location from which to manage multiple manifests. +* By associating applications with products, you get an organizational layer that simplifies tracking and managing deployments throughout the software delivery lifecycle. + +For detailed information, see [Creating Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/create-application/). + + +## Key features of applications in Codefresh + + +* **GitOps-driven management** + Codefresh leverages Argo CD to ensure applications always align with their Git repository definitions, allowing declarative management and version control. + +* **Flexible creation methods** + Create applications in the Codefresh UI, imported from an existing Argo CD instance, defined programmatically using YAML, or in our intuitive Form modes. + + + +## Create your first application +We'll create an application with only the required settings for this quick start. We'll also connect the application to the product we created in the previous quick start. + +Use the Form editor or code directly in YAML. Switch between the two as you prefer. + +##### Step-by-step +1. In the Codefresh UI, from the sidebar, select **GitOps Apps**. +1. Click **Add Application** on the top-right. +1. In the Add Application panel, add definitions for the application: + * **Application name**: `demo-trioapp-dev` for the quick start. + We added `-dev` to the application name to differentiate it from other applications we'll create. + * **Runtime**: The runtime to associate with the application, `demo-runtime` for the quick start. + * **Name for YAML file**: The name of the application's configuration manifest, assigned on commit to Git. By default, the manifest is assigned the application name. + You can click the Edit icon and change the name if you want to. + + >**NOTE** + You cannot change the application definitions once you continue to the Configuration settings. + +{% include + image.html + lightbox="true" + file="/images/quick-start/apps/qs-create-app-definitions.png" + url="/images/quick-start/apps/qs-create-app-definitions.png" + alt="Applications quick start: Application definitions" + caption="Applications quick start: Application definitions" + max-width="50%" + %} + +{:start="4"} +1. Click **Next** to go to the Configuration tab. + By default you are in Form mode. You can toggle between Form and YAML modes as you define the application's configuration settings. +1. Define the **General** settings for the application: + * **Product**: From the list of products, select the product to which to connect this application, `demo-trio-gitsource` for the quick start. + * **Repository URL**: The URL to the repo in Git where you created the YAML resource files for the application. + * **Revision**: The branch in Git with the resource files. + * **Path**: The folder in Git with the resource files. + * **Namespace**: For the quick start, we'll define a namespace for the application, entitled `demo-dev`. + * **Auto-create namespace**: If you defined a namespace, select this option to ensure that the namespace is created if it doesn't exist. + * **Sync Policy**: Change to **Automatic** if needed, and select **Prune resources** to automatically remove unused resources. + + +{% include + image.html + lightbox="true" + file="/images/quick-start/apps/qs-create-app-configuration.png" + url="/images/quick-start/apps/qs-create-app-configuration.png" + alt="Applications quick start: Configuration > General settings" + caption="Applications quick start: Configuration > General settings" + max-width="70%" + %} + + +{:start="6"} +1. Retain the default **Advanced Settings**. + The only setting to note here is that we are creating a Helm application. +1. To commit all changes, select **Commit**. + The Commit form is displayed with the application's definitions on the left, and the read-only version of the manifest with the configuration settings you defined on the right. +1. Select the **Git Source** to which to commit the application's manifest. + For the quick start, we have one Git Source which we created earlier, the `demo-trio-gitsource`. + +{% include + image.html + lightbox="true" + file="/images/quick-start/apps/qs-create-app-commit-changes.png" + url="/images/quick-start/apps/qs-create-app-commit-changes.png" + alt="Applications quick start: Commit to Git Source" + caption="Applications quick start: Commit to Git Source" + max-width="60%" + %} + +{:start="9"} +1. Add a commit message and then click **Commit** at the bottom-right of the panel. + You are directed to the GitOps Apps dashboard. + You may have to wait for a few seconds until the application is synced to the cluster for it to be displayed in the dashboard. + +{% include + image.html + lightbox="true" + file="/images/quick-start/apps/qs-create-app-success.png" + url="/images/quick-start/apps/qs-create-app-success.png" + alt="Applications quick start: New application in GitOps Apps dashboard" + caption="Applications quick start: New application in GitOps Apps dashboard" + max-width="60%" + %} + +## Create additional applications +Follow the steps in [Create your first application](#create-your-first-application) to create more applications. + +One of the requirements for promotions in GitOps is to have an application in each of the environments you want to target in your promotion lifecyle. +For the quick start, since we created three environments, we'll add two more applications: `demo-trioapp-qa` and `demo-trioapp-prod`. +Remember to select the product for each of the applications. + +Here's a view of the GitOps Apps dashboard with all the three applications linked to their Git Source. + + {% include + image.html + lightbox="true" + file="/images/quick-start/apps/qs-create-app-apps-in-dashboard.png" + url="/images/quick-start/apps/qs-create-app-apps-in-dashboard.png" + alt="Applications quick start: GitOps Apps dashboard with `trio-demoapp` applications" + caption="Applications quick start: GitOps Apps dashboard with `trio-demoapp` applications" + max-width="60%" + %} + + +## View changes in Environments dashboard + +Let's return to the Environments dashboard to see how the new apps we created are displayed in it. + +* From the sidebar, select **Environments**. + + +Each environment displays the product `demo-trioapp`. +Mouse over the product name in any environment to see the associated application. + + {% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/env-with-assigned-apps.png" + url="/images/quick-start/environments-products/env-with-assigned-apps.png" + alt="Applications quick start: Environments with products" + caption="Applications quick start: Environments with products" + max-width="70%" + %} + +## View changes in Product Dashboard + +Let's also visit the Product Dashboard now that we have created applications and assigned them to the `demo-trioapp` product. + +* From the sidebar, select **Products**, and then click the product, `demo-trioapp`. + +Here's an example of the Product Dashboard for `demo-trioapp` with the applications we created for the quick start. + + + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/product-dashboard-view.png" + url="/images/quick-start/environments-products/product-dashboard-view.png" + alt="Applications quick start: Product Dashboard with product's applications" + caption="Applications quick start: Product Dashboard with product's applications" + max-width="60%" +%} + +## What's next +Explore the Product Dashboard to uncover insights about your product and its applications. + +[Quick start: Exploring the Product Dashboard]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-dashboard/) diff --git a/_docs/gitops-quick-start/products/quick-start-gitops-environments.md b/_docs/gitops-quick-start/products/quick-start-gitops-environments.md new file mode 100644 index 000000000..db60003f8 --- /dev/null +++ b/_docs/gitops-quick-start/products/quick-start-gitops-environments.md @@ -0,0 +1,107 @@ +--- +title: "Quick start: Creating Environments" +description: "Explore how environments empower application promotion and deployment" +group: gitops-quick-start +toc: true +--- + +In the previous quick start, you [created a Git Source]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-create/) for the GitOps Runtime. In this quick start, we'll focus on creating ennvironments in preparation for promoting and deploying applications. + +Environments are essential for managing the lifecycle of your applications as they move from development to production. Whether it’s a testing environment, a staging area, or production itself, each environment serves a unique purpose in the software delivery process. + +In the context of **promotions with Codefresh GitOps**, environments aren’t just configurations—they’re actionable entities. They give you an intuitive way to organize, track, and promote applications, ensuring consistency and clarity across your delivery lifecycle. +Environments are tightly integrated with GitOps principles, ensuring that your infrastructure and applications are always in sync with declarative configurations stored in Git. + + {% include + image.html + lightbox="true" + file="/images/gitops-environments/argo-apps-organized-into-envs.png" + url="/images/gitops-environments/argo-apps-organized-into-envs.png" + alt="Quick start: Representation of an Environment in Codefresh GitOps" + caption="Quick start: Representation of an Environment in Codefresh GitOps" + max-width="60%" +%} + +For detailed information, see [Environments]({{site.baseurl}}/docs/dashboards/gitops-environments/). + +## Why create environments? + +Environments are key to managing and promoting applications effectively. +They give you a structured, intuitive way to answer the question: _What’s running where?_ + +Here are just a few of the reasons you’ll want to use environments in Codefresh: + +* **Mirror your SDLC** + Environments are designed to mirror your software development life cycle (SDLC). By aligning applications with their development stages, environments offer a clear and contextual view of the entire application lifecycle, as it moves from development to production. + +* **Simplify promotions** + Environments make promoting applications between stages seamless. By organizing applications into environments, you always know what’s ready for the next stage, reducing confusion and ensuring consistency. + +* **Effortless creation** + Creating an environment in Codefresh is simple. Just provide a unique name, and map clusters and namespaces. + + {% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/environments-example.png" + url="/images/quick-start/environments-products/environments-example.png" + alt="Quick start: Environments in Codefresh GitOps" + caption="Quick start: Environments in Codefresh GitOps" + max-width="60%" +%} + + +## Create an Environment +Let's go ahead and create an environment. + +Environments mirror the deployment lifecycle of your software, so create as many as you need to match your process. +Common examples include `development`, `qa`, `staging`, and `production`, but you can customize environments to fit your needs. There's no cap on the number of environments you can create. + +For this quick start, we'll create three environments, `dev`, `qa`, and `prod`. + +1. In the Codefresh UI, from the sidebar, select **Environments**, and then click **Add Environment**. +1. Define the following: + 1. **Name**: A unique name for your environment, which is meaningful in the context of your development and deployment cycle. + For the quick start, we'll use `dev`. + 1. **Kind**: The purpose of the environment. Select **Non-production** where typically development, testing, and staging versions of applications are deployed. + The **Kind** property is used to also define rules for promotions and ABAC (Attribute Based Access Control) permissions. + 1. **Tags**: Leave this empty for the quick start. + 1. **Clusters and Namespaces**: Single or multiple clusters, namespaces, or cluster-namespace pairs, to map to the environment. + To include all namespaces in a cluster, leave the Namespace empty. + For the quick start, we'll add the `in-cluster` and the `demo-dev` namespace. + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/environment-add.png" + url="/images/quick-start/environments-products/environment-add.png" + alt="Environments quick start: Create an Environment" + caption="Environments quick start: Create an Environment" + max-width="50%" +%} + +{:start="3"} +1. Click **Add**. + The environment is displayed in the Environments dashboard. +1. Repeat _step 1_ through _step 3_ to create the two other environments: `qa` and `prod`. + For the quick start, both environments are mapped to `in-cluster`, and to namespaces, `demo-qa` and `demo-prod` respectively. + +Here's an example of the Environments dashboard with the three environments. +The environments are automatically populated with the applications in the clusters and namespaces mapped to them. +At this point, as we haven't created any applications, all environments are empty. + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/envs-no-apps.png" + url="/images/quick-start/environments-products/envs-no-apps.png" + alt="Environments quick start: Newly created environments without applications" + caption="Environments quick start: Newly created environments without applications" + max-width="60%" +%} + +## What's next +You’re probably eager to dive into applications. Before we do that let's create another entity that simplifies and supercharges applications: Products. + + +[Quick start: Creating products]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-create/) \ No newline at end of file diff --git a/_docs/gitops-quick-start/products/quick-start-product-create.md b/_docs/gitops-quick-start/products/quick-start-product-create.md new file mode 100644 index 000000000..fbf34018c --- /dev/null +++ b/_docs/gitops-quick-start/products/quick-start-product-create.md @@ -0,0 +1,93 @@ +--- +title: "Quick start: Creating products" +description: "Create products to group and manage related applications" +group: gitops-quick-start +toc: true +--- + + +In the previous quick start we [created environments]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/), one of the three core entities essential for GitOps promotions. Now, it’s time to create another core entity: Products. + +Products not only bridge the gap between environments and applications but also amplify the capabilities of your applications by grouping and managing them as cohesive units. + +{% include + image.html + lightbox="true" + file="/images/gitops-products/apps-grouped-by-product.png" + url="/images/gitops-products/apps-grouped-by-product.png" + alt="Products quick start: Representation of a product in Codefresh GitOps" + caption="Products quick start: Representation of a product in Codefresh GitOps" + max-width="60%" +%} + +For detailed information, see [Products]({{site.baseurl}}/docs/products/about-products/). + +## Why create products? + +Here are a few reasons why you would want to create products to manage your applications. + + + +* **Bridging applications and environments** + Products create a vital link between applications and their environments. By grouping applications within a product, you gain visibility and control over their deployment paths, ensuring all components move through environments together. + + +* **Unified application promotion and deployment** + Managing individual Argo CD applications across multiple environments can become complex. Products simplify this by grouping related applications, enabling efficient, cohesive management and promotion. + + +* **Effortless creation** + Creating a product is as simple as creating an environment. You can do so directly from the UI, declaratively by annotating application manifests, or even when creating applications themselves. + + + +## Create your first product +A product requires a unique name, and an annotation through which to connect the different applications. + +##### Before you begin +* Make sure you have at least [one environment]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/) + + +##### Step-by-step + +1. In the Codefresh UI, from the sidebar, select **Products**. +1. Click **Add Product**. +1. Define the following: + 1. **Name**: A unique name for the Product, `demo-trioapp` for the quick start. + 1. **Connect Applications**: Displays the annotation associated with this product that is automatically created, and used to connect the different applications to it. In our case, `codefresh.io/product: demo-trioapp`. + 1. **Tags**: Leave this empty for the quick start. + + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/products-create.png" + url="/images/quick-start/environments-products/products-create.png" + alt="Products quick start: Create product" + caption="Products quick start: Create product" + max-width="50%" +%} + +{:start="4"} +1. Click **Add**. + The Product is displayed in the Products page. +1. Click the product name to see the dashboard for the individual product. + You'll notice that the product currently has no applications assigned to it. + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/products-no-apps-assigned.png" + url="/images/quick-start/environments-products/products-no-apps-assigned.png" + alt="Products quick start: Product with no applications" + caption="Products quick start: Product with no applications" + max-width="60%" +%} + + + +## What's next +After creating two of the three core entities for GitOps promotions, environments and products, we are ready to dive into applications. + +[Quick start: Creating applications]({{site.baseurl}}/docs/gitops-quick-start/products/create-app-ui/) + diff --git a/_docs/gitops-quick-start/products/quick-start-product-dashboard.md b/_docs/gitops-quick-start/products/quick-start-product-dashboard.md new file mode 100644 index 000000000..4e95b3037 --- /dev/null +++ b/_docs/gitops-quick-start/products/quick-start-product-dashboard.md @@ -0,0 +1,135 @@ +--- +title: "Quick start: Exploring the Product Dashboard" +description: "Gain insights into applications, versions, and deployment details" +group: gitops-quick-start +toc: true +--- + +In the previous quick start, we [created applications]({{site.baseurl}}/docs/gitops-quick-start/products/create-app-ui/) and assigned them to the same product. + +Let's explore the Product Dashboard to see how these come together. The dashboard offers a consolidated view of your product's applications in their environments, including the application release versions, dependencies, and integrated insights from Kubernetes, Git, and issue-tracking tools. + + + +Here's an example of the Product Dashboard with the applications we created for the quick start. + + + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/product-dashboard-view.png" + url="/images/quick-start/environments-products/product-dashboard-view.png" + alt="Product Dashboard quick start: Explore Product Dashboard" + caption="Product Dashboard quick start: Explore Product Dashboard" + max-width="60%" +%} + + + +For this quick start, we'll focus on two key features: release versions and integrated insights into applications. + +## Identifying release versions in product applications + +The release version displayed for each application signifies the specific version of the application that is currently deployed. For detailed information, see [Configuring app version for promotions]({{site.baseurl}}/docs/products/promotion-version-properties/#configuring-versions-for-promoted-applications). + +**Why is this important?** +Knowing the release version at a glance helps you quickly identify which version of an application is deployed in each environment. This is crucial for ensuring consistency, troubleshooting, and managing deployments effectively. + +In the example below, `dev` has a different version of the application compared to `qa` and `prod`. + + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/product-dashboard-view.png" + url="/images/quick-start/environments-products/product-dashboard-view.png" + alt="Product Dashboard quick start: Release versions of application/product in environments" + caption="Product Dashboard quick start: Release versions of application/product in environments" + max-width="60%" +%} + +You can use the integrated insights in the Product Dashboard—such as Git commit history and feature tracking—to evaluate the changes. Based on this information, you can decide whether to promote the changes and the version across environments, which is covered in the next set of quick starts. + +Additionally, you can: + +* **View application dependencies and their versions** + This helps trace which versions of dependencies are included in a particular deployment. +* **Compare dependency versions across environments** + For example, you can verify whether the version deployed in a staging environment matches the one in production, which is useful for identifying inconsistencies or issues in specific environments. + + +### View dependencies +1. Click the version to display the application's dependencies. + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/products-app-version-number.png" + url="/images/quick-start/environments-products/products-app-version-number.png" + alt="Products quick start: Versions for application dependencies" + caption="Products quick start: Versions for application dependencies" + max-width="50%" +%} + + +### Compare deployed versions across applications +Compare the dependency versions in the different applications associated with the Product. + +1. In the same panel, enable **Compare**. +1. Click within the field **Select applications to compare**, and select the applications. + * For up to two applications, switch between **YAML** and **Table** views. + * For more than two applications, the comparison view automatically switches to **Table**. + +In this quick start, dependency versions are identical across all three applications. + +{% include + image.html + lightbox="true" + file="/images/quick-start/environments-products/products-app-version-compare.png" + url="/images/quick-start/environments-products/products-app-version-compare.png" + alt="Products quick start: Dependency versions across applications" + caption="Products quick start: Dependency versions across applications" + max-width="60%" +%} + +## Integrated insights into product's applications + +Products offer enriched insights into your applications, more than just standard Git commit or hash information. + +When you select a product, the Product Dashboard displays three tabs on the right: **Pods**, **Git**, and **Features**. These tabs consolidate Kubernetes (Pods), version control (Git), and issue-tracking (Features) data into a single location. + +**Why are these insights crucial?** +When troubleshooting issues in production, having access to such comprehensive information is invaluable. You can pinpoint what occurred, when it happened, who made the change, and which feature or bug was addressed, streamlining your debugging process. + +From this unified view, you can: +* Gain insights into deployment specifics +* Review all commits leading up to the latest one that triggered the deployment +* Align deployed features with related feature requests +* Effectively track deployment timelines + +### Tabs overview + +##### Pods +Shows live Kubernetes data, including pod status and health. + +##### Git +Provides _direct insights from the application's source repository, including the complete commit history up to the commit that initiated the build and deployed the new version, and deep links to source control. + +##### Features +Maps commits to tickets in your issue-tracking tool, offering traceability for deployed features or bug fixes. + + +### Requirement: Integrate CI platforms/tools +For the Git and Features tabs to work seamlessly, ensure your CI/CD systems are integrated. If you have CI platforms/tools already in place, be it Codefresh pipelines, GitHub Actions, or Jenkins, you can integrate them with Codefresh GitOps. The same applies to issue-tracking tools like Jira. + +For setup instructions, see [Image enrichments with GitOps integrations]({{site.baseurl}}/docs/gitops-integrations/image-enrichment-overview/). + +## What's next? +We'll dive into how to promote changes and deploy applications across environments using the entities you've created and worked with: Environments, products, and applications. +For an overview on promotions, read [Quick start: Promotions in Codefresh GitOps]({{site.baseurl}}/docs/gitops-quick-start/promotions/). + +Let's move on to the first quick start on promotions to see this in action. + +[Quick start: Drag-and-drop promotion]({{site.baseurl}}/docs/gitops-quick-start/promotions/drag-and-drop/) + diff --git a/_docs/gitops-quick-start/promotions.md b/_docs/gitops-quick-start/promotions.md new file mode 100644 index 000000000..ab85b5fd1 --- /dev/null +++ b/_docs/gitops-quick-start/promotions.md @@ -0,0 +1,48 @@ +--- +title: "Quick start: Promotions in Codefresh GitOps" +description: "Explore basic & advanced promotion scenarios" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/promotions/promotion-scenarios/ +--- + + +Promotions orchestrate the flow of changes for applications across environments, ensuring controlled and validated deployments. +A successful promotion sequence relies on several key components that together govern and orchestrate the promotion flow across environments. + +This series of quick starts on promotions guide you through the different promotion scenarios, from basic to advanced. + + +## Core entities for all promotion scenarios +Every promotion scenario relies on three foundational entities: + +* **Applications** + Represent deployable services or microservices. + +* **Products** + Group and manage related applications, enabling consistent configuration and visibility. + +* **Environments** + Define where changes are promoted, representing distinct deployment stages like development, staging, or production. + +These entities form the basis of your deployment structure. With them in place, you can initiate basic promotions, such as moving changes between environments using a simple drag-and-drop method. + +## Promotion-specific +To enable more advanced deployment strategies, promotions have additional unique entities: + +* **Promotion Flows** + After setting up the basic entities, orchestrate promotions for applications across multiple environments. + Use our Promotion Flow builder to create automated, complex, multi-environment deployment strategies. + +* **Promotion Workflows** + Introduce gates in the promotion process through Promotion Workflows, another entity unique to promotions in GitOps. + Through Promotion Workflows, you can create and implement any type of tests to validate readiness, enforce compliance, mitigate risks, and confirm performance. + +Explore these quick starts on promotions: +* [Drag-and-drop promotions]({{site.baseurl}}/docs/gitops-quick-start/promotions/drag-and-drop/) +* [Multi-environment sequential promotion]({{site.baseurl}}/docs/gitops-quick-start/promotions/multi-env-sequential-flow/) +* [Multi-environment promotion with gates]({{site.baseurl}}/docs/gitops-quick-start/promotions/policy-multi-env-promotion/) +* [Multi-environment promotion with parallel environments]({{site.baseurl}}/docs/gitops-quick-start/promotions/parallel-multi-env-promotion/) +* [Multi-environment promotion with dependencies]({{site.baseurl}}/docs/gitops-quick-start/promotions/dependency-multi-env-promotion/) + diff --git a/_docs/gitops-quick-start/promotions/dependency-multi-env-promotion.md b/_docs/gitops-quick-start/promotions/dependency-multi-env-promotion.md new file mode 100644 index 000000000..1ad151f88 --- /dev/null +++ b/_docs/gitops-quick-start/promotions/dependency-multi-env-promotion.md @@ -0,0 +1,100 @@ +--- +title: "Quick start: Multi-environment promotion with dependencies" +description: "Promote product apps between environments with dependencies" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/promotions/promotion-scenarios/dependency-multi-env-promotion/ +--- + + +In the final quick start, we’ll explore how to create dependencies between environments in a Promotion Flow. + +By default, each environment in a promotion flow (except the trigger environment), is dependent on the one preceding it. +However, critical environments may rely on the success or stability of multiple environments before they are promoted to. By defining additional dependencies, you can ensure that changes are promoted only when all required environments meet the specified criteria. + +In this quick start, we'll update the `multi-env-sequential-promotion` Promotion Flow. + + + +## Add dependency to Promotion Flow +Update the dependency on the `prod` environment, by selecting `staging` in addition to `qa`. + +1. From the list of Promotion Flows, open `multi-env-sequential-promotion`. + In the example, we have already added the `staging` environment as a parallel environment to `qa`. +1. Mouse over the environment for which to add the dependency (`prod`), and click **Depends on**. +1. Select the additional environment, `staging` for the quick start, and then click **Update dependency**. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dependency-update.png" +url="/images/quick-start/promotions/quick-start-dependency-flow.png" +alt="Promotions quick start: Update dependencies for environment" +caption="Promotions quick start: Update dependencies for environment" +max-width="60%" +%} + + +Here's the `multi-env-sequential-promotion` Promotion Flow with the updated dependency. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dependency-flow.png" +url="/images/quick-start/promotions/quick-start-dependency-flow.png" +alt="Promotions quick start: Chart view of Promotion Flow with updated dependencies" +caption="Promotions quick start: Chart view of Promotion Flow with updated dependencies" +max-width="60%" +%} + +Here's the YAML view of the same flow with the updated dependency. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dependency-flow-yaml.png" +url="/images/quick-start/promotions/quick-start-dependency-flow-yaml.png" +alt="Promotions quick start: YAML view of Promotion Flow with updated dependencies" +caption="Promotions quick start: YAML view of Promotion Flow with updated dependencies" +max-width="60%" +%} + +{:start="4"} +1. Continue with [Trigger and view product release with dependencies](#trigger-and-view-product-release-with-dependencies). + +## Trigger and view product release with dependencies +Triggering a Promotion Flow with dependencies promotes changes to the target environment only after all dependent environments are successfully promoted. + +1. Open the `multi-env-sequential-promotion` Promotion Flow and click **Trigger**. +1. Select the product, the application to promote, and then click **Trigger** once again. +1. Click **View Release Details**. + +The Release view displays the dependencies in the Promotion Flow, showing that promotion to `prod` is contingent on the successful promotion of both `qa` and `staging`. +In this example, while `qa` has been promoted successfully, `staging` is still pending promotion, preventing `prod` from starting its promotion. + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dependency-flow-release-view.png" +url="/images/quick-start/promotions/quick-start-dependency-flow-release-view.png" +alt="Promotions quick start: Release view of Promotion Flow with dependencies" +caption="Promotions quick start: Release view of Promotion Flow with dependencies" +max-width="60%" +%} + +Congratulations! You've completed the final quick start in the Promotion series! + +By now, you’ve successfully created environments, your first product, added applications, and promoted them across environments. These foundational steps empower you to manage complex promotions confidently and effectively. + +## Related articles +Now that you’ve mastered the basics, learn more on promotion settings for products and configuring promotion entities. +[Configuring version and promotable properties for products]({{site.baseurl}}/docs/products/promotion-version-properties/) +[Configuring promotion flows and triggers for products]({{site.baseurl}}/docs/products/promotion-flow-triggers/) +[Configuring promotion entities]({{site.baseurl}}/docs/promotions/entities/) + + + + + \ No newline at end of file diff --git a/_docs/gitops-quick-start/promotions/drag-and-drop.md b/_docs/gitops-quick-start/promotions/drag-and-drop.md new file mode 100644 index 000000000..e752e9047 --- /dev/null +++ b/_docs/gitops-quick-start/promotions/drag-and-drop.md @@ -0,0 +1,124 @@ +--- +title: "Quick start: Drag-and-drop promotion" +description: "Promote product apps between two environments" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/promotions/promotion-scenarios/drag-and-drop/ +--- + +In this first quick start on promotions, we'll see how to promote products using the intuitive drag-and-drop functionality in the Environments dashboard. + +This quick, visual method allows you to manually move applications between two environments in just a few steps. + +Use this method when you want to: +* Quickly test changes in a different environment +* Manually promote a product version for validation or further deployment + +## Before you begin +If you haven't done so already, create: +* [Environments]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-gitops-environments/) +* [Products]({{site.baseurl}}/docs/gitops-quick-start/products/quick-start-product-create/) +* [Applications]({{site.baseurl}}/docs/gitops-quick-start/products/create-app-ui/) + +## Promote product applications through drag-and-drop + +1. From the sidebar, select **Environments**. + * The `demo-trioapp` product is displayed in the `dev`, `qa`, and `prod` environments. + * Note the release versions for the product in each environment. + For example, the version in `dev` is different from those in `qa` and `prod`, indicating changes to the application that have not yet been deployed to all environments. + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dnd-prod-in-env.png" +url="/images/quick-start/promotions/quick-start-dnd-prod-in-env.png" +alt="Promotions quick start: `demo-trioapp` product in Environments dashboard" +caption="Promotions quick start: `demo-trioapp` product in Environments dashboard" +max-width="60%" +%} + +{:start="2"} +1. To view the applications linked to the product `demo-trioapp` in each environment, mouse over the product name in each of the environments. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/qucik-start-dnd-apps-in-prod.png" +url="/images/quick-start/promotions/qucik-start-dnd-apps-in-prod.png" +alt="Promotions quick start: `demo-trioapp-dev` and `demo-trioapp-qa` applications" +caption="Promotions quick start: demo-trioapp-dev` and `demo-trioapp-qa` applications" +max-width="60%" +%} + +{:start="3"} +1. Drag and drop the application into the desired target environment. + For the quick start, we'll promote `demo-trioapp` by dragging `demo-trioapp-dev` from `dev` and dropping it into `demo-trioapp` in the `qa` environment. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dnd-action.png" +url="/images/quick-start/promotions/quick-start-dnd-action.png" +alt="Promotions quick start: Drag and drop `demo-trioapp-dev` to promote" +caption="Promotions quick start: Drag and drop `demo-trioapp-dev` to promote" +max-width="60%" +%} + +{:start="4"} +1. Click **Commit** to commit the changes. + The Commit Changes page displays details about the promotion, including the action used, the files impacted, and the properties being updated. + + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/tutorials/dnd-commit.png" +url="/images/gitops-promotions/tutorials/dnd-commit.png" +alt="Promotions quick start: Commit changes for `demo-trioapp`" +caption="Promotions quick start: Commit changes for `demo-trioapp`" +max-width="60%" +%} + +{:start="5"} +1. Review the changes carefully and click **Promote**. +1. Continue with [View release created for product](#view-release-created-for-product). + + +## View release created for product +After committing the changes, the promotion mechanism automatically creates a release for the product, `demo-trioapp` in our case. +Here you can monitor how the promotion is orchestrated between the environments `dev` and `qa`. + +* Click **View Release Details** to go to the release view and monitor the release as it progresses between the `dev` and `qa` environments. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dnd-ongoing-release.png" +url="/images/quick-start/promotions/quick-start-dnd-ongoing-release.png" +alt="Promotions quick start: On-going release for `demo-trioapp`" +caption="Promotions quick start: On-going release for `demo-trioapp`" +max-width="60%" +%} + +When the release completes execution, go to **Product > Releases** to see the information and status for the release. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-dnd-releases-page.png" +url="/images/quick-start/promotions/quick-start-dnd-releases-page.png" +alt="Promotions quick start: Releases list with release record for `demo-trioapp`" +caption="Promotions quick start: Releases list with release record for `demo-trioapp`" +max-width="60%" +%} + + +## What's next +Now that you've learned how to promote a product using the drag-and-drop method, we'll explore more advanced promotion scenarios. +The next quick start demonstrates how to orchestrate a multi-environment promotion through a Promotion Flow, enabling you to automate and streamline deployments across more than two environments. + +[Quick start: Multi-environment sequential promotion]({{site.baseurl}}/docs/gitops-quick-start/promotions/multi-env-sequential-flow/) + + diff --git a/_docs/gitops-quick-start/promotions/multi-env-sequential-flow.md b/_docs/gitops-quick-start/promotions/multi-env-sequential-flow.md new file mode 100644 index 000000000..197514afc --- /dev/null +++ b/_docs/gitops-quick-start/promotions/multi-env-sequential-flow.md @@ -0,0 +1,210 @@ +--- +title: "Quick start: Multi-environment sequential promotion" +description: "Promote product apps between multiple environments sequentially" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/promotions/promotion-scenarios/multi-env-sequential-flow/ +--- + + +[Drag-and-drop promotion]({{site.baseurl}}/docs/gitops-quick-start/promotions/drag-and-drop/), covered in the previous quick start, is ideal for on-demand promotions to a single environment. In contrast, sequential promotion flows offer a structured approach to managing changes across multiple environments, minimizing deployment risks. + +This quick start demonstrates creating a promotion flow with three environments (`dev`, `qa`, `prod`), triggering the flow, and monitoring its progress in the Releases view. + + +## Before you begin + +For this quick start, ensure that you have: + +* Three environments + For multi-environment promotions, you need at least three environments. + Here we use `dev`, `qa`, and `prod`. + +* Application in each environment + Each environment must have an application for the product, such as `demo-trioapp-dev`, `demo-trioapp-qa`, and `demo-trioapp-prod`. + +* Consistent repo structure for applications + The structure of the repos with the resources must be consistent across all the three applications. + + +## Create Promotion Flow for multi-environment promotions + +Codefresh simplifies creating multi-environment promotion sequences through Promotion Flows. +You can use the Flow Builder in either Chart or YAML modes depending on your preference to create a Promotion Flow. + +>**NOTE** +You need to be an account administrator to create Promotion Flows. + + +1. In the Codefresh UI, on the toolbar, click the **Settings** icon. +1. From the sidebar select **Promotion Flows**, and then click **Add Promotion Flow**. +1. Enter the settings for the Promotion Flow: + * **Name**: The name for the flow. For this quick start, we'll use `multi-env-sequential-promotion`. + * **Description**: (Optional) More information about the purpose of the Promotion Flow. + * **Flow Timeout**: The maximum duration allowed for the Promotion Flow to complete execution after being triggered, before it is automatically terminated. If not specified, the default timeout is 1 day (24 hours). For this quick start, we'll set it to `5 minutes`. + * **Version**: (Optional) The version of the Promotion Flow. This is manually defined and manually updated, and is useful to indicate changes in the same flow. For the quick start, we'll set it to `1.0`. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-settings.png" +url="/images/quick-start/promotions/quick-start-seq-promo-settings.png" +alt="Promotions quick start: Define Promotion Flow settings" +caption="Promotions quick start: Define Promotion Flow settings" +max-width="60%" +%} + +{:start="4"} +1. Click **>** to close the panel. +1. Select the **Trigger Environment** as the starting point for the promotion. For the quick start, select `dev`. + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-trigger-env.png" +url="/images/quick-start/promotions/quick-start-seq-promo-trigger-env.png" +alt="Promotions quick start: Select Trigger Environment" +caption="Promotions quick start: Select Trigger Environment" +max-width="60%" +%} + +{:start="6"} +1. Select the target environments in the promotion sequence to which to promote changes: `qa` and `prod`. + 1. Mouse over the right of the `dev` environment node and click {::nomarkdown}{:/}. + 1. From the list, select the first target environment in the flow, `qa` for this quick start. + 1. Repeat the action on the `qa` environment node to add the next target environment. + For the quick start, we'll add `prod` as the final target environment in the flow. + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-target-env.png" +url="/images/quick-start/promotions/quick-start-seq-promo-target-env.png" +alt="Promotions quick start: Add target environment" +caption="Promotions quick start: Add target environment" +max-width="60%" +%} + + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-all-envs.png" +url="/images/quick-start/promotions/quick-start-seq-promo-all-envs.png" +alt="Promotions quick start: Promotion Flow with required environments" +caption="Promotions quick start: Promotion Flow with required environments" +max-width="60%" +%} + +{:start="5"} +1. Click **Save Promotion Flow** on the top-right. + The Name and Description are populated from the Settings. The flow's YAML version on the right lists the environment sequence. + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-save-flow.png" +url="/images/quick-start/promotions/quick-start-seq-promo-save-flow.png" +alt="Promotions quick start: Save Promotion Flow" +caption="Promotions quick start: Save Promotion Flow" +max-width="60%" +%} + +{:start="6"} +1. To add the new flow to the Promotion Flows list, click **Save**. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-flow-list.png" +url="/images/quick-start/promotions/quick-start-seq-promo-flow-list.png" +alt="Promotions quick start: Promotion Flow list with new flow" +caption="Promotions quick start: Promotion Flow page with new flow" +max-width="60%" +%} + + +{:start="7"} +1. Continue with [Trigger Promotion Flow](#trigger-promotion-flow). + +## Trigger Promotion Flow +Manually trigger the Promotion Flow to promote changes from the Trigger Environment to the defined target environments. + + +1. From the list of Promotion Flows, select `multi-env-sequential-promotion` and then click **Trigger** to initiate the promotion. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-trigger.png" +url="/images/quick-start/promotions/quick-start-seq-promo-trigger.png" +alt="Promotions quick start: Trigger selected Promotion Flow" +caption="Promotions quick start: Trigger selected Promotion Flow" +max-width="60%" +%} + +{:start="2"} +1. Select the product to promote. For this quick start, select `demo-trioapp`, and continue by clicking **Next**. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-trigger-select-product.png" +url="/images/quick-start/promotions/quick-start-seq-promo-trigger-select-product.png" +alt="Promotions quick start: Select product to promote" +caption="Promotions quick start: Select product to promote" +max-width="50%" +%} + +{:start="3"} +1. Select the application with the changes to promote. In our case, the application `demo-trioapp-dev` is automatically selected. +1. To initiate the promotion, click **Trigger**. +1. Continue with [View and monitor product release](#view-and-monitor-product-release). + + + + +## View and monitor product release +On triggering the flow, the promotion mechanism automatically creates a new release for the product (`demo-trioapp`), and orchestrates the changes sequentially through the environments defined in the Promotion Flow. + +* Click **View Release Details** to go to the release view and monitor the sequential progression of changes through `dev`, `qa`, and `prod` as per the `multi-env-sequential-promotion` Promotion Flow. + + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-release-view.png" +url="/images/quick-start/promotions/quick-start-seq-promo-release-view.png" +alt="Promotions quick start: Release view for triggered Promotion Flow" +caption="Promotions quick start: Release view for triggered Promotion Flow" +max-width="60%" +%} + +##### Release record in releases list + +In the Releases page, the Promotion Flow column displays the name of the flow (`multi-env-sequential-promotion` for example) for traceability. For drag-and-drop promotions in contrast, this column displays Manual. + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-release-list.png" +url="/images/quick-start/promotions/quick-start-seq-promo-release-list.png" +alt="Promotions quick start: Release list with release record for triggered Promotion Flow" +caption="Promotions quick start: Release list with release record for triggered Promotion Flow" +max-width="60%" +%} + +## What's next +To further enhance your promotion flow, the next quick start will guide you through adding gates to each environment for conditional promotions, allowing you to introduce more control and flexibility in your promotion processes. + +[Quick start: Multi-environment promotion with gates]({{site.baseurl}}/docs/gitops-quick-start/promotions/policy-multi-env-promotion/) + + + \ No newline at end of file diff --git a/_docs/gitops-quick-start/promotions/parallel-multi-env-promotion.md b/_docs/gitops-quick-start/promotions/parallel-multi-env-promotion.md new file mode 100644 index 000000000..2d34187d1 --- /dev/null +++ b/_docs/gitops-quick-start/promotions/parallel-multi-env-promotion.md @@ -0,0 +1,118 @@ +--- +title: "Quick start: Multi-environment parallel promotion" +description: "Promote product apps between environments in parallel" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/promotions/promotion-scenarios/parallel-multi-env-promotion/ +--- + + +In this quick start, we'll learn how to configure parallel promotions across multiple environments. + +Parallel promotions are ideal for scenarios like multi-region deployments, where updates must be promoted simultaneously to designated regions before proceeding to a production environment. + +We’ll modify the `multi-env-sequential-promotion` flow to include parallel environments, saving it as a new flow called `multi-env-parallel`. + +## Before you begin +* Ensure you have an existing product deployed to more than one production environment. + For example, the `demo-trioapp` product in this quick start is deployed to multiple production environments. +* If necessary, add at least two applications to two different production environments before proceeding. + + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-parallel-dashboard-view.png" +url="/images/quick-start/promotions/quick-start-parallel-dashboard-view.png" +alt="Promotions quick start: Product with applications in multiple production environments" +caption="Promotions quick start: Product with applications in multiple production environments" +max-width="60%" +%} + + +## Add parallel environments to Promotion Flow + +We'll enhance the Promotion Flow by adding multiple environments to execute promotions in parallel. + +For this example, we’ll add `prod-asia` and `prod-eu` as additional production environments to `qa`. + +1. Open the Promotion Flow you created, `multi-env-sequential-promotion` for the quick start. +1. Open the Settings panel: + * **Name**: Change the name to create a new Promotion Flow, `multi-env-parallel-promotion`. + * **Version**: Change the version to 1.00. +1. Mouse over the right of the environment node before the final one in the flow and add the new environments. + For the quick start, we'll add `prod-eu` and `prod-asia` to `qa`. + + {% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-parallel-add-envs.png" +url="/images/quick-start/promotions/quick-start-parallel-add-envs.png" +alt="Promotions quick start: Adding parallel environments in Promotion Flow" +caption="Promotions quick start: Adding parallel environments in Promotion Flow" +max-width="60%" +%} + +{:start="4"} +1. Click **Save Promotion Flow**. + + +Below are the Chart and YAML views of the Promotion Flow. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-parallel-chart-view.png" +url="/images/quick-start/promotions/quick-start-parallel-chart-view.png" +alt="Promotions quick start: Chart view of Promotion Flow with parallel environments" +caption="Promotions quick start: Chart view of Promotion Flow with parallel environments" +max-width="60%" +%} + + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-parallel-envs-yaml-view.png" +url="/images/quick-start/promotions/quick-start-parallel-envs-yaml-view.png" +alt="Promotions quick start: YAML view of Promotion Flow with parallel environments" +caption="Promotions quick start: YAML view of Promotion Flow with parallel environments" +max-width="60%" +%} + +{:start="5"} +1. Continue with [Trigger and view product release for parallel environment promotion](#trigger-and-view-product-release-for-parallel-environment-promotion). + +## Trigger and view product release for parallel environment promotion + +Triggering a Promotion Flow with parallel environments promotes changes simultaneously across all defined parallel environments. +The release is considered successful only after all environments are promoted successfully. + +1. Open the `multi-env-parallel-promotion` Promotion Flow and click **Trigger**. +1. Select the product, the application to promote, and then click **Trigger** once again. +1. Click **View Release Details**. + +The Release view displays the parallel structure of the Promotion Flow, with simultaneous promotions across `prod`, `prod-eu`, and `prod-asia`. + + + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-parallel-release-view.png" +url="/images/quick-start/promotions/quick-start-parallel-release-view.png" +alt="Promotions quick start: Release view of Promotion Flow with parallel environments" +caption="Promotions quick start: Release view of Promotion Flow with parallel environments" +max-width="60%" +%} + +## What's next +The final quick start in this series will guide you through creating dependencies between environments to define the order for promotions. + +[Quick start: Multi-environment promotion with dependencies]({{site.baseurl}}/docs/gitops-quick-start/promotions/dependency-multi-env-promotion/) + + + \ No newline at end of file diff --git a/_docs/gitops-quick-start/promotions/policy-multi-env-promotion.md b/_docs/gitops-quick-start/promotions/policy-multi-env-promotion.md new file mode 100644 index 000000000..f756d7a82 --- /dev/null +++ b/_docs/gitops-quick-start/promotions/policy-multi-env-promotion.md @@ -0,0 +1,124 @@ +--- +title: "Quick start: Multi-environment promotion with gates" +description: "Promote product apps between multiple environments with promotion conditions" +group: gitops-quick-start +toc: true +redirect_from: + - /docs/promotions/promotion-scenarios/policy-multi-env-promotion/ +--- + + +Now that we have covered [Multi-environment sequential promotion]({{site.baseurl}}/docs/promotions/promotion-scenarios/multi-env-sequential-flow/), let's move on to configuring conditions for promotions, ensuring that each environment’s specific requirements are met before changes are promoted. + +Codefresh makes it easy to automate and enforce gates throughout your promotion processes using Promotion Workflows. +Promotion Workflows are essentially Argo Workflows customized for promoting changes through your environments. +For detailed information, see [Configuring Promotion Workflows]({{site.baseurl}}/docs/promotions/entities/promotion-workflow/). + +## Promotion Workflows for promotion gates +Promotion Workflows are designed to define the conditions under which changes are promoted to the next environment. They provide a way to automate testing, quality checks, validation, and any other requirements based on your deployment process, establishing gates that control the flow of changes between environments. + +You can create workflows tailored to the specific tasks required during a promotion and categorize them based on the stage of the promotion process in which they are executed, as Pre- and Post-Action Workflows. + +##### Pre-Action Workflow +A Promotion Workflow that runs _before the promotion action is triggered_. These workflows can be used for tasks like smoke tests, unit tests, security scans, or any other validation that must pass before a change is promoted to the next environment. + +The Pre-Action Workflow plays a critical role in ensuring that changes meet all necessary requirements before being promoted to the next environment. It acts as the gatekeeper, validating changes and stopping the promotion if any tests or validations fail. + + +##### Post-Action Workflows +A Promotion Workflow that runs _after the promotion action has completed_. These workflows can be used for tasks like performance monitoring, database migrations, or notifications to inform stakeholders that the promotion is complete. + +The Post-Action Workflow allows you to monitor and verify the effects of the promotion after it has taken place. This workflow helps ensure the promoted changes behave as expected in the new environment. + + + +## Assign Pre- and Post-Action Workflows to environments in Promotion Flow + +To ensure each environment's specific requirements are met, assign workflows to govern promotion behavior. + +In this quick start, we’ll define the Promotion Workflows to govern promotion behavior for the `qa` and `prod` environments. + + + +### Before you begin +* [Create Promotion Workflows]({{site.baseurl}}/docs/promotions/entities/promotion-workflow/#create-promotion-workflows) + +### Step-by-step + +1. From the Promotion Flow list, select the Promotion Flow you created, `multi-env-sequential-promotion` for the quick start. +1. In the Settings panel, update the **Version** to indicate changes, for example, `2.0`. +1. Assign the workflows by clicking the respective controls and selecting the Promotion Workflows and the Promotion Action from the list. + The example below shows the Pre-Action Workflows available. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-policy-settings.png" +url="/images/quick-start/promotions/quick-start-seq-promo-policy-settings.png" +alt="Promotions quick start: Pre-Action Workflow to govern promotion behavior for environment" +caption="Promotions quick start: Pre-Action Workflow to govern promotion behavior for environment" +max-width="60%" +%} + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-policy-populated.png" +url="/images/quick-start/promotions/quick-start-seq-promo-policy-populated.png" +alt="Promotions quick start: Target environment configured with Promotion Workflows and Action" +caption="Promotions quick start: Target environment configured with Promotion Workflows and Action" +max-width="60%" +%} + +{:start="4"} +1. Repeat _step 3_ to select the Workflows and Actions for the other target environments in the Promotion Flow. + For this quick start, we'll select the same workflows and the same promotion action for `prod`. + + + + Here's the YAML view of the flow with the workflows and promotion actions. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-policy-yaml.png" +url="/images/quick-start/promotions/quick-start-seq-promo-policy-yaml.png" +alt="Promotions quick start: YAML view of Promotion Flow with Promotion Workflows" +caption="Promotions quick start: YAML view of Promotion Flow with Promotion Workflows" +max-width="60%" +%} + +{:start="5"} +1. To save the changes, click **Save Promotion Flow**. +1. Continue with [Trigger Promotion Flow and monitor product release](#trigger-promotion-flow-and-monitor-product-release). + + +## Trigger Promotion Flow and monitor product release +Now that we have updated the Promotion Flow with the appropriate Pre- and Post-Action Workflows, we can trigger the flow and monitor its progress. + +The difference between the previous release (without workflows), and this one (with workflows), for the same Promotion Flow (`multi-env-sequential-promotion`), is that changes will only be promoted to the next environment when all workflows associated with the previous environment are complete. + +1. Open the Promotion Flow, `multi-env-sequential-promotion` and click **Trigger**. +1. Select the product, the application to promote, and then click **Trigger** once again. +1. Click **View Release Details**. + In the example below, the current release view shows the `qa` and `prod` environments with the Pre- and Post-Action Workflows defined for each environment. + +{% include +image.html +lightbox="true" +file="/images/quick-start/promotions/quick-start-seq-promo-policy-release.png" +url="/images/quick-start/promotions/quick-start-seq-promo-policy-release.png" +alt="Promotions quick start: Release view for gated Promotion Flow" +caption="Promotions quick start: Release view for gated Promotion Flow" +max-width="60%" +%} + + + +## What's next +In the next quick start for promotions, we'll explore how to configure Promotion Flows for parallel promotions, allowing changes to be promoted simultaneously across multiple environments. + +[Quick start: Multi-environment parallel promotion]({{site.baseurl}}/docs/gitops-quick-start/promotions/parallel-multi-env-promotion/) + + + \ No newline at end of file diff --git a/_docs/promotions/entities.md b/_docs/promotions/entities.md index 44c75d101..f2060a3fe 100644 --- a/_docs/promotions/entities.md +++ b/_docs/promotions/entities.md @@ -9,7 +9,7 @@ toc: true After creating products and environments, you can initiate promotions and track releases. -Enhance your promotion strategies with these advanced configuration options: +Enhance your promotion strategies with these advanced configuration options for promotion entities: * Multi-environment promotion with [Promotion Flows]({{site.baseurl}}/docs/promotions/entities/promotion-flow/) (only account admins) * Conditional promotions with [Promotion Policies]({{site.baseurl}}/docs/promotions/entities/promotion-policy/) (only account admins) * Automatic validations and gating with [Promotion Workflows]({{site.baseurl}}/docs/promotions/entities/promotion-workflow/) diff --git a/_docs/promotions/entities/promotion-policy.md b/_docs/promotions/entities/promotion-policy.md index 006b7cc82..12f808be2 100644 --- a/_docs/promotions/entities/promotion-policy.md +++ b/_docs/promotions/entities/promotion-policy.md @@ -366,5 +366,5 @@ For more information, see [Promotion Workflows in Product Releases]({{site.baseu [Configure Promotion Workflows]({{site.baseurl}}/docs/promotions/configuration/promotion-workflow/) [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) [Tracking product releases]({{site.baseurl}}/docs/promotions/product-releases/) -[Promotions: End-to-end guide]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) diff --git a/_docs/promotions/entities/promotion-workflow.md b/_docs/promotions/entities/promotion-workflow.md index b6a8d0e17..fc37e230e 100644 --- a/_docs/promotions/entities/promotion-workflow.md +++ b/_docs/promotions/entities/promotion-workflow.md @@ -1,630 +1,63 @@ --- title: "Configure Promotion Workflows" description: "Create, run, and manage Promotion Workflows" -redirect-from: - - /docs/promotions/configuration/ group: promotions toc: true --- -Workflows are automated processes designed to orchestrate tasks, checks, and actions in a defined sequence to achieve a specific outcome. -In the context of GitOps promotions, Promotion Workflows automate tests and tasks before and after changes are promoted in environments. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/workflows/workflow-overview-image.png" -url="/images/gitops-promotions/workflows/workflow-overview-image.png" -alt="Promotion Workflows" -caption="Promotion Workflows" -max-width="60%" -%} - - -##### Promotion Workflows and Argo Workflows -Promotion Workflows are Argo Workflows that include a specific annotation identifying them for promotion use. You can harness the full capabilities of Argo Workflows and integrate them seamlessly into the GitOps promotion process. - -If you are not familiar with Argo Workflows, refer to their official [documentation](https://argo-workflows.readthedocs.io/en/latest/){:target="\_blank"}. -We also have several articles at our [learning center](https://codefresh.io/learn/argo-workflows/){:target="\_blank"} on all aspects of Argo Workflows. - -See also [Annotation attribute for Promotion Workflows](#annotation-attribute-for-promotion-workflows). +For promotions with GitOps, Promotion Workflows define the actions to execute before and after changes are deployed to environments, ensuring that each update meets quality and performance standards. +These workflows facilitate pre- and post-promotion testing with validations, performance monitoring, notifications, and more, allowing for precise control when changes are promoted. -##### Pre-Action and Post-Action Workflows +In structure and behavior, a Promotion Workflow is essentially an Argo Workflow, classified as a Promotion Workflow. To classify and utilize an Argo Workflow or a Workflow Template as a Promotion Workflow, it must include the annotation attribute `metadata.annotations: codefresh.io/workflow-origin: promotion` in its manifest. +See [Key features of Promotion Workflows](#key-features-of-promotion-workflows) and [Create Promotion Workflows](#create-promotion-workflows). -Promotion Workflows though optional in the promotion process, play a critical role in ensuring that the promoted changes to target environments meet the necessary standards for quality and performance. +After creating Promotion Workflows, there are two aspects to working with them: +* **Managing Promotion Workflows** + Managing Promotion Workflows involves controlling the configuration of the manifest, creating new Promotion Workflows by copying existing ones, and removing workflows that are no longer needed or relevant. + See [Managing Promotion Workflows](#managing-promotion-workflows). -Our GitOps promotion process allows you to run Promotion Workflows at different stages of the process: +* **Managing Workflow execution instances** + Workflow execution instances represent specific occurrences when a Promotion Workflow is triggered either as part of a Promotion Policy, or run for validation. These instances provide detailed insights into the performance and execution of the specific instance of the Workflow. + See [Managing Workflow instances](#managing-workflow-instances). -* _Before_ the changes are applied through Pre-Action Workflows - Pre-Action Workflows validate the readiness of the environment for the changes. These workflows can include tasks such as smoke tests, security scans, or dependency checks. -* _After_ the changes are applied through Post-Action Workflows - Post-Action Workflows validate the success of the promotion after the changes are committed. Such workflows can run performance testing, data integrity checks, or notifying stakeholders about the update status. -See [Promotion Workflow examples](#promotion-workflow-examples). -##### Using Promotion Workflows in the promotion process -After creating Promotion Workflows, there are two ways to use them in the promotion process depending on the level of control and scalability you need: - -* Manual selection - When triggering a promotion manually, you can select specific Pre- and Post-Action Workflows to run for the target environment. This approach is ideal for single-environment promotions or when you need granular control over the workflows for a specific change. - Example: - During a drag-and-drop promotion, you might choose a Pre-Action Workflow to run integration tests and a Post-Action Workflow to send Slack notifications for the target environment. - - See [Triggering promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/). - -* Controlled automation with policies - For scalable, automated usage, you can associate Promotion Workflows with Promotion Policies. Promotion Policies govern promotion behavior according to predefined criteria to create reusable promotion patterns for environments. - With this approach, you can match workflows to environments or products, ensuring consistent behavior in multi-environment promotion flows. You can also combine workflows with specific promotion actions, such as committing changes in pre-production and creating pull requests in production. - Example: - Assign a validation workflow for all staging environments and a performance testing workflow for production environments. - - See [Configuring Promotion Policies]({{site.baseurl}}/docs/promotions/configuration/promotion-policy/). +## Key features of Promotion Workflows +##### Annotation attribute +An Argo Workflow or a Workflow Template is classified as a Promotion Workflow only when the following annotation is present in the workflow manifest: +`metadata.annotations: codefresh.io/workflow-origin: promotion` -##### Arguments in Pre-Action and Post-Action Workflows -Codefresh passes a set of arguments it retrieves during the promotion process to both Pre- and Post-Action Workflows. You can use these as dynamic data throughout the promotion lifecycle. -See [Parameters in Pre-Action and Post-Action Workflows](#parameters-in-pre-action-and-post-action-workflows). +This annotation in the Promotion Workflow's manifest ensures that: +* The Promotion Workflow is displayed in the Promotion Workflows list and can be managed there +* You can assign the Promotion Workflow to Promotion Policies +* Select it when creating Promotion Flows +See [Create Promotion Workflows](#create-promotion-workflows). -##### Manage workflows and workflow instances -After creating Promotion Workflows, you can [manage workflows](#managing-promotion-workflows) and [workflow instances](#managing-workflow-instances). +##### Pre- and Post-Action Workflows +A Promotion Workflow can be executed before or after the Promotion Action as a Pre-Action or a Post-Action Workflow. The Promotion Action is the action that implements the changes to the environment, for example, commit. +##### Pre-commit run option +Inline validations when creating or editing Promotion Workflows are supplemented by the Run option. -## Promotion Workflow examples +Instead of committing the manifest and detecting errors or failures when the Workflow is activated, the Run option runs the specific Promotion Workflow in the cluster, verifying actions and steps in the workflow, such as sending notifications, running pre-action validations or post-action test. +See [Validate Promotion Workflow parameters](#validate-promotion-workflow-parameters). -Below are examples of different types of workflows designed to address specific requirements at various stages of the GitOps promotion process. -* Testing workflows: Running unit and smoke tests for example to validate and verify that the promoted change is functional in the target environment. -* Notification workflows: Send updates or alerts to stakeholders via tools like Slack or email. -* Performance testing workflows: For running benchmarks or load tests to validate performance post-promotion. -* Validation workflows: Ensure compliance with security, quality, or policy standards before deployment. -* Rollback workflows: Automatically revert changes if a promotion fails validation or post-action checks. +##### Pre- & Post-Action Workflow arguments +Codefresh passes parameters to the Pre-Action and Post-Action Workflows. These arguments allow you to customize Post-Action Workflow execution based on the specific details of the commit. +See [Arguments for Pre-Action and Post-Action Workflows](#arguments-for-pre-action-and-post-action-workflows). -##### Workflow settings in Shared Repo +## Promotion Workflow YAMLs Once configured and committed, Workflow settings are saved as a CRD (Custom Resource Definition) within the Shared Configuration Repository in the GitOps Runtime selected as the Configuration Runtime. The path in the Shared Configuration Repo is `//resources/control-planes/promotion-workflows/`. See [Shared Configuration Repository]({{site.baseurl}}/docs/installation/gitops/shared-configuration/) and [Designating Configuration Runtimes]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes). -##### YAML examples - -Here are some examples of Promotion Workflows with different objectives and run at different stages of the promotion process. -* [Example 1: Pre-Action Workflow with application sync check](#example-1-pre-action-application-sync-check-test) -* [Example 2: Pre-action Workflow combining smoke test and Slack notification](#example-2-pre-action-smoke-test-with-slack-notification) -* [Example 3: Post-Action Workflow to close Jira ticket](#example-3-post-action-jira-ticket-close) - -### Example 1: Pre-Action application sync check test -This Pre-action Workflow performs a preliminary validation by echoing a sync message for the application being promoted. -The workflow confirms that the argument `APP_NAME` is correctly passed to it and right application is being promoted. - - -```yaml -# DO NOT REMOVE the following attributes: -# annotations.codefresh.io/workflow-origin (identifies type of Workflow Template as Promotion Workflow) -# annotations.version (identifies version of Promotion Workflow used) -# annotations.description (identifies intended use of the Promotion Workflow) -apiVersion: argoproj.io/v1alpha1 -kind: WorkflowTemplate -metadata: - name: pre-action - annotations: - codefresh.io/workflow-origin: promotion - version: 0.0.1 - description: 'promotion workflow template' -spec: - serviceAccountName: promotion-template - arguments: - parameters: - - name: APP_NAME - description: The name of the application being promoted. - entrypoint: echo-pre-action - templates: - - name: echo-pre-action - script: - image: alpine - command: - - sh - source: | - echo "syncing {{ workflow.parameters.APP_NAME }}" -``` - - -### Example 2: Pre-Action smoke test with Slack notification -A more complex Pre-Action Workflow, the workflow in this example executes a smoke test and sends a Slack alert if the smoke test fails. The workflow identifies failures before changes are committed and promoted, and alerts stakeholders of the failures. - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: WorkflowTemplate -metadata: - name: smoke-test-pre-action - annotations: - codefresh.io/workflow-origin: promotion - version: 0.0.1 - description: 'Pre-action smoke test with Slack notification' -spec: - serviceAccountName: promotion-template - arguments: - parameters: - - name: APP_NAME - description: The name of the application being promoted. - entrypoint: smoke - onExit: slack-alert - templates: - - name: smoke - inputs: - parameters: - - name: NB_TESTS - value: 100 - - name: THRESHOLD - value: 30 - - name: TEST_RATE - value: 50 - script: - image: bash:5.2.26 - command: ["/usr/local/bin/bash"] - source: | - num_tests={{inputs.parameters.NB_TESTS}} - error=0 - success=0 - test_rate={{inputs.parameters.TEST_RATE}} - suite_threshold={{inputs.parameters.THRESHOLD}} - - # Generate random test results - for ((i=1; i<=$num_tests; i++)); do - rand_num=$((RANDOM % 100 + 1)) - if ((rand_num < test_rate )) - then - echo "Test $i: FAILED ($rand_num)" - ((error++)) - else - echo "Test $i: PASSED ($rand_num)" - ((success++)) - fi - done - - success_rate=$((success * 100 / num_tests)) - echo "Success Rate: $success_rate%" - if ((success_rate < suite_threshold)) - then - echo "Test Suite: FAILED" - exit 1 - else - echo "Test Suite: PASSED" - exit 0 - fi - - - name: slack-alert - dag: - tasks: - - name: send-message - templateRef: - name: argo-hub.slack.0.0.2 - template: post-to-channel - when: "{{workflow.status}} != Succeeded" - arguments: - parameters: - - name: SLACK_CHANNEL - value: 'topic-codefresh-demo' - - name: SLACK_MESSAGE - value: 'Smoke test failed for {{ workflow.parameters.APP_NAME }}. Check logs at https://g.codefresh.io/2.0/workflows/{{ workflow.name }}' - - name: SLACK_TOKEN - value: slack-token - - name: LOG_LEVEL - value: "info" -``` - -### Example 3: Post-Action soak test -This example is of a Post-Action Promotion Workflow that uses a script template to display application details, commit information, and the Argo CD host, taking these parameters from the promotion flow process. - -```yaml -# DO NOT REMOVE the following attributes: -# annotations.codefresh.io/workflow-origin (identifies type of Workflow Template as Promotion Workflow) -# annotations.version (identifies version of Promotion Workflow used) -# annotations.description (identifies intended use of the Promotion Workflow) -apiVersion: argoproj.io/v1alpha1 -kind: WorkflowTemplate -metadata: - name: soak-test - annotations: - codefresh.io/workflow-origin: promotion - version: 0.0.1 - argo-hub/version: 0.0.2 - argo-hub/description: >- - This Workflow Template is an example of a post-promotion workflow that - uses a script template to display application details, commit information, - and the Argo CD host, taking these parameters from the promotion flow - process. - argo-hub/categories: promotion example workflow - argo-hub/license: MIT - argo-hub/owner_name: Eti Zaguri - argo-hub/owner_email: eti.zaguri@codefresh.io - argo-hub/owner_avatar: https://avatars.githubusercontent.com/u/85868206 - argo-hub/owner_url: https://github.com/eti-codefresh - argo-hub/icon_url: >- - https://cdn.jsdelivr.net/gh/codefresh-io/argo-hub@main/examples/post-promotion-starter/assets/icon.svg - argo-hub/icon_background: '#f4f4f4' -spec: - arguments: - parameters: - - name: APP_NAMESPACE - - name: APP_NAME - - name: REPO_URL - - name: BRANCH - - name: PATH - - name: COMMIT_SHA - value: '' - - name: COMMIT_MESSAGE - value: '' - - name: COMMIT_AUTHOR - value: '' - - name: COMMIT_DATE - value: '' - serviceAccountName: argo-hub.post-promotion-starter.0.0.2 - entrypoint: echo - templates: - - name: echo - metadata: - annotations: - argo-hub-template/description: >- - Echo the commit parameters and argo cd host from the promotion flow - process - argo-hub-template/icon_url: >- - https://cdn.jsdelivr.net/gh/codefresh-io/argo-hub@main/examples/post-promotion-starter/assets/icon.svg - argo-hub-template/icon_background: '#f4f4f4' - script: - image: alpine - command: - - sh - source: > - echo "syncing - {{workflow.parameters.APP_NAMESPACE}}/{{workflow.parameters.APP_NAME}} - from {{workflow.parameters.REPO_URL}} branch - {{workflow.parameters.BRANCH}} path {{workflow.parameters.PATH}}" - - if [[ -n "{{workflow.parameters.COMMIT_SHA}}" ]]; then - echo "commit SHA: {{workflow.parameters.COMMIT_SHA}}" - fi - - - if [[ -n "{{workflow.parameters.COMMIT_AUTHOR}}" ]]; then - echo "commit author: {{workflow.parameters.COMMIT_AUTHOR}}" - fi - - - if [[ -n "{{workflow.parameters.COMMIT_MESSAGE}}" ]]; then - echo "commit message: {{workflow.parameters.COMMIT_MESSAGE}}" - fi - - - if [[ -n "{{workflow.parameters.COMMIT_DATE}}" ]]; then - echo "commit date: {{workflow.parameters.COMMIT_DATE}}" - fi -``` - -## Parameters in Pre-Action and Post-Action Workflows -Pre-Action and Post-Action Workflows can use default parameters retrieved from application manifest data, and user-defined custom parameters to adapt dynamically to specific environments and processes. - -### Default parameters - -The table describes the default parameters and values passed to Pre- and Post-Action Workflows. -The same set of parameters are passed also for pull requests (GitHub only), after the pull request is merged. - -At the simplest levels, you can display the details from the parameters in notifications. In more advanced scenarios, you can customize the workflow execution based on specific parameters. - -{: .table .table-bordered .table-hover} -| Parameters | Description | Pre-Action Workflow | Post-Action Workflow | -| -------------- | -------------- | -------------- | -------------- | -|`APP_NAMESPACE` | The namespace where the application is deployed to. For example, `gitops`. | ✅ | ✅ | -|`APP_NAME` | The name of the specific application the Promotion Workflows and the Promotion Action pertain to. For example, `trioapp-staging`.| ✅ | ✅ | -| `REPO_URL` | The Git repository with the application settings, as defined in the application's configuration. See [Source settings for applications]({{site.baseurl}}/docs/deployments/gitops/create-application/#sources).| ✅ | ✅ | -| `BRANCH` | The specific Git branch to which to promote changes. For example, `main`. |✅ | ✅ | -| `PATH` | The relative path within the repository defined by `REPO_URL` to the directory or file containing the application's configuration. See [Source settings for applications]({{site.baseurl}}/docs/deployments/gitops/create-application/#sources). | ✅ | ✅ | -|`RUNTIME` |The name of the GitOps Runtime the application being promoted is associated with. |✅ | ✅ | -|`COMMIT_SHA`| The unique identifier (SHA) of the commit, generated by Git, including the precise set of changes addressed by the commit. Can be used as a trigger condition in Promotion Flows configured for a product. | |✅ | -|`COMMIT_AUTHOR`| The name of the user who made the commit. Useful for tracking changes and for notifications.| | ✅ | -|`COMMIT-MESSAGE` | The text in the commit message associated with the code change that triggered the promotion, providing context for the changes introduced by the commit. | |✅ | -|`COMMIT-DATE` | The date and time when the commit was made. Useful to correlate the commit with other events and understand the timeline of changes.| | ✅ | - - -### Custom global parameters -In Pre-Action Workflows, you can define _custom parameters as global outputs_, making them available as input parameters in subsequent Post-Action Workflows. This feature provides a seamless way to pass data across workflows and create complex automation scenarios. - -In the Pre-Action Workflow, any parameter marked with a `globalName` in its `outputs` definition becomes a global parameter. -These parameters are then available for the Post-Action Workflow. - -```yaml -outputs: - parameters: - - name: JIRA_ID - globalName: JIRA_ID - valueFrom: - path: /tmp/JIRA_ID - -``` - -### Custom `globalName` argument usage example - -This is an example of a Pre-Action Workflow that simulates creating a Jira ticket with the data retreived from the application manifest and outputs the ticket ID as a global parameter. The Post-Action Workflow simulates using the ID as an input parameter to close the ticket. - -#### Pre-Action Workflow example with Jira ID as global parameter - -Main features: -* **Workflow parameters** - The following parameters are passed to the Pre-Action Workflow: - * Application details: `APP_NAMESPACE`, `APP_NAME` - * Source repository details: `REPO_URL`, `BRANCH, PATH` - -* **Argo CD application fetch task** - The `argocd-get` task fetches application details using Argo CD's CLI, storing the application manifest for downstream tasks. - -* **Jira ticket creation task** - The `jira-create-ticket` task generates a simulated Jira ticket ID based on the application manifest. - The `JIRA_ID` parameter is marked with a `globalName` to allow it to be passed to post-action workflows seamlessly. - - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: WorkflowTemplate -metadata: - name: pre-action-argo-cd-jira-example - annotations: - codefresh.io/workflow-origin: promotion - codefresh.io/promotion-stage: pre-action - version: 0.0.1 - description: 'a demo jira-open-ticket wf. reads argo-cd app information, outputs (dummy) JIRA_ID value' -spec: - serviceAccountName: pre-action-sa - entrypoint: dag - arguments: - parameters: - - name: APP_NAMESPACE - - name: APP_NAME - - name: REPO_URL - - name: BRANCH - - name: PATH - templates: - - name: dag - inputs: - parameters: - - name: APP_NAMESPACE - - name: APP_NAME - - name: REPO_URL - - name: BRANCH - - name: PATH - dag: - tasks: - - name: argocd-get - template: argocd-get-tmpl - arguments: - parameters: - - name: ARGOCD_SERVER - value: argo-cd-server:80 # or whatever service name you end up using - - name: APP_NAME - value: "{{ inputs.parameters.APP_NAME }}" - - name: TOKEN_SECRET - value: argocd-token - - name: TOKEN_SECRET_KEY - value: token - - - name: jira-create-ticket - depends: "argocd-get" - template: jira-create-ticket-tmpl - arguments: - parameters: - - name: APP_MANIFEST - value: "{{ tasks['argocd-get'].outputs.parameters.APP_MANIFEST }}" - - - name: argocd-get-tmpl - inputs: - parameters: - - name: ARGOCD_SERVER - - name: APP_NAME - - name: TOKEN_SECRET - default: argocd-token - - name: TOKEN_SECRET_KEY - default: token - outputs: - parameters: - - name: APP_MANIFEST - # globalName: APP_MANIFEST # optional - any global output will reach the post-action as well - valueFrom: - path: /tmp/result.json - script: - name: app-get - image: quay.io/codefreshplugins/argo-hub-workflows-argocd-versions-0.0.1-images-argocd-cli:main - env: - - name: APP_NAME - value: "{{ inputs.parameters.APP_NAME }}" - - name: ARGOCD_SERVER - value: "{{ inputs.parameters.ARGOCD_SERVER }}" - - name: ARGOCD_AUTH_TOKEN - valueFrom: - secretKeyRef: - name: "{{ inputs.parameters.TOKEN_SECRET }}" - key: "{{ inputs.parameters.TOKEN_SECRET_KEY }}" - - name: ARGOCD_OPTS - value: --grpc-web --plaintext - command: - - sh - source: | - argocd app get ${APP_NAME} --output json > /tmp/result.json - - - name: jira-create-ticket-tmpl - inputs: - parameters: - - name: APP_MANIFEST - outputs: - parameters: - - name: JIRA_ID - globalName: JIRA_ID - valueFrom: - path: /tmp/JIRA_ID - script: - image: alpine:3.20 - command: - - sh - source: | - echo "create jira ticket with data from the inputs.prameters.APP_MANIFEST" - sleep 5 - RANDOM_HASH=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 13) - echo "JIRA-ticket-id-${RANDOM_HASH}" > /tmp/JIRA_ID -``` - -#### Post-Action Workflow with Jira ID - -Main features: -* **Workflow parameters** - The following parameters are passed to the Post-Action Workflow: - * Application details: `APP_NAMESPACE`, `APP_NAME` - * Source repository details: `REPO_URL`, `BRANCH, PATH` - * Promotion metadata: `COMMIT_SHA`, `COMMIT_MESSAGE`, `COMMIT_AUTHOR`, `COMMIT_DATE` - * Jira ticket ID: `JIRA_ID` -* **Close Jira ticket task** - Uses the `close-jira task` to call a script that simulates closing the JIRA ticket by using the provided `JIRA_ID`. - The task output will show: `Closing JIRA ticket: followed by JIRA ticket closed`. -* **Log summary task** - After closing the Jira ticket, the `echo` task logs and outputs all provided contextual information, including the promotion details from the arguments passed to the workflow. - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: WorkflowTemplate -metadata: - name: post-action-jira-example - annotations: - codefresh.io/workflow-origin: promotion - codefresh.io/promotion-stage: post-action - version: 0.0.1 - description: 'a demo jira-close-ticket wf. expects (dummy) JIRA_ID argument' -spec: - serviceAccountName: post-action-sa - entrypoint: dag - arguments: - parameters: - - name: APP_NAMESPACE - - name: APP_NAME - - name: REPO_URL - - name: BRANCH - - name: PATH - - name: COMMIT_SHA - value: "" - - name: COMMIT_MESSAGE - value: "" - - name: COMMIT_AUTHOR - value: "" - - name: COMMIT_DATE - value: "" - - name: JIRA_ID - templates: - - name: dag - inputs: - parameters: - - name: APP_NAMESPACE - - name: APP_NAME - - name: REPO_URL - - name: BRANCH - - name: PATH - - name: COMMIT_SHA - - name: COMMIT_MESSAGE - - name: COMMIT_AUTHOR - - name: COMMIT_DATE - - name: JIRA_ID - dag: - tasks: - - name: jira-close - template: jira-close-tmpl - arguments: - parameters: - - name: JIRA_ID - value: "{{ inputs.parameters.JIRA_ID }}" - - - name: echo - depends: "jira-close" - template: echo-tmpl - arguments: - parameters: - - name: APP_NAMESPACE - value: "{{ inputs.parameters.APP_NAMESPACE }}" - - name: APP_NAME - value: "{{ inputs.parameters.APP_NAME }}" - - name: REPO_URL - value: "{{ inputs.parameters.REPO_URL }}" - - name: BRANCH - value: "{{ inputs.parameters.BRANCH }}" - - name: PATH - value: "{{ inputs.parameters.PATH }}" - - name: COMMIT_SHA - value: "{{ inputs.parameters.COMMIT_SHA }}" - - name: COMMIT_MESSAGE - value: "{{ inputs.parameters.COMMIT_MESSAGE }}" - - name: COMMIT_AUTHOR - value: "{{ inputs.parameters.COMMIT_AUTHOR }}" - - name: COMMIT_DATE - value: "{{ inputs.parameters.COMMIT_DATE }}" - - - name: jira-close-tmpl - inputs: - parameters: - - name: JIRA_ID - script: - image: alpine:3.20 - env: - - name: JIRA_ID - value: "{{ inputs.parameters.JIRA_ID }}" - command: - - sh - source: | - echo "got JIRA_ID \"${JIRA_ID}\"" - sleep 5 - echo "after handling jira in post action" - - - name: echo-tmpl - inputs: - parameters: - - name: APP_NAMESPACE - - name: APP_NAME - - name: REPO_URL - - name: BRANCH - - name: PATH - - name: COMMIT_SHA - - name: COMMIT_MESSAGE - - name: COMMIT_AUTHOR - - name: COMMIT_DATE - outputs: - parameters: - - name: RESULT - valueFrom: - path: /tmp/result - globalName: RESULT - script: - image: alpine:3.20 - command: - - sh - source: | - converted_date=$(date -d "{{ inputs.parameters.COMMIT_DATE }}" +"%a %b %d %H:%M:%S %Y %z") - echo "post action for \"{{ inputs.parameters.APP_NAMESPACE }}/{{ inputs.parameters.APP_NAME }}\"" - echo "repoUrl: {{ inputs.parameters.REPO_URL }}, branch: {{ inputs.parameters.BRANCH }}, path: {{ inputs.parameters.PATH }}" - echo "" - echo "commit {{ inputs.parameters.COMMIT_SHA }}" - echo "Author: {{ inputs.parameters.COMMIT_AUTHOR }}" - echo "Date: ${converted_date}" - echo "" - echo " {{ inputs.parameters.COMMIT_MESSAGE }}" - echo "" - echo "{\"POST_ACTION_RESULT\": "\Success\""}" > /tmp/result -``` - -## Annotation attribute for Promotion Workflows -An Argo Workflow or a Workflow Template is classified as a Promotion Workflow only when the following annotation is present in the workflow manifest: -`metadata.annotations: codefresh.io/workflow-origin: promotion` - -This annotation in the Promotion Workflow's manifest ensures that: -* The Promotion Workflow is displayed in the Promotion Workflows list and can be managed there -* You can assign the Promotion Workflows in Promotion Policies -* Select Promotion Workflows within Promotion Flows - ## Create Promotion Workflows @@ -632,7 +65,7 @@ Create a Promotion Workflow from scratch, use the base Promotion Workflow Templa Whichever method you use to create your Promotion Workflow, make sure you include the annotation in the manifest to classify and use it as a Promotion Workflow. - + 1. In the Codefresh UI, from Promotions in the sidebar, select **Promotion Workflows**. 1. Click **Add Promotion Workflow**. 1. Define the following: @@ -667,12 +100,34 @@ max-width="60%" When the YAML file is synced to the cluster, it is displayed in the Promotion Workflows list. +### Arguments for Pre-Action and Post-Action Workflows + + +The table describes the parameters with default values passed to Pre- and Post-Action Workflows. +Some parameters are passed to both types of Promotion Workflows, while some parameters are specific only to Post-Action Workflows. +The same set of parameters are passed also for pull requests, after the pull request is merged. + +At the simplest levels, you can display the details from the parameters in notifications. In more advanced scenarios, you can customize the Workflow execution based on specific parameters. + +{: .table .table-bordered .table-hover} +| Parameters | Description | Pre-Action Workflow | Post-Action Workflow | +| -------------- | -------------- | -------------- | -------------- | +|`APP_NAME` | The name of the specific application the Promotion Workflows and the Promotion Action pertain to. For example, `trioapp-staging`.| ✅ | ✅ | +|`APP_NAMESPACE` | The namespace where the application is deployed to. For example, `gitops`. | ✅ | ✅ | +| `REPO_URL` | The Git repository with the application settings, as defined in the application's configuration. See [Source settings for applications]({{site.baseurl}}/docs/deployments/gitops/create-application/#sources).| ✅ | ✅ | +| `PATH` | The relative path within the repository defined by `REPO_URL` to the directory or file containing the application's configuration. See [Source settings for applications]({{site.baseurl}}/docs/deployments/gitops/create-application/#sources). | ✅ | ✅ | +| `BRANCH` | The specific Git branch to which to promote changes. For example, `main`. |✅ | ✅ | +|`RUNTIME` |The name of the GitOps Runtime the application being promoted is associated with. |✅ | ✅ | +|`COMMIT_SHA`| The unique identifier (SHA) of the commit, generated by Git, including the precise set of changes addressed by the commit. Can be used as a trigger condition in Promotion Flows configured for a product. | |✅ | +|`COMMIT_AUTHOR`| The name of the user who made the commit. Useful for tracking changes and for notifications.| | ✅ | +|`COMMIT-MESSAGE` | The text in the commit message associated with the code change that triggered the promotion, providing context for the changes introduced by the commit. | |✅ | +|`COMMIT-DATE` | The date and time when the commit was made. Useful to correlate the commit with other events and understand the timeline of changes.| | ✅ | ## Promotion Workflow list -All Workflows which include `metadata.annotations: codefresh.io/workflow-origin: promotion` are displayed in the Promotion Workflows list. +All Argo Workflows which include `metadata.annotations: codefresh.io/workflow-origin: promotion` are displayed in the Promotion Workflows list. {% include image.html @@ -708,7 +163,7 @@ You can: Changes to the manifest do not affect past execution instances as the manifest is updated independently of individual workflow executions. - + ### Validate Promotion Workflow parameters @@ -741,14 +196,27 @@ The option runs the specific Promotion Workflow in the cluster, verifying all ac -### Copy/delete Promotion Workflows -Copy an existing Promotion Workflow to create a new Promotion Workflow with the same manifest configuration. +### Copy Promotion Workflows +Copy an existing Promotion Workflow to create a new Promotion Workflow with the same manifest configuration. (NIMA: when would you do this) + +1. In the Codefresh UI, from Promotions in the sidebar, select **Promotion Workflows**. +1. From the context menu of the Promotion Workflow select **Copy**. +1. Enter the **Name**, **Description**, and **Resource Filename** for the new Workflow. +1. Update the manifest if needed. +1. Commit the changes. + -Delete unused legacy Promotion Workflows. Deleting a Promotion Workflow removes it from the Promotion Workflow list, from the Promotion Policies it is configured in, and from the Promotion Flows. -Both options are available in the context menu of the selected Promotion Workflow. +### Delete Promotion Workflows +Delete unused legacy Promotion Workflows. Deleting a Promotion Workflow removes it from the Promotion Workflow list, from the Promotion Policies it is configured in, and from the Promotion Flows. + +1. In the Codefresh UI, from Promotions in the sidebar, select **Promotion Workflows**. +1. From the context menu of the Promotion Workflow select **Delete**. +1. Enter the name of the Promotion Workflow to confirm. +1. Optional. Add a commit message and description. +1. To confirm, click **Commit & Delete**. ## Managing Workflow instances @@ -756,23 +224,11 @@ Workflow instances are the specific execution instances of the Promotion Workflo You can: * View instances of a Promotion Workflow - In addition to the status which is prominently displayed on the right for each execution instance, you can filter by products, environments and applications to get to the instances of interest to you. * Analyze the version of the manifest used for the instance with the configuration, parameters, artifacts (Workflow summary) - -* Take action on a completed or failed workflow (Workflow actions) - * **Resubmit**: Rerun or re-execute the Workflow. Resubmitting a Workflow, creates a new instance of the Workflow. You can resubmit both successful and failed workflows. - * **Retry**: Rerun the workflow instance from the point of error. Unlike Resubmit, Retry does not create a new workflow instance. - * **Delete** an instance (Workflow actions) -* Analyze individual steps of the workflow (Workflow steps) - * The header displays the name of the step, its status, the step-type, the date of the most recent update, and duration. - * The tabs displayed differ according to the step type: - * The Summary, Manifest, Containers, Inputs, Outputs tabs are displayed for all almost all step types. - * The Logs tab is displayed for Pod step types. - * Event-step types display Manifest, Summary, and Payload. - For Cron and Unknown event types, only the Event Sources are shown. +* Resubmit a completed or failed workflow (Workflow actions) +* Delete an instance (Workflow actions) +* Analyze individual steps of the workflow (Workflow steps) * View detailed logs to troubleshoot execution (Workflow logs) - View online logs for ongoing or completed Workflows. As with logs in any standard terminal, you can copy/cut/paste log info. The commands differ based on the OS. - {% include image.html @@ -787,9 +243,9 @@ max-width="60%" - The table highlights key information you can find in the Summary tab for a workflow. @@ -829,10 +287,11 @@ The table highlights key information you can find in the Summary tab for a workf ### Workflow actions Depending on the status of the workflow instance, you can do the following: +* **Resubmit**: Rerun or re-execute the Workflow. Resubmitting a Workflow, creates a new instance of the Workflow. You can resubmit both successful and failed workflows. +* **Retry**: Rerun the workflow instance from the point of error. Unlike Resubmit, Retry does not create a new workflow instance. - -SCREENSHOT -Remove unused or legacy workflow instances. Deleting a workflow instance removes it from the list of executions. The Promotion Workflow itself is not changed. + ### Workflow steps Visualize the steps in the Workflow. For additional information on the step, click the step to open the pull-out panel. @@ -847,10 +306,19 @@ caption="Workflow instance step detailed view" max-width="60%" %} +* The header displays the name of the step, its status, the step-type, the date of the most recent update, and duration. +* The tabs displayed differ according to the step type: + * The Summary, Manifest, Containers, Inputs, Outputs tabs are displayed for all almost all step types. + * The Logs tab is displayed for Pod step types. + * Event-step types display Manifest, Summary, and Payload. + For Cron and Unknown event types, only the Event Sources are shown. ### Workflow logs +View online logs for ongoing or completed Workflows. As with logs in any standard terminal, you can copy/cut/paste log info. The commands differ based on the OS. + * For an ongoing Workflow, view live logs for steps as they are being executed. + * For a completed Workflow, view logs for the Workflow, or for any step in the workflow. {% include @@ -862,14 +330,14 @@ alt="Workflow instance logs" caption="Workflow instance logs" max-width="60%" %} ---> -## Promotion Workflows in product release views -When a promotion is triggered automatically or manually, a release is created for the product and displayed in the Releases tab. -Clicking the Release ID displays the ongoing or completed view of the promotion orchestration across the environment. -Each environment displays the Pre-Action or Post-Action workflows assigned to it, including its steps for on-going releases. The collective status of the workflows determines the promotion status of an environment. + +## Promotion Workflows & steps in Releases +When a release is created for a promotion triggered automatically or manually, clicking the Release ID displays the ongoing or completed view of the promotion orchestration across the environment. + +Each environment displays the Pre-Action or Post-Action workflows assigned to it. If a workflow execution is in progress, workflow steps are alsi displayed. The collective status of the workflows determines the promotion status of an environment. {% include image.html @@ -881,8 +349,21 @@ caption="Example of workflows for product release" max-width="60%" %} -See [Promotion Workflows in product releases]({{site.baseurl}}/docs/promotions/product-releases/#promotion-workflows-in-product-releases). +See [Promotion Workflows in product releases]({{site.baseurl}}/docs/promotions/product-releases/#promotion-workflows-in-product-releases) +## Promotion Workflows in Promotion Policies +Workflows are assigned on creating Promotion Policies. A Promotion Policy governs the promotion behavior for each environment. +Accordingly, you can assign a Promotion Workflow to run for the environment before updating it with changes (Pre-Action Workflow), and after promoting the changes (Post-Action Workflow). + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/workflows/workflows-in-policy.png" +url="/images/gitops-promotions/workflows/workflows-in-policy.png" +alt="Example of Promotion Workflows in Promotion Policy" +caption="Example of Promotion Workflows in Promotion Policy" +max-width="60%" +%} ## Related articles @@ -890,5 +371,5 @@ See [Promotion Workflows in product releases]({{site.baseurl}}/docs/promotions/p [Configure Promotion Policies]({{site.baseurl}}/docs/promotions/configuration/promotion-policy/) [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) [Tracking product releases]({{site.baseurl}}/docs/promotions/product-releases/) -[Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[Promotion sequences]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) diff --git a/_docs/promotions/entities/yaml.md b/_docs/promotions/entities/yaml.md index 9e5dd742b..be6518219 100644 --- a/_docs/promotions/entities/yaml.md +++ b/_docs/promotions/entities/yaml.md @@ -2,15 +2,13 @@ title: "YAML specs" description: "YAML specifications for promotion entities" group: promotions -redirect-from: - - /docs/promotions/configuration/yaml/ toc: true --- Codefresh provides two options for defining manifests for promotion entities: Form mode and YAML mode. If you prefer working with YAML, create manifests for promotion entities using our YAML examples: -* [Product YAML]({{site.baseurl}}/docs/promotions/entities/yaml/product-crd/) -* [Promotion Template YAML]({{site.baseurl}}/docs/promotions/entities/yaml/promotion-template-crd/) -* [Promotion Flow YAML]({{site.baseurl}}/docs/promotions/entities/yaml/promotion-flow-crd/) -* [Promotion Policy YAML]({{site.baseurl}}/docs/promotions/entities/yaml/promotion-policy-crd/) \ No newline at end of file +* [Product YAML]({{site.baseurl}}/docs/promotions/configuration/yaml/product-crd/) +* [Promotion Template YAML]({{site.baseurl}}/docs/promotions/configuration/yaml/promotion-template-crd/) +* [Promotion Flow YAML]({{site.baseurl}}/docs/promotions/configuration/yaml/promotion-flow-crd/) +* [Promotion Policy YAML]({{site.baseurl}}/docs/promotions/configuration/yaml/promotion-policy-crd/) \ No newline at end of file diff --git a/_docs/promotions/getting-started.md b/_docs/promotions/getting-started.md index a7b24a33a..427b7b4c7 100644 --- a/_docs/promotions/getting-started.md +++ b/_docs/promotions/getting-started.md @@ -8,6 +8,7 @@ toc: true Use the links below to dive into the basics of promotions in Codefresh GitOps, explore key components, and configure your first promotion flow. * Understand the entities involved the entities and their roles: [Promotion building blocks]({{site.baseurl}}/docs/promotions/promotion-components/) -* High-level guidelines on how to set up and implement promotions: [Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) -* Practical examples on triggering promotions: [Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) +* High-level guidelines on how to set up and implement promotions: [Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) + +* Practical walkthroughs on triggering promotions: [Promotion tutorials]({{site.baseurl}}/docs/gitops-quick-start/promotions/) diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index e995d75d1..45e3d1551 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -132,7 +132,7 @@ In code samples and internal references, it is represented as `isc`. ## Related articles [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) -[Promotions: End-to-end guide]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) [Triggering promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) [Tracking product releases]({{site.baseurl}}/docs/promotions/product-releases/) diff --git a/_docs/promotions/promotion-scenarios.md b/_docs/promotions/promotion-scenarios.md index 8b694e70f..4443fb515 100644 --- a/_docs/promotions/promotion-scenarios.md +++ b/_docs/promotions/promotion-scenarios.md @@ -5,41 +5,11 @@ group: promotions toc: true --- +>**Moved** +We have moved Promotion Tutorials to the GitOps Quick Start section. -A successful promotion sequence relies on several key components that together govern and orchestrate the promotion flow across environments. The sections that follow takes you through configuring several scenarios for promotions, from basic to complex promotions. +This ensures a seamless learning journey, starting from setting up your Codefresh account and installing a Runtime, to creating environments, products, applications, and finally promoting applications across environments. +Go to [GitOps quick starts]({{site.baseurl}}/docs/gitops-quick-start/gitops-quick-start/). -Here’s how to progress from basic to advanced promotion sequences: - -##### Applications, Products, and Environments -These core deployment entities are required for all promotions. Products enable you to group and configure related applications, and environments define where changes to these applications are promoted. -With these entities, you can quickly promote changes using a drag-and-drop method between two environments and choose the target environment for promotion. - -##### Promotion Flows -After setting up the basics, orchestrate promotion across multiple environments. -Use our Promotion Flow entity to create complex, multi-environment deployment strategies. - -##### Promotion Workflows -Adding Promotion Workflows introduces validations and checks that ensure each environment in the sequence meets your standards. - - -Explore these promotion tutorials to get up and running: -* [Drag-and-drop promotions]({{site.baseurl}}/docs/promotions/promotion-scenarios/drag-and-drop/) -* [Multi-environment sequential promotion]({{site.baseurl}}/docs/promotions/promotion-scenarios/multi-env-sequential-flow/) -* [Policy-driven multi-environment promotion]({{site.baseurl}}/docs/promotions/promotion-scenarios/policy-multi-env-promotion/) -* [Multi-environment promotion with parallel environments]({{site.baseurl}}/docs/promotions/promotion-scenarios/parallel-multi-env-promotion/) -* [Multi-environment promotion with dependencies]({{site.baseurl}}/docs/promotions/promotion-scenarios/dependency-multi-env-promotion/) - - - - - - \ No newline at end of file diff --git a/_docs/promotions/promotion-scenarios/dependency-multi-env-promotion.md b/_docs/promotions/promotion-scenarios/dependency-multi-env-promotion.md deleted file mode 100644 index 01bae9b63..000000000 --- a/_docs/promotions/promotion-scenarios/dependency-multi-env-promotion.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Multi-environment promotion with dependencies" -description: "Promote product apps between environments with dependencies" -group: promotions -toc: true ---- - - -In this final scenario, we’ll explore how to create dependencies between environments in a Promotion Flow. - -By default, each environment in a promotion flow (except the trigger environment) is dependent on the one preceding it. However, critical environments may rely on the success or stability of multiple environments before they are promoted to. By defining additional dependencies, you can ensure that changes are promoted only when all required environments meet the specified criteria. - -In this example, we’ll return to the `three-env-promotion` flow, add a parallel `staging` environment, and set a dependency on `staging` for `production`. This setup means changes are promoted to `production` only after both `qa` and `staging` have been successfully promoted. - -In the example, we have already added the `staging` environment. - - -Now we'll update the dependency on the `production` environment, by selecting `staging`, in addition to `qa`: - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-dependency.png" -url="/images/gitops-promotions/tutorials/promo-flow-dependency.png" -alt="Update dependencies for environment" -caption="Update dependencies for environment" -max-width="60%" -%} - - - -Here's the `three-env-promotion` Promotion Flow with the updated dependency. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-updated-dependency.png" -url="/images/gitops-promotions/tutorials/promo-flow-updated-dependency.png" -alt="Promotion Flow with updated dependencies" -caption="Promotion Flow with updated dependencies" -max-width="60%" -%} - -Here's the YAML view of the same flow with the updated dependency. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-dependency-yaml-view.png" -url="/images/gitops-promotions/tutorials/promo-flow-dependency-yaml-view.png" -alt="YAML view of Promotion Flow with updated dependencies" -caption="YAML view of Promotion Flow with updated dependencies" -max-width="60%" -%} - -## Related articles -[Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) - - - \ No newline at end of file diff --git a/_docs/promotions/promotion-scenarios/drag-and-drop.md b/_docs/promotions/promotion-scenarios/drag-and-drop.md deleted file mode 100644 index 01b0b8c03..000000000 --- a/_docs/promotions/promotion-scenarios/drag-and-drop.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Drag-and-drop promotion" -description: "Promote product apps between two environments" -group: promotions -toc: true ---- - -In this basic scenario, we'll see how to promote products in the Environments dashboard using drag-and-drop functionality. -This quick, visual method allows you to move applications across two environments in a few simple steps. - -##### Context -In the Environments dashboard, we see the `cf-101` product, in the `dev` and `qa` environments. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-prod-in-env.png" -url="/images/gitops-promotions/tutorials/dnd-prod-in-env.png" -alt="`cf-101` product in Environments dashboard" -caption="`cf-101` product in Environments dashboard" -max-width="60%" -%} - - -##### Linked applications -Mouse over `cf-101` displays the linked applications in each environment, `cf-101-dev` and `cf-101-qa`. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-apps-in-prod.png" -url="/images/gitops-promotions/tutorials/dnd-apps-in-prod.png" -alt="`cf-101-dev` and `cf-101-qa` applications" -caption="`cf-101-dev` and `cf-101-qa` applications" -max-width="60%" -%} - -##### Product versions -`cf-101` has different versions in `dev` and `qa` environments. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-prod-versions.png" -url="/images/gitops-promotions/tutorials/dnd-prod-versions.png" -alt="`cf-101` versions in environments" -caption="``cf-101` versions in environments" -max-width="60%" -%} - -##### Promotion with drag-and-drop -To promote, we'll drag `cf-101-dev` from `dev` and drop it into `cf-101` in the `qa` environment. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-action.png" -url="/images/gitops-promotions/tutorials/dnd-action.png" -alt="Drag and drop `cf-101` to promote" -caption="Drag and drop `cf-101` to promote" -max-width="60%" -%} - -##### Commit changes page -The Commit Changes page shows the action used for the promotion, the files, and the properties in the files that will be changed. -Review the files and properties that will be updated as part of this promotion action. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-commit.png" -url="/images/gitops-promotions/tutorials/dnd-commit.png" -alt="Commit changes for `cf-101`" -caption="Commit changes for `cf-101`" -max-width="60%" -%} - -##### Release creation and completion -After commit, a release is automatically created for `cf-101` with a new Release ID. -Clicking **View Release Details** takes you to the release view. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-inital-release.png" -url="/images/gitops-promotions/tutorials/dnd-inital-release.png" -alt="Running release for `cf-101`" -caption="Running release for `cf-101`" -max-width="60%" -%} - -Wait for the release to complete, and then return to the Releases page to view the Release ID updated with the current status. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/dnd-releases-page.png" -url="/images/gitops-promotions/tutorials/dnd-releases-page.png" -alt="Releases list with new release for `cf-101`" -caption="Releases list with new release for `cf-101`" -max-width="60%" -%} - -## Related articles -[Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) - - diff --git a/_docs/promotions/promotion-scenarios/multi-env-sequential-flow.md b/_docs/promotions/promotion-scenarios/multi-env-sequential-flow.md deleted file mode 100644 index 42bcb601a..000000000 --- a/_docs/promotions/promotion-scenarios/multi-env-sequential-flow.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Multi-environment sequential promotion" -description: "Promote product apps between multiple environments sequentially" -group: promotions -toc: true ---- - - -Drag-and-drop is useful for on-demand promotion to a single environment, but a sequential promotion flow is better for managing changes across multiple environments. -In this scenario, we’ll see how to set up a Promotion Flow to move changes in the `cf-101` product through three environments: `dev`, `qa`, and `production`. -We'll also trigger the promotion and monitor how the changes are orchestrated through each environment. - - ->**NOTE** -You must be an account administrator to create Promotion Flows. -For successful promotion, each environment must have an application for the product in the Promotion Flow, with a consistent repo structure. - -##### Adding Promotion Flow - -We'll go to **Settings**, from the sidebar select **Promotion Flows**, and then click **Add Promotion Flow**. - -##### Trigger Environment -The Trigger Environment is the starting point for the promotion. - -When you add a Promotion Flow, you are promoted to select the **Trigger Environment**. -We'll select `dev` as our Trigger Environment. - - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-env.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-env.png" -alt="Selecting Trigger Environment" -caption="Selecting Trigger Environment" -max-width="60%" -%} - - -The Promotion Flow has `dev` as its first environment. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-env-created.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-env-created.png" -alt="Flow Builder with first environment" -caption="Flow Builder with first environment" -max-width="60%" -%} - -##### Selecting target environments -Next, we'll select the target environments in the promotion sequence: `qa` and `production`. - - -* Mouse over the right of the `dev` environment node, displays the add icon: {::nomarkdown}{:/}. -* From the list, we'll select `qa` as the first target environment to add to the flow. -* We'll repeat the actions on the `qa` environment to add `production` as the final target environment in the flow. - - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-target-env.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-target-env.png" -alt="Add target environment" -caption="Add target environment" -max-width="60%" -%} - - - -Our Promotion Flow now has the three environments required: `dev`, `qa`, and `production`. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-all-target-envs.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-all-target-envs.png" -alt="Required environments in Promotion Flow" -caption="Required environments in Promotion Flow" -max-width="60%" -%} - -##### Saving Promotion Flow -The final step is to save the Promotion Flow by clicking **Save Promotion Flow** on the top-right. - -The **Name** is required. The flow's YAML file lists the environment sequence. - - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-save-flow.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-save-flow.png" -alt="Save Promotion Flow" -caption="Save Promotion Flow" -max-width="60%" -%} - -Clicking **Save** adds the new flow, `three-env-promotion` to the Promotion Flows page. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-flow-list.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-flow-list.png" -alt="Promotion Flow page with new flow" -caption="Promotion Flow page with new flow" -max-width="60%" -%} - -##### Triggering Promotion Flow -After creating the flow, we'll trigger it to promote changes from the trigger environment to the defined target environments. - -* **Selecting the flow** - From the list of Promotion Flows, we'll select `three-env-promotion`, and then click **Trigger** to initiate the promotion. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-flow.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-flow.png" -alt="Trigger selected Promotion Flow" -caption="Trigger selected Promotion Flow" -max-width="60%" -%} - -* **Selecting the product** - We'll select `cf-101` as the product and continue by clicking **Next**. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-flow-select-product.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-flow-select-product.png" -alt="Select product to promote" -caption="Select product to promote" -max-width="60%" -%} - -* **Selecting the application** - The application with the changes, `cf-101-dev`, is automatically selected, so we'll click **Trigger** to initiate the promotion. - - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-flow-select-app.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-trigger-flow-select-app.png" -alt="Select product's application to promote" -caption="Select product's application to promote" -max-width="60%" -%} - - -##### Monitoring release -A release is automatically created for `cf-101` with a new Release ID. -In the release view, you can see that changes are orchestrated sequentially through the environments, following the order defined in the `three-env-promotion` Promotion Flow. - - - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-promo-flow-release-view.png" -url="/images/gitops-promotions/tutorials/seq-promo-flow-release-view.png" -alt="Release view for triggered promotion" -caption="Release view for triggered promotion" -max-width="60%" -%} - - -## Related articles -[Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) - - - \ No newline at end of file diff --git a/_docs/promotions/promotion-scenarios/parallel-multi-env-promotion.md b/_docs/promotions/promotion-scenarios/parallel-multi-env-promotion.md deleted file mode 100644 index 8952cacaa..000000000 --- a/_docs/promotions/promotion-scenarios/parallel-multi-env-promotion.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Multi-environment promotion with parallel environments" -description: "Promote product apps between environments in parallel" -group: promotions -toc: true ---- - - -In this scenario, we'll build on the `three-env-promotion` flow to create a promotion flow with additional environments and parallel promotions, and save it as a new flow. - -Consider a multi-region deployment model, where you have designated primary regions for deployment, and you want promotions to pass successfully for all these regions and the production environment in parallel. - -##### Context -In the Product dashboard, the `cf-101` product has applications in several production environments. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-parallel-prod-apps.png" -url="/images/gitops-promotions/tutorials/promo-flow-parallel-prod-apps.png" -alt="Product with applications in multiple production environments" -caption="Product with applications in multiple production environments" -max-width="60%" -%} - - -##### Adding environments to Promotion Flow - -We'll add two additional production environments to `qa`: `prod-asia` and `prod-us`. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-parallel-envs.png" -url="/images/gitops-promotions/tutorials/promo-flow-parallel-envs.png" -alt="Adding parallel environments in Promotion Flow" -caption="Adding parallel environments in Promotion Flow" -max-width="60%" -%} - -Here's the Promotion Flow with the parallel environments: - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-parallel-envs-created.png" -url="/images/gitops-promotions/tutorials/promo-flow-parallel-envs-created.png" -alt="Promotion Flow with parallel environments" -caption="Promotion Flow with parallel environments" -max-width="60%" -%} - -Here's the YAML view of the Promotion Flow with the parallel environments. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-parallel-yaml-view.png" -url="/images/gitops-promotions/tutorials/promo-flow-parallel-yaml-view.png" -alt="YAML view of Promotion Flow with parallel environments" -caption="YAML view of Promotion Flow with parallel environments" -max-width="60%" -%} - - -We'll save this as `parallel-env-promotion`. - -Triggering this flow displays the parallel promotion structure in the Release view. -Promotions occur simultaneously for each environment, and the release is considered successful once all environments are promoted successfully. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/promo-flow-parallel-envs-release.png" -url="/images/gitops-promotions/tutorials/promo-flow-parallel-envs-release.png" -alt="Release view of Promotion Flow with parallel environments" -caption="Release view of Promotion Flow with parallel environments" -max-width="60%" -%} - -## Related articles -[Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) - - - \ No newline at end of file diff --git a/_docs/promotions/promotion-scenarios/policy-multi-env-promotion.md b/_docs/promotions/promotion-scenarios/policy-multi-env-promotion.md deleted file mode 100644 index 758c4638a..000000000 --- a/_docs/promotions/promotion-scenarios/policy-multi-env-promotion.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Multi-environment promotion with conditions" -description: "Promote product apps between multiple environments with promotion conditions" -group: promotions -toc: true ---- - - -Now that we have reviewed multi-environment promotion in [Multi-environment sequential promotion]({{site.baseurl}}/docs/promotions/promotion-scenarios/multi-env-sequential-flow/), let's configure policies to manage promotion conditions, ensuring that each environment’s specific requirements are met before changes are promoted. - -##### What are Promotion Policies? -Promotion Policies define the criteria for promoting changes through each environment. They govern promotion behavior through include automated tests, scans, quality checks, approvals, notifications, and more. -You can define promotion criteria through Promotion Workflows, modeled on Argo Workflows. - -* Create Promotion Workflows in Codefresh by selecting **Promotion Workflows** from the sidebar. - - - - - - -##### Assigning Policy settings - -Promotion Policies support three optional settings: -* **Pre-Action Workflow**: The workflow to run before the Promotion Action. -* **Promotion Action**: The action that promotes the changes, which defaults to Commit if not set. -* **Post-Action Workflow**: The workflow to run after the Promotion Action. - -We'll define the policy settings for the `three-env-promotion` Promotion Flow to manage promotion behavior for the `qa` and `production` target environments. - -Assigning settings is as simple as clicking the respective controls and selecting the workflows/action from the list. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-flow-pre-action.png" -url="/images/gitops-promotions/tutorials/seq-flow-pre-action.png" -alt="Policy settings for target environments" -caption="Policy settings for target environments" -max-width="60%" -%} - -For both `qa` and `production`, we'll select the same workflows and the same promotion action. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-flow-populated-policy.png" -url="/images/gitops-promotions/tutorials/seq-flow-populated-policy.png" -alt="Target environments with policy settings" -caption="Target environments with policy settings" -max-width="60%" -%} - -Here's the YAML view of the promotion flow with the workflows and promotion actions. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq--policy-flow-yaml-view.png" -url="/images/gitops-promotions/tutorials/seq--policy-flow-yaml-view.png" -alt="YAML view of policy settings" -caption="YAML view of policy settings" -max-width="60%" -%} - - -##### Triggering policy-driven Promotion Flow -We'll save the changes to the `three-env-promotion` flow, trigger it, and monitor the release view. - -In contrast to the previous release, the current release view shows the `qa` and `production` environments with the Pre- and Post-Action Workflows defined for each environment. - -{% include -image.html -lightbox="true" -file="/images/gitops-promotions/tutorials/seq-flow-release-with-workflows.png" -url="/images/gitops-promotions/tutorials/seq-flow-release-with-workflows.png" -alt="Release view for policy-driven Promotion Flow" -caption="Release view for policy-driven Promotion Flow" -max-width="60%" -%} - -## Related articles -[Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) - - - \ No newline at end of file diff --git a/_docs/promotions/releases.md b/_docs/promotions/releases.md index 308fc3d3a..b30f74c42 100644 --- a/_docs/promotions/releases.md +++ b/_docs/promotions/releases.md @@ -394,7 +394,7 @@ max-width="60%" [Promotion Flows]({{site.baseurl}}/docs/promotions/configuration/promotion-flow/) [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) [Promotion tutorials]({{site.baseurl}}/docs/promotions/promotion-scenarios/) -[Promotions: End-to-end guide]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) diff --git a/_docs/quick-start/gitops-quick-start.md b/_docs/quick-start/gitops-quick-start.md deleted file mode 100644 index 86c83e5d0..000000000 --- a/_docs/quick-start/gitops-quick-start.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "GitOps quick starts" -description: "" -group: quick-start -toc: true ---- - -Check out our GitOps quick starts to get up and running with GitOps in Codefresh. - -The quick start guides you through: -* Provisioning GitOps Runtimes -* Creating and deploying an application - - -## Provision GitOps Runtimes -Based on your deployment model, start by provisioning the Hosted or Hybrid GitOps Runtime. Hosted and Hybrid GitOps Runtimes can co-exist with each other. - - -### Hosted -Hosted GitOps Runtimes are hosted on a Codefresh cluster and managed by Codefresh. You need to provision your Hosted Runtime once for your account. - -1. [Provision a Hosted GitOps Runtime]({{site.baseurl}}/docs/quick-start/gitops-quick-start/install-hosted/) - Provision the Hosted GitOps Runtime with a single click, and complete the setup for your hosted environment. - - - -### Hybrid -Hybrid GitOps Runtimes are hosted on a customer cluster and managed by the customer. You can provision multiple Hybrid GitOps Runtimes in the same account. - -1. [Prepare for Hybrid GitOps Runtime installation]({{site.baseurl}}/docs/quick-start/gitops-quick-start/verify-requirements/) - Verify your environment matches the requirements for installing a Hybrid GitOps Runtime. -1. [Install the Hybrid GitOps Runtime]({{site.baseurl}}/docs/quick-start/gitops-quick-start/runtime/) - Install the Hybrid GitOps Runtime through Helm. - -## Create a Codefresh account -[Create an account in Codefresh]({{site.baseurl}}/docs/quick-start/create-codefresh-account/) in which to create pipelines. - - -## Deploy an application - -1. [Create an application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-ui/) - Create the `codefresh-guestbook` application in the Codefresh UI. -1. [Create and commit resources for application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-specs/) - Create rollout and service resources, and commit these resources to deploy the `codefresh-guestbook` application. -1. [Update the image tag for application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-rollout/) - Update the image for the `codefresh-guestbook` application to trigger a rollout. - - -## Streamline deployments with Environments and Products -1. [Create an Environment]({{site.baseurl}}/docs/quick-start/gitops-quick-start/gitops-products/#create-an-environment) - Create a `dev` Environment and map clusters and namespaces. -1. [Create and work with Products]({{site.baseurl}}/docs/quick-start/gitops-quick-start/gitops-products/#create--work-with-products) - Add a Product `demo-trioapp`, assign interrelated Argo CD applications to it. \ No newline at end of file diff --git a/_docs/quick-start/gitops-quick-start/create-app-specs.md b/_docs/quick-start/gitops-quick-start/create-app-specs.md deleted file mode 100644 index d7102b5c0..000000000 --- a/_docs/quick-start/gitops-quick-start/create-app-specs.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "Create & commit resources for `codefresh-guestbook` application" -description: "" -group: getting-started -sub-group: gitops-quick-start -toc: true ---- - -Now that you have created `codefresh-guestbook` as an Argo CD application, you need to deploy it. -Let's deploy the `codefresh-guestbook` application by creating and committing resources. - -You will create and commit the following resources: -1. A folder in Git to save resources for the application -1. `Rollout` resource defining the deployment strategy -1. `Service` resource to expose the application to external traffic - -### Before you begin -* [Create `codefresh-guestbook` Argo CD application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-ui/) -* Make sure [Argo Rollouts is installed]({{site.baseurl}}/docs/deployments/gitops/install-argo-rollouts/) on the target cluster - -### Create folder in Git for application resources -Create a folder in the Git repo in which to save all the resources for the `codefresh-guestbook` application. - -* In your Git repo, create a folder to store the resources needed to deploy the application. - For example, `/quick-start/` - -### Create rollout.yaml - -Create a rollout resource for the application you want to deploy. - - -To leverage Argo Rollouts' deployment capabilities, we are using Argo's `rollout` resource instead of the native Kubernetes Deployment object. -For detailed information on the fields you can define, see [Argo Rollout specification](https://argoproj.github.io/argo-rollouts/features/specification/){:target="\_blank"}. - - -* In the Git repository create the `rollout.yaml` file, as in the example below. - - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Rollout -metadata: - name: codefresh-guestbook-rollout -spec: - replicas: 4 - revisionHistoryLimit: 2 - selector: - matchLabels: - app: codefresh-guestbook - template: - metadata: - labels: - app: codefresh-guestbook - spec: - containers: - - image: gcr.io/heptio-images/ks-guestbook-demo:0.1 - name: codefresh-guestbook - ports: - - name: http - containerPort: 80 - protocol: TCP - minReadySeconds: 30 - strategy: - canary: - steps: - - setWeight: 25 - - pause: {duration: 20s} - - setWeight: 75 - - pause: {duration: 15s} -``` - -#### Fields in `rollout.yaml` - -{: .table .table-bordered .table-hover} -| Rollout Field | Notes | -| -------------- | -------------| -| `replicas` | When deployed, the rollout creates four replicas of the `codefresh-guestbook` application.| -| `revisionHistoryLimit` | The number of replica sets to retain. | -| `matchLabels` | The pods to select for this rollout. In our example, all pods with the label `codefresh-guestbook` are selected.| -| `image` | The container image for the application with the version tag, `gcr.io/heptio-images/ks-guestbook-demo:0.1` in our example.| -| `name` | The name of the application, `codefresh-guestbook` in our example. | -| `canary` | The deployment strategy, `canary` meaning that the traffic is gradually routed to the new application. Starting with `setWeight` of `25%` followed by a `pause` of 20 seconds, and the remaining `75%` after verification.| -| `templateName` | The analysis template used to validate the application metrics. Our example has the `background-analysis` template, and interfaces with Prometheus to monitor and validate metric thresholds.| - - -### Create a service resource -Create a service resource to expose your application to external traffic. - -* Create a `service.yaml` resource for the application you want to deploy, as in the example below. - >**NOTE** - Create it in the same folder in which you saved `rollout.yaml`. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: codefresh-guestbook-svc -spec: - ports: - - port: 8080 - targetPort: 80 - selector: - app: codefresh-guestbook # must be the same as the selector defined in rollouts.yaml - type: LoadBalancer -``` - -#### Fields in `service.yaml` - -{: .table .table-bordered .table-hover} -| Service field | Notes | -| -------------- | -------------- | -| `spec.ports` | The internal `port`, 8080 in our example, and external `targetPort`, 80 in our example.| -| `selector.app` | The pods to select, and MUST be identical to that defined in `rollouts.yaml`, `codefresh-guestbook` in our example.| - -### View application resources in Codefresh -Once you create and commit the `rollout` and `service` resources, return to the GitOps Apps dashboard. After selecting the application, the Current State tab displays the application's resources. - -1. In the Codefresh UI, from Ops in the sidebar, select [GitOps Apps](https://g.codefresh.io/2.0/applications-dashboard?sort=desc-lastUpdated){:target="\_blank"}. -1. Select the application. - The Current State tab is now populated with the `rollout` and `service` resources you added. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-app-current-state.png" - url="/images/getting-started/quick-start/cdops-app-current-state.png" - alt="Current State with resources for application" - caption="Current State with resources for application" - max-width="70%" - %} - -### What to do next -[(Optional) Update image tag for Argo CD application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-rollout/) \ No newline at end of file diff --git a/_docs/quick-start/gitops-quick-start/create-app-ui.md b/_docs/quick-start/gitops-quick-start/create-app-ui.md deleted file mode 100644 index 289ca8faa..000000000 --- a/_docs/quick-start/gitops-quick-start/create-app-ui.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Create `codefresh-guestbook` Argo CD application" -description: "" -group: getting-started -sub-group: gitops-quick-start -toc: true ---- - -Let's start by creating a simple Argo CD application, `codefresh-guestbook`, in the Codefresh UI. -We'll create the application without resources, and then define/add resources in the next step. - - -For detailed information, see [Creating Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/create-application/). - - -**How to** - - -1. In the Codefresh UI, from Ops in the sidebar, select [GitOps Apps](https://g.codefresh.io/2.0/applications-dashboard?sort=desc-lastUpdated){:target="\_blank"} dashboard. -1. Select **Add Application** on the top-right. -1. In the Add Application panel, add definitions for the application: - * **Application name**: `codefresh-guestbook` for the quick start. - * **Runtime**: The runtime to associate with the application, `hosted-runtime` for the quick start. - * **Name for YAML file**: The name of the application's configuration manifest, assigned on commit to Git. By default, the manifest is assigned the application name. - You can click the Edit icon and change the name, if needed. - - >**NOTE** - You cannot change the application definitions once you continue to the Configuration settings. - -{% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-add-app-settings.png" - url="/images/getting-started/quick-start/cdops-add-app-settings.png" - alt="Add Application panel" - caption="Add Application panel" - max-width="50%" - %} - -{:start="4"} -1. Select **Next** to go to the Configuration tab. - By default you are in Form mode. You can toggle between Form and YAML modes as you define the application's configuration settings. -1. Define the **General** settings for the application: - * **Repository URL**: The URL to the repo in Git where you created the YAML resource files for the application. - * **Revision**: The branch in Git with the resource files. - * **Path**: The folder in Git with the resource files. - * **Namespace**: Optional. For the quick start, we'll create a namespace for the application, entitled `quick-start`. - * **Sync Policy**: Change to **Automatic**, and select **Prune resources** to automatically remove unused resources. - * **Sync Options**: If you defined a namespace, select **Auto-create namespace** to ensure that the namespace is created if it doesn't exist. - -{% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-add-app-configuration.png" - url="/images/getting-started/quick-start/cdops-add-app-configuration.png" - alt="Add Application Quick Start: General settings" - caption="Add Application Quick Start: General settings" - max-width="70%" - %} - - -{:start="6"} -1. Retain the default **Advanced Settings**. -1. To commit all your changes, select **Commit**. - The Commit form is displayed with the application's definitions on the left, and the read-only version of the manifest with the configuration settings you defined on the right. -1. Select the **Git Source** to which to commit. - -{% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-add-app-commit.png" - url="/images/getting-started/quick-start/cdops-add-app-commit.png" - alt="Add Application Quick Start: Commit to Git" - caption="Add Application Quick Start: Commit to Git" - max-width="70%" - %} - -{:start="9"} -1. Add a commit message and then select **Commit** at the bottom-right of the panel. - You are directed to the [GitOps Apps dashboard](https://g.codefresh.io/2.0/applications-dashboard?sort=desc-lastUpdated){:target="\_blank"}. - You may have to wait for a few seconds until the application is synced to the cluster. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-add-app-dashboard.png" - url="/images/getting-started/quick-start/cdops-add-app-dashboard.png" - alt="Application dashboard with new application" - caption="Application dashboard with new application" - max-width="70%" - %} - -{:start="10"} -1. Select the application. The Current State tab does not display any resources as we have not created any resources for the application. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-app-empty-current-state.png" - url="/images/getting-started/quick-start/cdops-app-empty-current-state.png" - alt="Empty Current State for new application" - caption="Empty Current State for new application" - max-width="70%" - %} - - -In the next task, you will create and commit resources for the `codefresh-guestbook` application and deploy the application. - - -### What to do next -[Create and commit resources for `codefresh-guestbook` application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-specs/) diff --git a/_docs/quick-start/gitops-quick-start/create-gitops-ci-pipeline.md b/_docs/quick-start/gitops-quick-start/create-gitops-ci-pipeline.md deleted file mode 100644 index 5a297b780..000000000 --- a/_docs/quick-start/gitops-quick-start/create-gitops-ci-pipeline.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: "Create a basic CI delivery pipeline" -description: "" -group: getting-started -sub-group: quick-start -toc: true ---- - -Now that you have configured and run the Hello World demo pipeline, let's create a more advanced pipeline. - -For the quick start, you'll create a basic CI Delivery Pipeline in Codefresh. - -The Delivery Pipeline: -* Clones a Git repository -* Builds a docker image using `kaniko` -* Pushes the built image to a Docker Registry -* Runs an example testing step -* Sends the image information to Codefresh - -Our CI pipeline interacts with third-party services such as GitHub and a Docker Registry. You need to first add secrets to the cluster to store the credentials required. - - -### Create a Personal Access Token (PAT) -You must have a PAT to clone the repository. - - -1. Create your PAT (Personal Access Token) with a valid `expiration` date and `scope`. - Scopes: `repo` and `admin-repo.hook` - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - alt="GitHub PAT permissions for CI pipeline" - caption="GitHub PAT permissions for CI pipeline" - max-width="30%" - %} - -{:start="2"} -1. Define your PAT and namespace by replacing the values in these commands: - -``` - export GIT_TOKEN=[PAT token] - export NAMESPACE=[Codefresh runtime namespace] -``` - -1. Create a generic Kubernetes secret with your PAT token: - -``` -kubectl create secret generic github-token \ - --from-literal=token=$GIT_TOKEN --dry-run=client \ - --save-config -o yaml | kubectl apply -f - -n $NAMESPACE -``` - -### Create Docker-registry secret -To push the image to a Docker registry, we'll need the credentials on our cluster. - -> The Docker registry secret is different from the general registry secret. - -1. Export the values for the Docker registry's `server`, `username`, `password`, `email`, and `namespace`: - -``` -export DOCKER_REGISTRY_SERVER=[Server] -export DOCKER_USER=[Username] -export DOCKER_PASSWORD=[Password] -export DOCKER_EMAIL=[Email] -export NAMESPACE=[Codefresh runtime namespace] -``` - -{:start="2"} -1. Create the secret: - -``` -kubectl create secret docker-registry \ - --docker-server=$DOCKER_REGISTRY_SERVER \ - --docker-username=$DOCKER_USER \ - --docker-password=$DOCKER_PASSWORD \ - --docker-email=$DOCKER_EMAIL -n $NAMESPACE -``` - - > In the Workflow Template, the Docker registry name defaults to `docker-config`. - - -### Create general registry secret -Create a general registry secret to send the image information to Codefresh. - -1. Export the values for your registry's `username`, `password`, `domain`, and `namespace`: - -``` -export USER=[Username] -export PASSWORD=[Password] -export DOMAIN=[Domain] -export NAMESPACE=[Codefresh runtime namespace] -``` - -{:start="2"} -1. Create the secret: - -``` -kubectl create secret generic registry-creds \ - --from-literal=username=$USER \ - --from-literal=password=$PASSWORD \ - --from-literal=domain=$DOMAIN \ - --dry-run=client --save-config -o yaml | kubectl apply -f - -n $NAMESPACE -``` - -### Create the CI delivery pipeline -Now that you have defined the secrets, create the CI delivery pipeline in Codefresh. - -1. In the UI, go to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"}. -1. Select **+ Add Delivery Pipeline**. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-new-pipeline.png" - url="/images/getting-started/quick-start/quick-start-new-pipeline.png" - alt="Add Delivery Pipeline panel in Codefresh" - caption="Add Delivery Pipeline panel in Codefresh" - max-width="30%" - %} - -{:start="3"} -1. Enter a name for the delivery pipeline. - The name is created from the names of the sensor and the trigger event for the delivery pipeline. - * **Sensor Name**: The name of the sensor resource, for example, `sensor-cf-ci`. - * **Trigger Name**: The event configured in the sensor to trigger the Workflow Template, for example, `push-cf-ci`. -1. From the list of **Git Sources**, select the Git Source to which to commit the resources for this delivery pipeline. - > Do not select the marketplace Git Source as you cannot commit to it. - If you have multiple runtimes installed, the Git Source you select also determines the runtime that executes the pipeline. -1. Select **Next**. - In the **Configuration** tab, **Workflow Templates** is selected. This is our CI Starter Workflow Template, that builds a Docker image using Kaniko, reports image metadata to Codefresh, and tests the image. -1. Select **Trigger Conditions**. -1. From the **Add** dropdown, select **Git Events**. -1. In the **Git Repository URLs** field, select one or more GitHub repositories to listen to for the selected event. -1. From the **Event** dropdown, select the event, in our case, **Commit pushed**. - Codefresh displays all the **Arguments** available for the selected event. - You can map each argument to a single or combination of predefined variables, which Codefresh automatically maps to the correct path when you commit the changes. Argo Workflow then instantiates the values from the event payload. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-ci-pipeline-arguments.png" - url="/images/getting-started/quick-start/quick-start-ci-pipeline-arguments.png" - alt="Predefined variables for arguments" - caption="Predefined variables for arguments" - max-width="30%" - %} - - In each field, type `$` and from the list of predefined variables, select each of these in turn: - - * **REPO**: Required. The repository to clone during the build step. Select `Repository name`. - * **IMAGE_NAME**: Required. The name for the built image. Enter the name in the format `([docker_url]/[account]/[image_name]`. - * **TAG**: Optional. The tag for the built image. If not defined, uses the default tag `latest`. Enter `1.0`. - * **GIT_REVISION**: Optional. The Git revision to report to Codefresh. Select `Git revision`. - * **GIT_BRANCH**: Optional. The Git branch to report to Codefresh. Select `Git branch`. - * **GIT_COMMIT_URL**: Optional. The Git commit URL to report to Codefresh. Select `Commit url`. - * **GIT_COMMIT_MESSAGE**: Optional. The Git commit message to report to Codefresh. Select `Commit message`. - - You are now ready to commit the delivery pipeline to the Git Source. - -{:start="10"} -1. Select **Apply**, and then **Commit** on the top-right. - The Commit Changes panel shows the files to be committed. -1. Enter the commit message and then select **Commit**. -1. In the **Delivery Pipelines** page to which you are redirected, verify that your pipeline is displayed. - - Behind the scenes, we committed the pipeline to your Git repository and synced the resources to your cluster. - It may take a few seconds for the Git-to-cluster sync to complete, and then your pipeline should be displayed. - -### Trigger the pipeline with a Git commit event -Make a change to a file in the Git repository to trigger the pipeline. - -1. Go to the Git repository selected for the trigger condition. -1. Make a change to any file to get a commit event. -1. In the UI, go back to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"} to see the new workflow for the pipeline. - -Continue to tweak the pipeline and enhance its capabilities. - - -### What to do next -If you have not created an application in Codefresh, continue with: - -[Create resources for codefresh-guestbook application]({{site.baseurl}}/docs/getting-started/quick-start/create-app-specs) - diff --git a/_docs/quick-start/gitops-quick-start/create-rollout.md b/_docs/quick-start/gitops-quick-start/create-rollout.md deleted file mode 100644 index 6300a7ad9..000000000 --- a/_docs/quick-start/gitops-quick-start/create-rollout.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Update image tag for `codefresh-guestbook` application" -description: "" -group: getting-started -sub-group: gitops-quick-start -toc: true ---- - -You will now make a change in the `codefresh-guestbook` application manifest, and update the image tag. -Because we selected auto-sync in the application settings, Argo CD detects that the live state in the cluster is out of sync with the desired state in Git, and triggers the new rollout. - -### Before you begin - -* [Create & commit resources for `codefresh-guestbook` application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-specs/) - - -### Update image tag in rollout.yaml -Update the image tag in the `codefresh-guestbook` application. - -1. Go to the Git repo with `rollout.yaml`. -1. Update the image tag from `0.1` to `0.2` as in the example below. - -```yaml -... -template: - metadata: - labels: - app: codefresh-guestbook - spec: - containers: - - image: gcr.io/heptio-images/ks-guestbook-demo:0.2 - name: codefresh-guestbook - ports: - - name: http - containerPort: 80 - protocol: TCP -... -``` - -{:start="3"} -1. Commit the change. - -### View the rollout in the GitOps Apps dashboard -When the image tag is updated, the auto-sync initiates the rollout. - -1. Go back to the [GitOps Apps](https://g.codefresh.io/2.0/applications-dashboard?sort=desc-lastUpdated){:target="\_blank"} dashboard. -1. Select the application you created. - The deployment entry for the application is displayed as progressing. - - {% include - image.html - lightbox="true" - file="/images/quick-start/cdops-app-rollout-in-dashboard.png" - url="/images/quick-start/cdops-app-rollout-in-dashboard.png" - alt="Application dashboard with rollout in progress" - caption="Application dashboard with rollout in progress" - max-width="60%" - %} - -{:start="3"} -1. To visualize the rollout analysis, click the rollout name. - - {% include - image.html - lightbox="true" - file="/images/quick-start/cdops-app-rollout-panel.png" - url="/images/quick-start/cdops-app-rollout-panel.png" - alt="Rollout analysis in progress" - caption="Rollout analysis in progress" - max-width="60%" - %} - -{:start="4"} -1. To view metric validation details, expand **Background Analysis** in the panel. - -You have now created and deployed an Argo CD application in Codefresh. - - -### What to do next -[Work with Environments & Products]({{site.baseurl}}/docs/quick-start/gitops-quick-start/gitops-products/) - - - - - \ No newline at end of file diff --git a/_docs/quick-start/gitops-quick-start/gitops-products.md b/_docs/quick-start/gitops-quick-start/gitops-products.md deleted file mode 100644 index fdfd68950..000000000 --- a/_docs/quick-start/gitops-quick-start/gitops-products.md +++ /dev/null @@ -1,456 +0,0 @@ ---- -title: "Quick start: Environments & Products in Codefresh GitOps" -description: "Understand and leverage power of Codefresh's Environment and Product entities for applications" -group: quick-start -toc: true ---- - - -If you've been working with Codefresh GitOps, you're likely familiar with managing Argo CD applications in Codefresh. From creating them to monitoring application deployments and resources. - -If you're new to Codefresh GitOps, start with our [quick start on Argo CD applications]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-ui/) to familiarize yourself with Argo CD applications in Codefresh. - -This quick start focuses on introducing you to the next-generation features for a new development and deployment experience in Codefresh GitOps: Environments and Products! -For detailed information on all tasks and features, refer to the articles on [Environments]({{site.baseurl}}/docs/dashboards/gitops-environments/) and [Products]({{site.baseurl}}/docs/products/about-products/). - -We'll begin by exploring the key benefits of Environments and Products. -And then guide you through how to work with these both to streamline and empower your software development lifecycle. - -### Why would you want to create Environments? - -Here are some key benefits of Environments: - -* **Mirror your SDLC** - Codefresh Environments are designed to mirror your software development life cycle (SDLC). By aligning applications with their development stages, Environments offer a clear and contextual view of the entire application lifecycle, as it moves from development to production. - -* **Effortless creation** - Creating an Environment in Codefresh is straightforward and intuitive. All you need is a unique name and the Kubernetes clusters and namespaces to associate with the Environment. - -* **Contextual visibility** - Environments consolidate Kubernetes clusters and namespaces, providing a unified view of all Argo CD applications deployed within. This centralized perspective allows teams to effortlessly track application deployments across various clusters and namespaces, enhancing operational transparency. - -* **Simple scalability and maintenance** - Environments are equally simple to scale and maintain as they are to create. Whether expanding infrastructure or adapting to evolving project requirements, scaling is as simple as adding more Environments, or adding more clusters or namespaces to existing Environments. - For flexibility, Codefresh allows you to also add Environments without deploying any applications to them. - - {% include - image.html - lightbox="true" - file="/images/gitops-environments/argo-apps-organized-into-envs.png" - url="/images/gitops-environments/argo-apps-organized-into-envs.png" - alt="Quick start: Representation of an Environment in Codefresh GitOps" - caption="Quick start: Representation of an Environment in Codefresh GitOps" - max-width="60%" -%} - -### What do you get from Products? - -Now that we have briefly explored what you can accomplish with Environments, let's see how Products in Codefresh GitOps complement Environments. - -{% include - image.html - lightbox="true" - file="/images/gitops-products/apps-grouped-by-product.png" - url="/images/gitops-products/apps-grouped-by-product.png" - alt="Quick start: Representation of a Product in Codefresh GitOps" - caption="Quick start: Representation of a Product in Codefresh GitOps" - max-width="60%" -%} - -* **Unified application management** - Managing complex Argo CD applications across multiple Environments can be challenging. - By grouping similar Argo CD applications into a unit, Products allow you to also efficiently manage them cohesively. - -* **Bridging applications and Environments** - Products act as a bridge between applications and their respective Environments. By linking applications to Products, you can easily track their deployment across different environments, providing clarity and control over your deployment pipelines. - -* **Effortless creation** - As with Environments, creating a Product is equally straightforward. You can create Products from the UI, or declaratively through annotations in your application manifests. - -* **Real-time insights with integrated views** - The Products dashboard offers three distinct views - Pods, Git, and Features. These views provide real-time insights into the changes in the application repo, deployment details, code changes, and feature tracking. Whether you're a developer tracking the latest commits or a project manager monitoring feature releases, these integrated views offer valuable insights tailored to your role. - - -We'll now take you through the key tasks and functionality, starting with Environments. - -## Create an Environment -First, you'll need to set up an Environment. Environments mirror the deployment lifecycle of your software, so create as many as you need to match your process. - -Typically, organizations use environments like `development`, `qa`, `staging`, and `production`, but you can customize these to suit your needs. There's no cap on the number of Environments you can set up. - -For this quick start, we'll set up just three Environments, `dev`, `qa`, and `prod`. - - -1. In the Codefresh UI, from Ops in the sidebar, select **Environments**, and then click **Add Environment**. -1. Define the following: - 1. **Name**: A unique name for your GitOps Environment, which is meaningful in the context of your development and deployment cycle. - For the quick start, we'll use `dev`. - 1. **Kind**: The purpose of this GitOps Environment. Select **Non-production** where development, testing, staging versions of applications are deployed. - Just a heads up that we will use this to define permissions for ABAC (Attribute Based Access Control). - 1. **Tags**: Leave this empty for the quick start. - 1. **Clusters and Namespaces**: Single or multiple cluster/namespace/cluster-namespace pairs to map to the GitOps Environment. - The Environment is populated by all the applications deployed to the mapped clusters and namespaces. - To include all namespaces in a cluster, leave the Namespace empty. - For the quick start, we'll add the `in-cluster` and the `demo-ta-dev` namespace. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/environment-add.png" - url="/images/quick-start/environments-products/environment-add.png" - alt="Quick start: Create an Environment" - caption="Quick start: Create an Environment" - max-width="60%" -%} - -{:start="3"} -1. Click **Add**. - The environment is displayed in the Environments dashboard. -1. Repeat _step 1_ through _step 3_ to create the two other Environments: `qa` and `prod`. - -## Create & work with Products -After creating at least one Environment, we can start creating Products and connect Argo CD applications to it. We'll conclude with key insights in the Products dashboard. - -### (Optional) Create applications -If you don't have Argo CD applications, fork the example repository and create three applications for each of the environments we created above. -Otherwise, continue with [Identify applications in GitOps Apps dashboard](#identify-applications-in-gitops-apps-dashboard). - -1. Fork the repository: [https://github.com/idan-codefresh/promotion-example/tree/main/example-manifests/trio-app](https://github.com/idan-codefresh/promotion-example/tree/main/example-manifests/trio-app){:target="\_blank"}. -1. In the Codefresh UI, from Ops in the sidebar, select **GitOps Apps**. -1. Click **Add Application**. -1. Define these settings for **Source**: - * **Repository URL**: `https://github.com//promotion-example.git` - * **Revision**: `main` - * **Path**: `example-manifests/trio-app/trio-dev` -1. Leave the rest of the settings unchanged. -1. Commit the changes. -1. Repeat _step 2_ through _step 5_ to create the `trio-qa` and `trio-prod` applications. - - -### Identify applications in GitOps Apps dashboard - -Let's first identify the applications you want to group as a Product in the GitOps Apps dashboard. -Look for different versions of the same software deployed in different Environments, utilizing similar microservices and dependencies. -These are the applications ideal for grouping and monitoring as a Product. - -For instance, consider three versions of the `demo-trioapp` application: `demo-trioapp-dev`, `demo-trioapp-qa`, and `demo-trioapp-prod`. We'll group these into a Product. - - -{% include -image.html -lightbox="true" -file="/images/quick-start/environments-products/products-gitops-apps.png" -url="/images/quick-start/environments-products/products-gitops-apps.png" -alt="Argo CD applications in GitOps Apps dashboard" -caption="Argo CD applications in GitOps Apps dashboard" -max-width="70%" -%} - - -### Create the `demo-trioapps` Product -Once you identify the applications, create the Product. -A Product requires a unique name, and optionally an annotation to connect the different Argo CD applications. - -##### Before you begin -* Make sure you have [created at least one Environment](#create-an-environment) - -##### How to - -1. In the Codefresh UI, from Ops in the sidebar, select **Products**. -1. Click **Add Product**. -1. Define the following: - 1. **Name**: A unique name for the Product, `demo-trioapps` for the quick start. - 1. **Connect Applications**: The annotation to associate with this Product, and use to connect the different applications to it. - For the quick start, we'll use the default annotation automatically created, `codefresh.io/product: demo-trioapps`. - 1. Copy the annotation to the clipboard. - 1. **Tags**: Leave this empty for the quick start. - - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-create.png" - url="/images/quick-start/environments-products/products-create.png" - alt="Create Product" - caption="Create Product" - max-width="60%" -%} - -{:start="4"} -1. Click **Add**. - The Product is displayed in the Products dashboard. -1. Click the Product name to view details. - You'll notice that the Product currently has no assigned applications. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-no-apps-assigned.png" - url="/images/quick-start/environments-products/products-no-apps-assigned.png" - alt="Quick start: New Product with no applications" - caption="Quick start: New Product with no applications" - max-width="60%" -%} - -## Assign applications to Product `demo-trioapp` -The next step is to assign applications to the Product you created, `demo-trioapp` in our case for the quick start. - -Codefresh offers two methods: -* Manual assignment from the Products dashboard - This method is a single-click action for quick assignment from the UI. Unlike other UI actions, manual assignment does not require a commit action. - Recommended for trying and testing rather than as the go-to method. - -* Declarative assignment through annotations - This method defines an annotation with the Product name in the application manifest. - If the Product doesn't exist, Codefresh automatically creates one for you. - Recommended as the go-to method as it is fully GitOps-compatible. - -### Manually assign application to a Product -Here we'll manually assign the application `demo-trioapp-dev` to the Product `demo-trioapps` from the Products dashboard. - - -1. In the Codefresh UI, from Ops in the sidebar, select **Products**. -1. Expand the new Product, `demo-trioapp` in our case. -1. Click **Manage Apps**. - On the left, you'll see the list of **Unassigned apps**, including `demo-trioapp-dev`, `demo-trioapp-qa`, and `demo-trioapp-prod`. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-unassigned-apps.png" - url="/images/quick-start/environments-products/products-unassigned-apps.png" - alt="Quick start: `demo-trioapps` Product with unassigned applications" - caption="Quick start: `demo-trioapps` Product with unassigned applications" - max-width="60%" -%} - -{:start="4"} -1. From the list of **Unassigned apps**, click {::nomarkdown}{:/} next to the application to assign, `demo-trioapp-dev` in our case. - - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-manually-assign-apps.png" - url="/images/quick-start/environments-products/products-manually-assign-apps.png" - alt="Quick start: Manually assign `demo-trioapp-dev` to Product" - caption="Quick start: Manually assign `demo-trioapp-dev` to Product" - max-width="60%" -%} - -{:start="5"} -1. To confirm, click **Save**. - Codefresh adds the application to the Environment defined for it. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-manually-assigned-app.png" - url="/images/quick-start/environments-products/products-manually-assigned-app.png" - alt="Quick start: `demo-trioapp-dev` assigned to Product in defined Environment" - caption="Quick start: `demo-trioapp-dev` assigned to Product in defined Environment" - max-width="60%" -%} - - -### Add annotation to connect application to Product -Now, let's connect an application to a Product declaratively, by adding an annotation to the application's manifest. -For the quick start, we'll use the default annotation Codefresh generated when we created the Product, to connect `demo-trioapp-prod`. - -1. If needed, copy the Product's annotation. - If not, continue from _Step 2_. - 1. In the Products dashboard, mouse over the row with the Product name, and then select **Edit** {::nomarkdown}{:/}. - 1. Copy the annotation and close the form. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-copy-annotation.png" - url="/images/quick-start/environments-products/products-copy-annotation.png" - alt="Quick start: Copy annotation from Product" - caption="Quick start: Copy annotation from Product" - max-width="50%" -%} - -{:start="2"} -1. Add the annotation to the application's manifest: - 1. From Ops in the sidebar, select **GitOps Apps**. - 1. Select the application to which to add the annotation, `demo-trioapp-prod` for the quick start. - 1. Click the **Configuration** tab and switch to **YAML** format. - 1. Add the annotation as in the example below. - 1. Commit to save the changes. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-add-annotation-manifest.png" - url="/images/quick-start/environments-products/products-add-annotation-manifest.png" - alt="Quick start: Add annotation to `demo-trioapp-prod` manifest" - caption="Quick start: Add annotation to `demo-trioapp-prod` manifest" - max-width="60%" -%} - -{:start="3"} -1. Return to the Products dashboard and select the Product, `demo-trioapp` in our case. - Both applications are now displayed as part of the Product. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-dashboard-apps.png" - url="/images/quick-start/environments-products/products-dashboard-apps.png" - alt="Quick start: `demo-trioapp-dev` and `demo-trioapp-prod` assigned to Product" - caption="Quick start: `demo-trioapp-dev` and `demo-trioapp-prod` assigned to Product" - max-width="60%" -%} - - - - -### Explore the Products dashboard - -Here's an example of the Products dashboard. - - -{% include - image.html - lightbox="true" - file="/images/gitops-products/expanded-view.png" - url="/images/gitops-products/expanded-view.png" - alt="GitOps Products dashboard (expanded view)" - caption="GitOps Products dashboard (expanded view)" - max-width="60%" -%} - -The Products dashboard showcases the Products created, whether or not applications are connected. -Clicking a Product provides detailed information on its applications. - -For this quick start, we'll focus on two key features: release versions and integrated insights into applications. - -### Release versions -Helm-based applications show the release version of the application. This is the _app version_ as defined in the Helm chart, identifying the specific release version in the different Environments. - -You can: -* View the application's dependencies and their versions - This is useful to identify which version is deployed where. -* Compare release versions of the dependencies across deployments in different Environments - This is useful for troubleshooting as you can identify if the version that works in dev is the same as the version with the problem in staging. - - -##### View dependencies -1. Click the version to display the application's dependencies. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-app-version-number.png" - url="/images/quick-start/environments-products/products-app-version-number.png" - alt="Quick start: Helm chart version for application" - caption="Quick start: Helm chart version for application" - max-width="60%" -%} - - -##### Compare deployed versions across applications -Compare the dependency versions in the different applications associated with the Product. - -1. In the same panel, enable **Compare**. -1. Click within the field **Select applications to compare**, and select the applications. - * For up to two applications, switch between **YAML** and **Table** views. - * For more than two applications, the comparison view automatically switches to **Table**. - -In this quick start, dependency versions are identical across all three applications. - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/products-app-version-compare.png" - url="/images/quick-start/environments-products/products-app-version-compare.png" - alt="Quick start: Dependency versions across applications" - caption="Quick start: Dependency versions across applications" - max-width="60%" -%} - -### Integrated insights into Product applications - -Products offer more than just standard Git commit or hash information by providing enriched insights into your applications. - -When you select a Product in the Products dashboard, three tabs appear on the right: **Pods**, **Git**, and **Features**. These tabs consolidate Kubernetes (Pods), version control (Git), and issue-tracking (Features) data into a single location. - -##### Git -In the Git tab, you gain direct insights from the application repository, not the GitOps repository. This allows you to trace the complete commit history of the application's repo up to the commit that initiated the build and deployed the new version. Commit history includes history of individual commits with deep links to source control. - -##### Features -The Features tab allows you to connect these commits with tickets in your issue-tracking tool or system. This integration enhances traceability and context, enabling you to monitor the deployment's impact by tying deployed features to specific feature requests or bug fixes. - -From this unified view, you can: -* Gain insights into deployment specifics -* Review all commits leading up to the latest one that triggered the deployment -* Align deployed features with related feature requests -* Effectively track deployment timelines - - - -**Why are these insights crucial?** -When troubleshooting issues in production, having access to such comprehensive information is invaluable. You can pinpoint what occurred, when it happened, who made the change, and which feature or bug was addressed, streamlining your debugging process. - - - -#### Requirement: Connect your CI platforms/tools to GitOps -To view this integrated information from Git and issue-tracking systems in the Products dashboard, you need to tie your CI system with your CD system. -If you have CI platforms/tools already in place, be it Codefresh pipelines, GitHub Actions, or Jenkins, you can integrate them with Codefresh GitOps. The same applies to issue-tracking tools like Jira. - -For an overview of the process, see [Image enrichments with GitOps integrations]({{site.baseurl}}/docs/gitops-integrations/image-enrichment-overview/). - -Once these integrations are in place, Codefresh takes care of the heavy lifting and retrieves the information from the different tools. -You can view this information in the Products dashboard when selecting a Product, as shown below, and also in our [Images dashboard]({{site.baseurl}}/docs/dashboards/images/). - - -#### Pods - -When you select a Product, the Pods tab is the tab in focus by default. -Here's a view of the Pods tab with Rollout information. - - -{% include - image.html - lightbox="true" - file="/images/gitops-products/pod-view-rollouts.png" - url="/images/gitops-products/pod-view-rollouts.png" - alt="Quick start: Pod view of application with Rollouts" - caption="Quick start: Pod view of application with Rollouts" - max-width="60%" -%} - -#### Git - - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/product-git-info.png" - url="/images/quick-start/environments-products/product-git-info.png" - alt="Products: Git view of applications" - caption="Products: Git view of applications" - max-width="60%" -%} - -#### Features - - -{% include - image.html - lightbox="true" - file="/images/quick-start/environments-products/product-features-info.png" - url="/images/quick-start/environments-products/product-features-info.png" - alt="Quick start: Features view of applications" - caption="Quick start: Features view of applications" - max-width="60%" -%} - - - -Try out more functionality in Environments and Products. - - - diff --git a/_docs/quick-start/gitops-quick-start/hello-world.md b/_docs/quick-start/gitops-quick-start/hello-world.md deleted file mode 100644 index 020110746..000000000 --- a/_docs/quick-start/gitops-quick-start/hello-world.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Trigger the Hello World example pipeline" -description: "" -group: getting-started -sub-group: quick-start -toc: true ---- - -Now that you have successfully installed the hybrid runtime, you can trigger one of the Hello World demo pipelines included in the runtime package. -The two Hello World example pipelines are triggered by different event conditions: -* Git (GitHub) event -* Calendar (cron) event - -For the quick start, let's focus on the `github/hello-world` pipeline. - -### Create a PAT token -To commit resources for the `github/hello-world` pipeline, you need to add a PAT to Codefresh. - -1. Create your personal token with a valid `expiration` date and `scope` with `base64` encoding. - For the pipeline, you need `repo` and `admin-repo.hook` scopes: - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - alt="GitHub PAT permissions for Hello World pipeline" - caption="GitHub PAT permissions for Hello World pipeline" - max-width="30%" - %} - -{:start="2"} -1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}, add your token. - -### View pipelines -View the pipelines in Codefresh. - -1. In the Codefresh UI, go to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"}. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-pipelines.png" - url="/images/getting-started/quick-start/quick-start-pipelines.png" - alt="Demo pipelines in the Pipelines page" - caption="Demo pipelines in the Pipelines page" - max-width="30%" - %} - - * The `github/hello-world` pipeline has not been triggered as it requires a Git event to trigger it. - * The `cron/hello-world` pipeline shows statistics as it has already been triggered based on the `cron` interval. - -### View and update manifest -As we don't have a workflow for this pipeline, you will configure the Git Source resource in the pipeline's **Manifest** tab. -1. In the **Pipelines** page, to drill down, select the pipeline name. -1. Select the **Manifest** tab, and click the arrowhead to expand the resource view. - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-manifest-expand.png" - url="/images/getting-started/quick-start/quick-start-manifest-expand.png" - alt="Expand resource view in Mainfests tab" - caption="Expand resource view in Mainfests tab" - max-width="30%" - %} - - You can see these resources: - - * Event Source (`event-source.git-source.yaml`). - * Sensor (`sensor.git-source.yaml`) - * Workflow Template (`workflow-template.hellow-world.yaml`) - - - > The pipeline is configured to run on a `PUSH` event in the Git repository. - - -Codefresh does the following: -* Commits the changes to your Git repository. -* Synchronizes the changes in Git back to your cluster, and updates the `event-source.git-source` resource. -* Triggers this pipeline after the `PUSH` event to your repository. -* Creates a workflow. View it in the UI, in the [Workflows](https://g.codefresh.io/2.0/workflows){:target="\_blank"} dashboard. - Select view workflow details to see the workflow log. - -### What to do next -[Create a basic CI pipeline]({{site.baseurl}}/docs/getting-started/quick-start/create-ci-pipeline) diff --git a/_docs/quick-start/gitops-quick-start/install-hosted.md b/_docs/quick-start/gitops-quick-start/install-hosted.md deleted file mode 100644 index 89ead4b97..000000000 --- a/_docs/quick-start/gitops-quick-start/install-hosted.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: "Provision a Hosted GitOps Runtime" -description: "Install the GitOps Runtime hosted by Codefresh" -group: getting-started -sub-group: gitops-quick-start -toc: true ---- - -If you have Hosted GitOps, set up your hosted Runtime environment: - -1. Provision the Hosted GitOps Runtime with a single click. -1. Authorize access through your OAuth token to the organization where Codefresh creates the Git runtime repo and the [Shared Configuration Repo]({{site.baseurl}}/docs/installation/gitops/shared-configuration/). -1. Connect to an external K8s cluster with access to the internet, to which you can deploy applications. - This is important as you cannot deploy to the in-cluster with the Hosted GitOps Runtime. -1. Install Argo Rollouts on the cluster. - -Read our [blog on Hosted GitOps](https://codefresh.io/blog/codefresh-upends-continuous-delivery-with-hosted-gitops-platform-featuring-dora-dashboards-and-first-class-integrations-for-ci/). -For detailed information on each of the steps below, see [Set up a Hosted GitOps Runtime environment]({{site.baseurl}}/docs/installation/gitops/hosted-runtime/). - -## Before you begin - -Verify that you have: -* A Kubernetes cluster with access to the internet -* An OAuth token - -## How to -1. In the Codefresh UI, go to Codefresh [Home Dashboard](https://g.codefresh.io/2.0/?time=LAST_7_DAYS){:target="\_blank"}. - -{% include -image.html -lightbox="true" -file="/images/runtime/hosted-gitops-initial-view.png" -url="/images/runtime/hosted-gitops-initial-view.png" -alt="Hosted GitOps setup" -caption="Hosted GitOps setup" -max-width="80%" -%} - -{:start="2"} -1. Provision the Hosted GitOps Runtime: - * Click **Install**, and wait for Codefresh to complete provisioning your Hosted GitOps Runtime (may take up to ten minutes). - -{% include -image.html -lightbox="true" -file="/images/runtime/hosted-installing.png" -url="/images/runtime/hosted-installing.png" -alt="Installing hosted runtime" -caption="Installing hosted runtime" -max-width="80%" -%} - -{:start="3"} -1. Select the Git organization for the runtime installation and the Shared Configuration Repo: - * Click **Connect**. - * Click **Authorize Access** and enter your OAuth token. - * Select the **Git Organization for which to create the repos**. - * Click **Create**. - Codefresh creates the two Git repositories in the paths shown. - - {% include -image.html -lightbox="true" -file="/images/runtime/hosted-connect-git.png" -url="/images/runtime/hosted-connect-git.png" -alt="Connect to Git provider" -caption="Connect to Git provider" -max-width="80%" -%} - -{:start="4"} -1. Connect a K8s cluster: - * Click **Connect**. - * In the Add Managed Cluster panel, copy the command `cf cluster add`, and run it in the terminal. - * When prompted to select the `kube-context`, select from the list of available clusters as defined in `kubeconfig`. - * Verify that you have configured access to the required IP addresses required. See [Codefresh IP addresses]({{site.baseurl}}/docs/administration/platform-ip-addresses/). - -{% include -image.html -lightbox="true" -file="/images/runtime/hosted-connect-cluster-step.png" -url="/images/runtime/hosted-connect-cluster-step.png" -alt="Connect a K8s cluster for hosted runtime" -caption="Connect a K8s cluster for hosted runtime" -max-width="70%" -%} - -{:start="5"} -1. Install Argo Rollouts on the cluster you added. You'll need this to apply the `rollout` resource we will create for the application in the next task. - * Go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. - * In either the **List View** or **Topology View**, click the name of the cluster on which to install Argo Rollouts. - * Click **+ Install Argo Rollouts**. - -{% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/cdops-app-install-rollout.png" - url="/images/getting-started/quick-start/cdops-app-install-rollout.png" - alt="Install Argo Rollouts on managed cluster" - caption="Install Argo Rollouts on managed cluster" - max-width="50%" - %} - -You are now ready to create and deploy an Argo CD application. - -## What to do next -[Create resources for codefresh-guestbook application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-specs/) - diff --git a/_docs/quick-start/gitops-quick-start/runtime.md b/_docs/quick-start/gitops-quick-start/runtime.md deleted file mode 100644 index 9059a8a54..000000000 --- a/_docs/quick-start/gitops-quick-start/runtime.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: "Install Hybrid GitOps Runtime" -description: "Install the Helm-based Hybrid GitOps Runtime" -group: getting-started -sub-group: quick-start -toc: true ---- - - - -Get up and running with Codefresh by installing the Hybrid Runtime for GitOps via Helm. -The Runtime is installed through a Helm chart. The Codefresh `values.yaml` is located [here](https://github.com/codefresh-io/gitops-runtime-helm/blob/main/charts/gitops-runtime/){:target="\_blank"}. It contains all the arguments that can be configured, including optional ones, with descriptions of each. - -## Quick start assumptions - -The quick start assumes that you are installing the first Hybrid GitOps Runtime in your Codefresh account. - -## Argo project components & CRDs -Hybrid GitOps installation requires a cluster without Argo project components and CRDs (Custom Resource Definitions). - -Argo project components include Argo Rollouts, Argo CD, Argo Events, and Argo Workflows. - -You can handle Argo project CRDs outside the chart, or as recommended, adopt the CRDs to be managed by the GitOps Runtime Helm release. - -If you already have Argo project CRDs on your cluster, do one of the following: -* Handle Argo projects CRDs outside of the chart (see [Argo's readme on Helm charts](https://github.com/argoproj/argo-helm/blob/main/README.md){:target="\_blank"}) - Disable CRD installation under the relevant section for each of the Argo projects in the Helm chart:
- `--set .crds.install=false`
- where:
- `` is the argo project component: `argo-cd`, `argo-workflows`, `argo-rollouts` and `argo-events`. - -* Adopt the CRDs
- Adopting the CRDs allows them to be managed by the `gitops-runtime helm release`. Doing so ensures when you upgrade the Hybrid GitOps Runtime, the CRDs are also automatically upgraded. - - Run this script _before_ installation: - -``` -#!/bin/sh -RELEASE= -NAMESPACE= -kubectl label --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) app.kubernetes.io/managed-by=Helm -kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-name=$RELEASE -kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-namespace=$NAMESPACE -``` - -### Tunnel-based Runtime -Hybrid GitOps Runtimes support tunnel-based, ingress-based, and service-mesh-based access modes. -For the quick start, we'll use the tunnel-based mode which is the default access mode that does not require an ingress controller. -For details on these access modes, review [GitOps Runtime architecture]({{site.baseurl}}/docs/installation/gitops/runtime-architecture/). - -### GitHub as Git provider -Hybrid GitOps Runtimes require a Git Runtime token for authentication to the Git installation repository based on your Git provider, and a Git user token to authenticate Git-based actions for the Runtime. -The quick start uses GitHub as the Git provider. For other Git providers and token requirements, see [Git providers and Git runtime tokens]({{site.baseurl}}/docs/security/git-tokens/#git-runtime-token-scopes). - -Have your GitHub Runtime token with a valid expiration date and access permissions ready for Runtime installation: - * Expiration: Either the default of 30 days or any duration you consider logical. - * Access scopes: Set to `repo` and `admin-repo.hook` - - {% include - image.html - lightbox="true" - file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" - alt="GitHub PAT permissions" - caption="GitHub PAT permissions" - max-width="30%" - %} - - If you need detailed information on GitHub tokens, see the [GitHub article](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -### Shared Configuration Repository -When you select the Git provider, Codefresh prompts you to also select the Shared Configuration Repository for your account. The repo stores account-level configuration settings and manifests. -Because the Shared Configuration Repo is defined at the account-level, the Git provider you select for the first Runtime in your account is used for all the other Runtimes in the same account. -Read up on the [Shared Configuration Repository]({{site.baseurl}}/docs/installation/gitops/shared-configuration/). - -## Install Hybrid GitOps Runtime - -##### Before you begin -* Make sure your cluster does not have [Argo project components & CRDs](#argo-project-components--crds) - -##### How to - -1. In the Welcome page, select **+ Install Runtime**. -1. From Runtimes in the sidebar, select **GitOps Runtimes**. -1. Click **Hybrid Runtimes**, and then click **Add**. -1. Set up your Git provider account: - 1. If not GitHub, select the Git provider. - 1. Define the provider's API URL. - 1. Define the URL of the **Shared Configuration Repository**. - 1. Click **Next**. -1. Install the Hybrid GitOps Runtime: - 1. Click **Generate** to create a new API key. - 1. Retain the default values for the GitOps Runtime name and namespace, `codefresh`. - 1. Copy the command in _Step 3_ and run it to install the Helm chart for the Hybrid GitOps Runtime: - where: - * `cf-gitops-runtime` is the default name of the Helm release, which you can change if needed. - * `codefresh` is the default namespace in which to install the Hybrid GitOps runtime. - * `` is mandatory for _tunnel-based Hybrid GitOps Runtimes_, and is automatically populated by Codefresh in the command. - * `` is the API key you generated, and is automatically populated in the command. - * `codefresh` is the default name of the Runtime. - * `oci://quay.io/codefresh/gitops-runtime` is the name of the Helm chart, predefined by Codefresh, and cannot be changed. - -{% include -image.html -lightbox="true" -file="/images/runtime/helm/helm-install-hybrid-runtime.png" -url="/images/runtime/helm/helm-install-hybrid-runtime.png" -alt="Quick Start: Install Hybrid GitOps Runtime" -caption="Quick Start: Install Hybrid GitOps Runtime" -max-width="60%" -%} - -{:start="6"} -1. Wait for a few minutes, and then click **Close**. - You are taken to the List View for GitOps Runtimes where you can see the Hybrid GitOps Runtime you added with a green dot indicating that it is online, and the Type column for the Runtime displaying Helm. -1. Complete the installation by clicking **Configure as Argo Application**. - There is no need for any further action from you, as Codefresh takes care of the configuration. - By configuring the Hybrid GitOps Runtime as an Argo Application, you can ensure that GitOps is the single source of truth for the Runtime, and view and monitor Runtime components. - - -You are now ready to create and deploy a GitOps application in Codefresh. - - -## What to do next -[Create resources for codefresh-guestbook application]({{site.baseurl}}/docs/quick-start/gitops-quick-start/create-app-specs/) - diff --git a/_docs/quick-start/gitops-quick-start/verify-requirements.md b/_docs/quick-start/gitops-quick-start/verify-requirements.md deleted file mode 100644 index 00db2593c..000000000 --- a/_docs/quick-start/gitops-quick-start/verify-requirements.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Prepare for Hybrid GitOps Runtime installation" -description: "" -group: getting-started -sub-group: quick-start -toc: true ---- - -Hybrid GitOps Runtimes are installed via Helm charts. - -If this is your first time installing GitOps in Codefresh, review and confirm that your deployment environment conforms to the minimum requirements for Hybrid GitOps installation. Check the [system requirements]({{site.baseurl}}/docs/installation/gitops/hybrid-gitops-helm-installation/#minimum-system-requirements). - - - -## What to do next -[Install a Hybrid GitOps Runtime]({{site.baseurl}}/docs/quick-start/gitops-quick-start/runtime/) diff --git a/docker-compose.yml b/docker-compose.yml index a468dd262..e8d576afe 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,4 +1,4 @@ -version: "2" + services: site: command: jekyll serve --incremental diff --git a/images/gitops-promotions/tutorials/dnd-action.png b/images/gitops-promotions/tutorials/dnd-action.png index 963f8144f..66ad705d1 100644 Binary files a/images/gitops-promotions/tutorials/dnd-action.png and b/images/gitops-promotions/tutorials/dnd-action.png differ diff --git a/images/gitops-promotions/tutorials/dnd-apps-in-prod.png b/images/gitops-promotions/tutorials/dnd-apps-in-prod.png index 7c5b455e3..ba3d05215 100644 Binary files a/images/gitops-promotions/tutorials/dnd-apps-in-prod.png and b/images/gitops-promotions/tutorials/dnd-apps-in-prod.png differ diff --git a/images/gitops-promotions/tutorials/dnd-commit.png b/images/gitops-promotions/tutorials/dnd-commit.png index b1044a663..f886f1a10 100644 Binary files a/images/gitops-promotions/tutorials/dnd-commit.png and b/images/gitops-promotions/tutorials/dnd-commit.png differ diff --git a/images/gitops-promotions/tutorials/dnd-prod-in-env.png b/images/gitops-promotions/tutorials/dnd-prod-in-env.png index 9d166d62a..c674126c1 100644 Binary files a/images/gitops-promotions/tutorials/dnd-prod-in-env.png and b/images/gitops-promotions/tutorials/dnd-prod-in-env.png differ diff --git a/images/gitops-promotions/tutorials/dnd-prod-versions.png b/images/gitops-promotions/tutorials/dnd-prod-versions.png index 62ba20559..66ad705d1 100644 Binary files a/images/gitops-promotions/tutorials/dnd-prod-versions.png and b/images/gitops-promotions/tutorials/dnd-prod-versions.png differ diff --git a/images/gitops-promotions/tutorials/dnd-releases-page.png b/images/gitops-promotions/tutorials/dnd-releases-page.png index 091183372..c0818286d 100644 Binary files a/images/gitops-promotions/tutorials/dnd-releases-page.png and b/images/gitops-promotions/tutorials/dnd-releases-page.png differ diff --git a/images/gitops-promotions/tutorials/seq-flow-release-with-workflows.png b/images/gitops-promotions/tutorials/seq-flow-release-with-workflows.png index dc5152a8b..8b3afa494 100644 Binary files a/images/gitops-promotions/tutorials/seq-flow-release-with-workflows.png and b/images/gitops-promotions/tutorials/seq-flow-release-with-workflows.png differ diff --git a/images/gitops-promotions/tutorials/seq-promo-flow-all-target-envs.png b/images/gitops-promotions/tutorials/seq-promo-flow-all-target-envs.png index 64e1b5f27..282cff40a 100644 Binary files a/images/gitops-promotions/tutorials/seq-promo-flow-all-target-envs.png and b/images/gitops-promotions/tutorials/seq-promo-flow-all-target-envs.png differ diff --git a/images/quick-start/apps/qs-create-app-apps-in-dashboard.png b/images/quick-start/apps/qs-create-app-apps-in-dashboard.png new file mode 100644 index 000000000..3cee3c973 Binary files /dev/null and b/images/quick-start/apps/qs-create-app-apps-in-dashboard.png differ diff --git a/images/quick-start/apps/qs-create-app-commit-changes.png b/images/quick-start/apps/qs-create-app-commit-changes.png new file mode 100644 index 000000000..b89494017 Binary files /dev/null and b/images/quick-start/apps/qs-create-app-commit-changes.png differ diff --git a/images/quick-start/apps/qs-create-app-configuration.png b/images/quick-start/apps/qs-create-app-configuration.png new file mode 100644 index 000000000..7ba2966e7 Binary files /dev/null and b/images/quick-start/apps/qs-create-app-configuration.png differ diff --git a/images/quick-start/apps/qs-create-app-definitions.png b/images/quick-start/apps/qs-create-app-definitions.png new file mode 100644 index 000000000..35139687e Binary files /dev/null and b/images/quick-start/apps/qs-create-app-definitions.png differ diff --git a/images/quick-start/apps/qs-create-app-success.png b/images/quick-start/apps/qs-create-app-success.png new file mode 100644 index 000000000..d4c81be1b Binary files /dev/null and b/images/quick-start/apps/qs-create-app-success.png differ diff --git a/images/quick-start/cdops-add-app-commit.png b/images/quick-start/cdops-add-app-commit.png deleted file mode 100644 index 2ddbeea4d..000000000 Binary files a/images/quick-start/cdops-add-app-commit.png and /dev/null differ diff --git a/images/quick-start/cdops-add-app-configuration.png b/images/quick-start/cdops-add-app-configuration.png deleted file mode 100644 index 9c61f2645..000000000 Binary files a/images/quick-start/cdops-add-app-configuration.png and /dev/null differ diff --git a/images/quick-start/cdops-add-app-dashboard.png b/images/quick-start/cdops-add-app-dashboard.png deleted file mode 100644 index c98d20a1c..000000000 Binary files a/images/quick-start/cdops-add-app-dashboard.png and /dev/null differ diff --git a/images/quick-start/cdops-add-app-settings.png b/images/quick-start/cdops-add-app-settings.png deleted file mode 100644 index b8a978f5d..000000000 Binary files a/images/quick-start/cdops-add-app-settings.png and /dev/null differ diff --git a/images/quick-start/env-with-assigned-apps.png b/images/quick-start/env-with-assigned-apps.png new file mode 100644 index 000000000..cc905dddb Binary files /dev/null and b/images/quick-start/env-with-assigned-apps.png differ diff --git a/images/quick-start/environments-products/env-with-assigned-apps.png b/images/quick-start/environments-products/env-with-assigned-apps.png new file mode 100644 index 000000000..76009ceb0 Binary files /dev/null and b/images/quick-start/environments-products/env-with-assigned-apps.png differ diff --git a/images/quick-start/environments-products/env-with-unassigned-apps.png b/images/quick-start/environments-products/env-with-unassigned-apps.png new file mode 100644 index 000000000..187c7634e Binary files /dev/null and b/images/quick-start/environments-products/env-with-unassigned-apps.png differ diff --git a/images/quick-start/environments-products/environment-add.png b/images/quick-start/environments-products/environment-add.png index 5bec68e75..cc26fda86 100644 Binary files a/images/quick-start/environments-products/environment-add.png and b/images/quick-start/environments-products/environment-add.png differ diff --git a/images/quick-start/environments-products/environments-example.png b/images/quick-start/environments-products/environments-example.png new file mode 100644 index 000000000..6cf6686af Binary files /dev/null and b/images/quick-start/environments-products/environments-example.png differ diff --git a/images/quick-start/environments-products/envs-no-apps.png b/images/quick-start/environments-products/envs-no-apps.png new file mode 100644 index 000000000..933af3b3d Binary files /dev/null and b/images/quick-start/environments-products/envs-no-apps.png differ diff --git a/images/quick-start/environments-products/product-dashboard-view.png b/images/quick-start/environments-products/product-dashboard-view.png new file mode 100644 index 000000000..b323dab0b Binary files /dev/null and b/images/quick-start/environments-products/product-dashboard-view.png differ diff --git a/images/quick-start/environments-products/products-add-annotation-manifest.png b/images/quick-start/environments-products/products-add-annotation-manifest.png index 134f3c906..5d12be4c5 100644 Binary files a/images/quick-start/environments-products/products-add-annotation-manifest.png and b/images/quick-start/environments-products/products-add-annotation-manifest.png differ diff --git a/images/quick-start/environments-products/products-copy-annotation.png b/images/quick-start/environments-products/products-copy-annotation.png index 6399e0213..c053a5cee 100644 Binary files a/images/quick-start/environments-products/products-copy-annotation.png and b/images/quick-start/environments-products/products-copy-annotation.png differ diff --git a/images/quick-start/environments-products/products-dashboard-apps.png b/images/quick-start/environments-products/products-dashboard-apps.png index a4427845a..f134c0a77 100644 Binary files a/images/quick-start/environments-products/products-dashboard-apps.png and b/images/quick-start/environments-products/products-dashboard-apps.png differ diff --git a/images/quick-start/environments-products/products-manually-assign-apps.png b/images/quick-start/environments-products/products-manually-assign-apps.png index 1f7cb45fc..5aa8e6710 100644 Binary files a/images/quick-start/environments-products/products-manually-assign-apps.png and b/images/quick-start/environments-products/products-manually-assign-apps.png differ diff --git a/images/quick-start/environments-products/products-no-apps-assigned.png b/images/quick-start/environments-products/products-no-apps-assigned.png index d22d0bbe0..423686f01 100644 Binary files a/images/quick-start/environments-products/products-no-apps-assigned.png and b/images/quick-start/environments-products/products-no-apps-assigned.png differ diff --git a/images/quick-start/environments-products/products-unassigned-apps.png b/images/quick-start/environments-products/products-unassigned-apps.png index 9a3001dc4..7112825c6 100644 Binary files a/images/quick-start/environments-products/products-unassigned-apps.png and b/images/quick-start/environments-products/products-unassigned-apps.png differ diff --git a/images/quick-start/envs-no-apps.png b/images/quick-start/envs-no-apps.png new file mode 100644 index 000000000..933af3b3d Binary files /dev/null and b/images/quick-start/envs-no-apps.png differ diff --git a/images/quick-start/gitops/apps-new-app-in-dashboard.png b/images/quick-start/gitops/apps-new-app-in-dashboard.png new file mode 100644 index 000000000..238e61867 Binary files /dev/null and b/images/quick-start/gitops/apps-new-app-in-dashboard.png differ diff --git a/images/quick-start/gitops/cdops-add-app-commit.png b/images/quick-start/gitops/cdops-add-app-commit.png new file mode 100644 index 000000000..dc4320619 Binary files /dev/null and b/images/quick-start/gitops/cdops-add-app-commit.png differ diff --git a/images/quick-start/gitops/cdops-add-app-dashboard.png b/images/quick-start/gitops/cdops-add-app-dashboard.png new file mode 100644 index 000000000..2fe31397a Binary files /dev/null and b/images/quick-start/gitops/cdops-add-app-dashboard.png differ diff --git a/images/quick-start/gitops/cdops-add-app-settings.png b/images/quick-start/gitops/cdops-add-app-settings.png new file mode 100644 index 000000000..b3fcbd08f Binary files /dev/null and b/images/quick-start/gitops/cdops-add-app-settings.png differ diff --git a/images/quick-start/promotions/qucik-start-dnd-apps-in-prod.png b/images/quick-start/promotions/qucik-start-dnd-apps-in-prod.png new file mode 100644 index 000000000..ba3d05215 Binary files /dev/null and b/images/quick-start/promotions/qucik-start-dnd-apps-in-prod.png differ diff --git a/images/quick-start/promotions/quick-start-dependency-flow-release-view.png b/images/quick-start/promotions/quick-start-dependency-flow-release-view.png new file mode 100644 index 000000000..c235ab66d Binary files /dev/null and b/images/quick-start/promotions/quick-start-dependency-flow-release-view.png differ diff --git a/images/quick-start/promotions/quick-start-dependency-flow-yaml.png b/images/quick-start/promotions/quick-start-dependency-flow-yaml.png new file mode 100644 index 000000000..b12341d74 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dependency-flow-yaml.png differ diff --git a/images/quick-start/promotions/quick-start-dependency-flow.png b/images/quick-start/promotions/quick-start-dependency-flow.png new file mode 100644 index 000000000..4610e5e20 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dependency-flow.png differ diff --git a/images/quick-start/promotions/quick-start-dependency-update.png b/images/quick-start/promotions/quick-start-dependency-update.png new file mode 100644 index 000000000..29e97e214 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dependency-update.png differ diff --git a/images/quick-start/promotions/quick-start-dnd-action.png b/images/quick-start/promotions/quick-start-dnd-action.png new file mode 100644 index 000000000..66ad705d1 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dnd-action.png differ diff --git a/images/quick-start/promotions/quick-start-dnd-ongoing-release.png b/images/quick-start/promotions/quick-start-dnd-ongoing-release.png new file mode 100644 index 000000000..a2c889f62 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dnd-ongoing-release.png differ diff --git a/images/quick-start/promotions/quick-start-dnd-prod-in-env.png b/images/quick-start/promotions/quick-start-dnd-prod-in-env.png new file mode 100644 index 000000000..c674126c1 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dnd-prod-in-env.png differ diff --git a/images/quick-start/promotions/quick-start-dnd-prod-versions.png b/images/quick-start/promotions/quick-start-dnd-prod-versions.png new file mode 100644 index 000000000..66ad705d1 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dnd-prod-versions.png differ diff --git a/images/quick-start/promotions/quick-start-dnd-releases-page.png b/images/quick-start/promotions/quick-start-dnd-releases-page.png new file mode 100644 index 000000000..bc2f631e1 Binary files /dev/null and b/images/quick-start/promotions/quick-start-dnd-releases-page.png differ diff --git a/images/quick-start/promotions/quick-start-parallel-add-envs.png b/images/quick-start/promotions/quick-start-parallel-add-envs.png new file mode 100644 index 000000000..961c622f8 Binary files /dev/null and b/images/quick-start/promotions/quick-start-parallel-add-envs.png differ diff --git a/images/quick-start/promotions/quick-start-parallel-chart-view.png b/images/quick-start/promotions/quick-start-parallel-chart-view.png new file mode 100644 index 000000000..20c23df85 Binary files /dev/null and b/images/quick-start/promotions/quick-start-parallel-chart-view.png differ diff --git a/images/quick-start/promotions/quick-start-parallel-dashboard-view.png b/images/quick-start/promotions/quick-start-parallel-dashboard-view.png new file mode 100644 index 000000000..1a058ed7a Binary files /dev/null and b/images/quick-start/promotions/quick-start-parallel-dashboard-view.png differ diff --git a/images/quick-start/promotions/quick-start-parallel-envs-view.png b/images/quick-start/promotions/quick-start-parallel-envs-view.png new file mode 100644 index 000000000..40fb1fbe9 Binary files /dev/null and b/images/quick-start/promotions/quick-start-parallel-envs-view.png differ diff --git a/images/quick-start/promotions/quick-start-parallel-envs-yaml-view.png b/images/quick-start/promotions/quick-start-parallel-envs-yaml-view.png new file mode 100644 index 000000000..df7dac02c Binary files /dev/null and b/images/quick-start/promotions/quick-start-parallel-envs-yaml-view.png differ diff --git a/images/quick-start/promotions/quick-start-parallel-release-view.png b/images/quick-start/promotions/quick-start-parallel-release-view.png new file mode 100644 index 000000000..05ec0b16b Binary files /dev/null and b/images/quick-start/promotions/quick-start-parallel-release-view.png differ diff --git a/images/quick-start/promotions/quick-start-promo-flow-dependency.png b/images/quick-start/promotions/quick-start-promo-flow-dependency.png new file mode 100644 index 000000000..eb7a9ef61 Binary files /dev/null and b/images/quick-start/promotions/quick-start-promo-flow-dependency.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-all-envs.png b/images/quick-start/promotions/quick-start-seq-promo-all-envs.png new file mode 100644 index 000000000..b0e142fd0 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-all-envs.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-flow-list.png b/images/quick-start/promotions/quick-start-seq-promo-flow-list.png new file mode 100644 index 000000000..7b2933ee5 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-flow-list.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-policy-populated.png b/images/quick-start/promotions/quick-start-seq-promo-policy-populated.png new file mode 100644 index 000000000..8f0c6185f Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-policy-populated.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-policy-release-view.png b/images/quick-start/promotions/quick-start-seq-promo-policy-release-view.png new file mode 100644 index 000000000..36731f3ff Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-policy-release-view.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-policy-release.png b/images/quick-start/promotions/quick-start-seq-promo-policy-release.png new file mode 100644 index 000000000..62882713a Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-policy-release.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-policy-settings.png b/images/quick-start/promotions/quick-start-seq-promo-policy-settings.png new file mode 100644 index 000000000..3b2a8fe82 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-policy-settings.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-policy-yaml.png b/images/quick-start/promotions/quick-start-seq-promo-policy-yaml.png new file mode 100644 index 000000000..654b49823 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-policy-yaml.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-release-list.png b/images/quick-start/promotions/quick-start-seq-promo-release-list.png new file mode 100644 index 000000000..fc5ea20c9 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-release-list.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-release-view.png b/images/quick-start/promotions/quick-start-seq-promo-release-view.png new file mode 100644 index 000000000..4fcd53c42 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-release-view.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-save-flow.png b/images/quick-start/promotions/quick-start-seq-promo-save-flow.png new file mode 100644 index 000000000..9997b8f5b Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-save-flow.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-settings.png b/images/quick-start/promotions/quick-start-seq-promo-settings.png new file mode 100644 index 000000000..1900a7345 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-settings.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-target-env.png b/images/quick-start/promotions/quick-start-seq-promo-target-env.png new file mode 100644 index 000000000..aa1fe1cfd Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-target-env.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-trigger-env.png b/images/quick-start/promotions/quick-start-seq-promo-trigger-env.png new file mode 100644 index 000000000..80a985302 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-trigger-env.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-trigger-select-product.png b/images/quick-start/promotions/quick-start-seq-promo-trigger-select-product.png new file mode 100644 index 000000000..96a5b6921 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-trigger-select-product.png differ diff --git a/images/quick-start/promotions/quick-start-seq-promo-trigger.png b/images/quick-start/promotions/quick-start-seq-promo-trigger.png new file mode 100644 index 000000000..5457ab3c5 Binary files /dev/null and b/images/quick-start/promotions/quick-start-seq-promo-trigger.png differ diff --git a/images/quick-start/runtimes/qs-runtime-create-gitsource.png b/images/quick-start/runtimes/qs-runtime-create-gitsource.png new file mode 100644 index 000000000..7500221a0 Binary files /dev/null and b/images/quick-start/runtimes/qs-runtime-create-gitsource.png differ diff --git a/images/quick-start/runtimes/qs-runtime-git-source-app.png b/images/quick-start/runtimes/qs-runtime-git-source-app.png new file mode 100644 index 000000000..ce983453e Binary files /dev/null and b/images/quick-start/runtimes/qs-runtime-git-source-app.png differ diff --git a/images/quick-start/runtimes/qs-runtime-gitsource-repo.png b/images/quick-start/runtimes/qs-runtime-gitsource-repo.png new file mode 100644 index 000000000..0d2bb4211 Binary files /dev/null and b/images/quick-start/runtimes/qs-runtime-gitsource-repo.png differ