Configuring the CloudBees Analytics server

Modeling and deploying microservice applications

9 minute readReferenceAutomation

This section describes modeling a CloudBees CD/RO microservice application and its deployment environment using a pre-provisioned Kubernetes cluster definition. Helm and YAML are the supported deployment options for microservice applications.

A CloudBees CD/RO microservice application consists of the microservices and processes that orchestrate the deployment of the microservices 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 a microservice application are mapped to at least one cluster within an environment.

To create a microservice application that deploys to a mapped Kubernetes cluster environment via Helm:

  1. Ensure all prerequisites are met.

  2. Review ARGO rollout specific considerations, if applicable.

  3. Create a new or copy an existing application.

  4. Define the microservice for Helm or YAML.

  5. Configure a microservice processes.

  6. Define the environment, configure a cluster reference based upon pre-provisioned Kubernetes cluster.

  7. Map the microservice to the cluster in the environment.

Prerequisites

These instructions assume you understand the tooling required for provisioning a Kubernetes cluster, are familiar with Kubernetes concepts, and have provisioned your Kubernetes cluster or clusters onto which the microservice application is deployed. Also, the following must be true:

  • The Kubernetes clusters used for deployment must be v1.16 or higher.

  • For YAML, the EC-Kubectl plugin v1.3.0 or higher is required.

  • For Helm, the EC-Helm plugin is required.

ARGO rollout deployment and delivery

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

If you are using CloudBees CD/RO 2023.02.0 or earlier, additional prerequisites are required to use Argo rollouts. You must install the Argo controller and Kubectl plugin.

As of CloudBees CD/RO release 2023.03.0, CloudBees CD/RO cbflow-agent images include kubectl v1.16.1 and the kubectl-argo-rollout plugin v1.4.0 preinstalled. For information, refer to Install and update CloudBees CD/RO agents.

Creating a new or copying 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 let you 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. Refer to Object Tags for more information.

    • Copy an existing application.

      1. Select Copy existing.

      2. Select the name of the application to be copied.

      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. Refer to Object Tags for more information.

  4. Select OK. The application editor displays.

    Application editor example
    Figure 1. Application editor
  5. Continue modifying the microservices application by defining the Helm or YAML microservice. Then, configuring the microservice processes, environment, cluster reference, and mapping settings.

Defining 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.

        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. 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.

        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.

  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 <fileName> 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, environment, cluster reference, and mapping settings.

Defining 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.

    • 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 for the Git repository.

        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.

        Additional options

        Additional options to be provided to the Helm CLI.

    • Configure a YAML repository.

      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.

        YAML Content

        The user-defined name of the YAML content source.

  5. Enter additional microservice details.

    Label Definition

    Relative path

    The relatiuve path to the YAML content source.

    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, environment, cluster reference, and mapping settings.

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 menu. The list of microservices for the microservice process displays.

  2. Select Edit from the microservice three-dots 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

    Used to set the default assigned approvers and turn on/off email notifications when rollout deployment is configured with manual approval. If approvers are not specified then the user who launched the deploy process will be assigned as the approver. These default values can be overwritten later upon process run, in pipeline task or release deployer configuration.

  4. Select OK.

  5. Continue modifying the microservices application by configuring the environment, cluster reference, and mapping settings.

Defining 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, and environment mapping.

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 or Kubectl plugin.

    • 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.

Mapping 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.

Deploying the application

Once the application is created and configured, you can deploy it. Refer to Deploying and troubleshooting applications for information about deploying applications.

Additional considerations for Helm deployments

Microservice deployment uses the upgrade --install Helm command to support both fresh and upgrade deployments. Deployment parameters defined in the Additional options field at application create time is used to provide list of flags and options for the deployment command.

If automatic rollback is configured, the --atomic option is added to the deployment command.

Parameters are appended to the command in the following order, which means options that are appended later can override values set by previous options.

  • File containing list of values supplied with Values parameter.

  • Microservice definition configuration Repository name, Repository credentials, Release name, and Chart.

  • Microservice definition Additional options.

  • Cluster definition Namespace parameter.

  • Cluster definition Kubeconfig Context parameter.

Release manifests are parsed in order to get list of containers and other Kubernetes resources that are deployed with this application. These containers and Kubernetes resources are reported to the environment inventory.

Because different YAML libraries have different implementation of the YAML specification, some manifests accepted by Kubernetes may not be parsed. If you have warnings about a specific YAML file that has containers, and the chart is under your governance, you can provide proper formatting and linting for the chart template to fix parsing errors. For charts provided by a third party, file an issue with that provider.