# Model and deploy microservice applications Model and deploy microservice applications ========================================== With CloudBees CD/RO, you can model a microservice application and its deployment environment using a pre-provisioned Kubernetes cluster definition. Deploy microservice applications using Helm or YAML. A CloudBees CD/RO microservice application consists of the microservices and processes that orchestrate deployment to pre-provisioned Kubernetes clusters. Microservice applications consists of one or more microservices, where each microservice is a logical group of containers. All microservices within an application are mapped to one or more clusters in the environment. To create a microservice application that deploys to a mapped Kubernetes cluster environment using Helm: 1. Ensure all [Prerequisites](#prerequisites) are met. 2. Review [Argo Rollouts deployment and delivery](#argo-rollouts-deployment-delivery) specific considerations, if applicable. 3. [Create a new application or copy an existing application](#create-application). 4. Define the microservice for [Helm](#define-helm-microservice-details) or [YAML](#define-yaml-microservice-details). 5. [Configuring a microservice process](#configure-microservice-process). 6. [Define the environment](#define-environment), [configure a cluster reference](#configure-cluster-reference) based upon pre-provisioned Kubernetes cluster. 7. [Map the microservice](#map-microservice-to-environment) to the cluster in the environment. [](#prerequisites)Prerequisites ------------------------------- These instructions assume you understand the tooling required for provisioning a Kubernetes cluster, are familiar with [Kubernetes concepts](https://kubernetes.io/), and have provisioned your Kubernetes cluster or clusters onto which the microservice application is deployed. Additionally, the following prerequisites must be met: * Kubernetes requirements: * The Kubernetes clusters used for deployment must be v1.16 or higher. * To use Argo Rollouts, you must install the [Argo controller](https://argoproj.github.io/argo-rollouts/installation/#controller-installation) in your cluster. * CloudBees CD/RO plugins requirements: * For YAML, the EC-Kubectl plugin v1.4.0 or higher is required. * For Helm, the EC-Helm plugin is required. * CloudBees CD/RO agent requirements: * CloudBees CD/RO agent images v2023.03.0 and higher: * For CloudBees CD/RO v2023.03.0 or later `cbflow-agent` images, the tools to use this feature come preinstalled. For current tool version information, refer to [CloudBees CD/RO agents third-party tools](/docs/cloudbees-cd/latest/install-k8s/installation#agent-third-party-tools). * For CloudBees CD/RO agent images v2023.02.0 and earlier, you must install the following tools: * For Helm-based deployments, you must install the [Helm CLI](https://helm.sh/docs/intro/install/). * For YAML-based deployments, you must install [kubectl](https://kubernetes.io/docs/tasks/tools/). * To use Argo Rollouts, you must install the [kubectl-argo-rollout plugin](https://argoproj.github.io/argo-rollouts/installation/#kubectl-plugin-installation) in your agent. Additional knowledge-based prerequisites: * For YAML-based deployments, refer to [YAML-based deployment file naming](#yaml-based-deployment-file-naming). * For Helm-based deployments, refer to [Helm-based deployment flags and options](#helm-based-flags-and-options). ### [](#yaml-based-deployment-file-naming)YAML-based deployment file naming When using YAML-based deployments, CloudBees CD/RO uses `kubectl` to process jobs. When `kubectl` parses over directories, YAML files in the directory are applied in the order they appear in the directory, which is typically alphabetically. This is a known issue that may cause temporary degraded deployment statuses if kubectl processes a file before its dependency. When deploying directories, this behavior can occur in both Git-based deployments and local workspace deployments. Once Argo Rollouts detects the degraded status, it tries to self-repair and pass the files again, which typically resolves the issue within about 20 seconds. CloudBees CD/RO reports the degraded status and automatically updates it after the issue is corrected. To avoid this issue, prefix your file names with a number sequence, so they are read in the correct order. For instance, if you have a `my-deployment` directory with the following structure: |-- my-deployment | |-- rollouts.yaml ## Depends on services.yaml, which is not deployed until after. | |-- services.yaml To read the dependency first, you could rename the files as follows: |-- my-deployment | |-- 01_services.yaml | |-- 02_rollouts.yaml ## Depends on services.yaml, which is already deployed. ### [](#helm-based-flags-and-options)Helm-based deployment flags and options Helm-based microservice deployments use the `helm upgrade --install` command to support both fresh and upgrade deployments. To pass flags and options as deployment parameters to `helm upgrade --install`, use the **Additional options** field when creating your application. Parameters are appended to the command in the following order: When configuring an option in multiple parameters, the value of the last occurrence is used. 1. Values file definitions configured with the **Values** parameter. 2. Microservice definition configuration **Repository name**, **Repository credentials**, **Release name**, and **Chart**. 3. Microservice definition **Additional options**. 4. Cluster definition **Namespace** parameter. 5. Cluster definition **Kubeconfig Context** parameter. 6. If automatic rollback is configured, the `--atomic` option is also added. The system parses release manifests for containers and other Kubernetes resources deployed with your application, which are listed in the environment inventory. Different YAML libraries implement different YAML specifications. As a result, the system may not parse some manifests that Kubernetes accepts, causing their containers or Kubernetes resources to not appear in the environment inventory. If you receive warnings about a specific YAML file that has containers, and the chart is under your governance, ensure the chart template is correctly formatted and linted. For charts provided by third-parties, file an issue with that provider. ### [](#use-argo-rollouts-inline-analysis)Use Argo Rollouts inline analysis Microservice deployments support using Argo Rollouts inline analysis results. These results are provided by approved Argo Rollouts metric providers, and can be used for YAML and Helm-based deployments. CloudBees CD/RO only reads the analysis results by Argo Rollouts metric providers. For more information on configuring Argo Rollouts inline analysis or approved Argo Rollouts metric providers, refer to the [Argo Rollouts documentation](https://argo-rollouts.readthedocs.io/en/stable/features/analysis/#analysis-progressive-delivery). To use this feature: 1. Configure inline analysis conditions in your YAML or Helm-based deployments prior to running the microservice deployment pipeline in CloudBees CD/RO. For **Helm-based deployments**, escape Argo Rollouts templates in Helm charts to avoid conflicts between Argo Rollouts and Helm templates. For more information, refer to the [Argo Rollouts documentation](https://argo-rollouts.readthedocs.io/en/stable/features/analysis/#analysis-progressive-delivery). 2. You must have the minimum plugin version installed for your deployment configuration: * For Helm-based deployments, EC-Helm v1.8.0 or later is required. * For YAML-based deployments, EC-Kubectl v1.5.0 or later is required. When using Argo Rollouts inline analysis, there are three basic types of results: * Passed: The deployment meets the criteria described in the deployment chart. * Failed: The deployment fails to meet the criteria described in the deployment chart. * Inconclusive: It cannot be determined if the deployment meets or fails to meet the criteria described in the deployment chart. Based on these results, the CloudBees CD/RO gate logics are: * For passing metric results, CloudBees CD/RO proceeds with the deployment. * For failing metric results, CloudBees CD/RO stops and rolls back the deployment. * For inconclusive metric results: 1. The microservice deployment is paused. 2. A manual approval step is automatically created and applied to the current pipeline step. This manual approval is created in addition to any other manual approval steps in your pipeline. Once created, this manual approval pauses the pipeline until it is approved or rejected. Even if you approve or reject the deployment via `kubectl` commands, the pipeline remains paused until this step is approved or rejected. 3. Based on the configured notifications for **Assignees**, The system sends notifications. 4. A member of the **Assignee** group approves or rejects the deployment via the manual approval step. 5. CloudBees CD/RO processes the deployment based on the gate logic. For more information on Argo Rollouts inline analysis results, refer to the [Argo Rollouts documentation](https://argo-rollouts.readthedocs.io/en/stable/features/analysis/#analysis-progressive-delivery). [](#argo-rollouts-deployment-delivery)Argo Rollouts deployment and delivery --------------------------------------------------------------------------- Argo Rollouts Advanced Deployment [Watch video](https://cloudbees.wistia.com/medias/v3rvzt4cfg) Argo Rollouts is a Kubernetes controller and set of custom resource definitions (CRDs) that provide advanced deployment capabilities for Kubernetes environments, such as: * Blue-green * Canary * Canary analysis * Experimentation * Progressive delivery [](#oci-registry-for-helm-based-microservices-deployments)OCI Registry for Helm-based microservice deployments -------------------------------------------------------------------------------------------------------------- CloudBees CD/RO supports OCI Registry for Helm-based microservice deployments. This pulls Helm charts hosted in OCI-compliant registries and deploys them using the EC-Helm plugin. OCI registry provides reliable and scalable Helm operations, particularly in environments where non-OCI approaches may become inefficient or unstable. OCI supports the following artifact registries for Helm charts: * Amazon ECR * JFrog Artifactory * Docker Hub * Google Artifact Registry [](#create-application)Create a new application or copy an existing application ------------------------------------------------------------------------------- 1. From the CloudBees CD/RO main menu, select **Deployment Automation**  **Applications**. The **Applications** list displays. 2. Select **New application**. The **New Application** dialog displays. 3. Choose an option. * Add new application. 1. Select **Create new**. 2. Complete the following field. Label Definition Application name User-defined name for the application. Project User-defined name of the project containing the application. Description (Optional) User-defined information about this application. Not used by the system. Application type The application type. Select **Microservice**. Tags Tags allow you to group related objects by a user-defined term. To tag this object or to modify or delete a tag, select the **Open Dialog** arrow. For more information, refer to [Object Tags](/docs/cloudbees-cd/latest/objects/object-tagging). * Copy an existing application. 1. Select **Copy existing**. 2. Select the name of the application to copy. 3. Complete the following fields. Label Definition Project User-defined name of the project containing the application. Description (Optional) User-defined information about this application. Not used by the system. Tags Tags allow you to group related objects by a user-defined term. To tag this object or to modify or delete a tag, select the Open Dialog arrow at right. For more information, refer to [Object Tags](/docs/cloudbees-cd/latest/objects/object-tagging). 4. Select **OK**. The application editor displays. ![Application editor example](../_images/microservice-application-editor.3266c49.png) Figure 1. Application editor 5. Continue modifying the microservices application by either: * [Define microservice details for Helm](#define-helm-microservice-details) * [Define microservice details for YAML](#define-yaml-microservice-details) [](#define-helm-microservice-details)Define microservice details for Helm ------------------------------------------------------------------------- When you create a new application, the new application is pre-populated with one microservice tile. 1. In the microservice tile of the **Application editor**, select **Add microservice**. The **Add microservice** dialog displays. 2. Choose an option. * Add a new microservice. 1. Select **Create new**. 2. Complete the following fields. Label Definition Name User-defined name for the microservice. Description User-defined description for the microservice. * Copy an existing microservice. 1. Select **Copy existing**. 2. Complete the following fields. Label Definition Project User-defined name of the project containing the application. Application name User-defined name for the application. Microservice User-defined name for the microservice. 3. Select **Next** 3. Select `Helm` from the **Definition type** choices. 4. Choose a microservice repository source from the **Definition source** options. * Clone and deploy a Git repository: 1. Select `Git repository` from the **Definition source** menu. 2. Complete the following fields. Label Definition Configuration Name User-defined name for the Git configuration. Git Repository User-defined name of the Git repository. Remote branch User-defined name of the remote Git branch. * Configure a Helm repository. 1. Select `HELM repository` from the **Definition source** menu. 2. Complete the following fields. Label Definition Repository URL The URL of the Helm chart repository. **Example:** `example:https://jfrog.demo.cbc.beescloud.com` `oci://jfrog.demo.cbc.beescloud.com` Some custom host or repository configurations for Helm charts may be supported by Kubernetes. CloudBees CD/RO supports most options listed the [Helm Chart Repository Guide](https://helm.sh/docs/topics/chart_repository/). The following Kubernetes configurations with CloudBees CD/RO have been tested using Helm charts from the following host types: * Helm-based repositories. * Git-based repositories. * Nexus-based repositories. IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: `[]`. Repository name User-defined name of the Helm chart repository. Repository credentials Credentials needed for repository connection. Select **Browse** to locate previously created credentials. For details, refer to [Credential management](/docs/cloudbees-cd/latest/credentials/credential-management). For private repositories, store the credential as a **Project Credential** or **Plugin Credential**. Additional options Additional flag options for `helm repo add` and `helm repo update` commands. Enter the flag options in a semicolon-separated format. The options that are added before the semicolon apply to `helm repo add` command, and options added after the semicolon apply to `helm repo update` command. Update specific repository Select this option to update a specific list of repositories instead of all configured repositories. Repositories to update Specify the repository names to update. Add only one repository name per line. 5. Enter additional microservice details. Label Definition Release name User-defined name of the deployment release. Chart User-defined name of the deployment Helm chart. Chart version User-defined deployment Helm chart version. The version is appended to the command line options supplied to the `helm upgrade` command. If the version specified in **Chart version** differs from the **Additional options** `--version` value, then the **Additional options** parameter `--version` value is removed. Additional options Additional options to be provided to the Helm CLI. Values A list of values. Values in this file have lower priority than **Additional options**. The list supplied here is saved to a file and passed to the command with the `-f ` option. Enable automatic rollback on failure? Select this option to automatically roll back deployments upon failure. When selected, a system-generated rollback microservice process step is created in the microservice process, and the `--atomic` Helm option is added to the deployment command. Timeout Available when rollback is enabled. This is the number of seconds to trigger a rollback timeout. 6. Select **Add microservice**. 7. Continue modifying the microservices application by configuring the [microservice processes](#configure-microservice-process), [environment](#define-environment), [cluster reference,](#configure-cluster-reference) and [mapping](#map-microservice-to-environment) settings. [](#define-yaml-microservice-details)Define microservice details for YAML ------------------------------------------------------------------------- When you create a new application, the new application is pre-populated with one microservice tile and one environment tile. 1. In the microservice tile of the **Application editor**, select **Add microservice**. The **Add microservice** dialog displays. 2. Choose an option. * Add a new microservice. 1. Select **Create new**. 2. Complete the following. Label Definition Name User-defined name for the microservice. Description User-defined description for the microservice. * Copy an existing microservice. 1. Select **Copy existing**. 2. Complete the following. Label Definition Project User-defined name of project containing the application. Application User-defined name for the application. Microservice User-defined name for the microservice. 3. Select **Next** 3. Select `YAML` from the **Definition type** choices. 4. Choose a microservice repository source from the **Definition source** options. When using YAML-based deployments, ensure you read and understand [YAML-based deployment file naming](#yaml-based-deployment-file-naming). * To clone and deploy YAML files from Git repositories: 1. Select `Git repository` from the **Definition source** menu. 2. Complete the following fields. Label Definition Configuration Name User-defined name for the Git configuration. Git Repository User-defined name for the Git repository. `kubectl` **does not** deploy YAML files recursively. If you want to deploy specific YAML files, add the relative path to those files in **Relative path**. Remote branch User-defined name of the Git remote branch. Relative path The relative path to the Git configuration. `kubectl` **does not** deploy YAML files recursively. Additional options (Optional) Enter additional options to include with the `kubectl apply` command. You cannot enter the `namespace`, `context`, `cluster`, or `user` as additional options. Instead, you can add these configurations to your plugin configuration or cluster definition. * To add YAML manual input, a single YAML file, or directory that contains your YAML files: 1. Select `YAML content` from the **Definition source** menu. 2. Complete the following fields. Label Definition Source Type The source of the YAML content. * Select **Content** to enter the YAML formatted content directly into the **YAML Content** field. * Select **YAML Content**. Select **Path** to enter the path to an existing YAML file in the **Relative path** field. `kubectl` **does not** deploy YAML files recursively. If you want to deploy specific YAML files, add the relative path to those files in **Relative path**. YAML Content The user-defined name of the YAML content source. 5. Enter additional microservice details. Label Definition Relative path The relative path to the YAML content source. `kubectl` **does not** deploy YAML files recursively. Additional options (Optional) Enter additional options to include with the `kubectl apply` command. You cannot enter the `namespace`, `context`, `cluster`, or `user` as additional options. Instead, you can add these configurations to your plugin configuration or cluster definition. 6. Select **Add microservice**. 7. Continue modifying the microservices application by configuring the [microservice processes](#configure-microservice-process), [environment](#define-environment), [cluster reference,](#configure-cluster-reference) and [mapping](#map-microservice-to-environment) settings. [](#configure-microservice-process)Configuring a microservice process --------------------------------------------------------------------- CloudBees CD/RO creates two process steps by default: * Retrieve Artifact * Deploy Microservice EC-Helm supports automatic rollback. When you create a microservice for Helm, CloudBees CD/RO creates a third process step, Rollback Microservice, by default. To configure a microservice process: 1. In the Application tile of the **Application editor**, select **Microservice process** from the microservice ![Three-dots](../_images/icons/3-dot-blk-icon.60801b8.png) menu. The list of microservices for the microservice process displays. 2. Select **Edit** from the microservice ![Three-dots](../_images/icons/3-dot-blk-icon.60801b8.png) menu. The **Edit application processes** page display. 3. Configure the application process by defining the following: Label Definition Process name User-defined name of the microservice process. Description User-defined description of the microservice. Process task type The task type of the microservice. Select `Deploy`, `Undeploy` or `Other`. Workspace Name of the microservice workspace. Working directory Working directory where the microservice process will run. Exclusive access True if environment is exclusive to the application or service process. Time limit Units for step time limit: seconds, minutes, or hours. Credentials The name of a credential to attach to this process. Default rollout options Set the default approver and enable or disable email notification when rollout deployment is configured with manual approval. If no approvers are specified then the user who launched the deployment is assigned as the approver. These values can be overwritten later during the process run, in the pipeline task or in the release deployer configuration. 4. Select **OK**. 5. Continue modifying the microservices application by configuring the [environment](#define-environment), [cluster reference,](#configure-cluster-reference) and [mapping](#map-microservice-to-environment) settings. [](#define-environment)Define the environment --------------------------------------------- Now you define the cluster environment into which the microservice is deployed. This cluster must have already been provisioned outside of CloudBees CD/RO. To add an environment: 1. In the environment tile of the **Application editor**, select **+**. The **New environment** dialog opens. 2. Select either **Create new** or **Use existing**. If you are creating a new environment, the **New environment** dialog opens. 3. Enter details about this environment. Label Definition Environment name User-defined name of the environment object containing the cluster. Project name The user-defined name of the project containing the environment. Environment description (Optional) User-defined information about this environment. Not used by the system. Utility resource name User-defined name of the resource used to deploy the microservice. This must be a CloudBees CD/RO agent, v10.1 or higher, with the following binaries installed: * Helm v3.4.1 or higher. * Kubectl v1.16 or higher. Resource Select the resource or resource pool. 4. Add additional utility resources to the environment if required. 1. Select **Add another utility resource**. 2. Enter the **Utility resource name** and select the **Resource**. 5. Select **Add environment**. The new **Utility Resource** tile opens in the editor field. 6. Continue modifying the microservices application by configuring the [cluster reference,](#configure-cluster-reference) and [environment mapping](#map-microservice-to-environment). [](#configure-cluster-reference)Configure a cluster reference ------------------------------------------------------------- After you create an environment, you can add a cluster reference. 1. In the environment tile of the **Application editor**, select **Add cluster reference**. The **Add cluster reference** dialog opens. 2. Enter details about this cluster reference. Label Definition Cluster reference name User-defined name of the cluster. Cluster reference description (Optional) User-defined information about this environment. Not used by the system. Configuration provider Select a configuration provider. * For Helm deployment: Select **Kubernetes via Helm (Supports microservice model)**. * For YAML deployment: Select **Kubernetes via Kubectl (Supports microservice model)**. Configuration Name A cluster configuration is CloudBees CD/RO object that holds common values, predefined parameter sets, and credentials for your cluster. A cluster configuration leverages the CloudBees CD/RO EC-Helm plugin for Helm deployments or the EC-Kubectl plugin for YAML deployments. * Select **New configuration** to define a new configuration. For more information, refer to [Helm plugin](/docs/cloudbees-cd-plugin-docs/latest/ec-helm/) or [Kubectl plugin](/docs/cloudbees-cd-plugin-docs/latest/ec-kubectl/). * Select the **name** of a previously defined configuration for the cluster. Namespace User-defined name of the Kubernetes namespace. If not supplied, the default namespace is used. Kubeconfig context User-defined name of the context to be used for this cluster deployment. If not specified, the one defined by the `current-context` inside the `kubeconfig` file is used. 3. Select **Add cluster reference**. 4. Continue modifying the microservices application by configuring the [environment mapping](#map-microservice-to-environment). [](#map-microservice-to-environment)Map the microservice to an environment -------------------------------------------------------------------------- For CloudBees CD/RO to correctly deploy the microservice, the microservice needs to be mapped to the environment that defines the cluster. Configure microservice environment mapping. 1. Select **Add mapping** or **Edit mapping** in the **Application editor**. The **Mapping** dialog opens. 2. Select the **Cluster reference**. 3. Select **Save mapping**. [](#deploy-application)Deploying the application ------------------------------------------------ Once the application is created and configured, you can deploy it. For more information about deploying applications, refer to [Example: Deploy and troubleshoot applications](/docs/cloudbees-cd/latest/applications-environments/example-deploy-applications).