Deploying apps to clusters with Continuous Delivery and Satellite Config

Deploy Kubernetes resources, like deployments, from your GitHub or GitLab repository to multiple clusters with IBM Cloud® Continuous Delivery and Satellite Config.

Objectives

In this tutorial, you learn how to create an open toolchain by using Continuous Delivery to deploy your app to multiple clusters. You also learn how toolchains are implemented in the Continuous Delivery service and how to deploy a simple web app by using a Continuous Delivery-only toolchain template.

With Satellite Config, you create a configuration that specifies which Kubernetes resources you want to deploy to a cluster group. Then, set up a Continuous Delivery pipeline to deploy these resources across a group of clusters whenever a change is made to the configuration.

The toolchain that is used in this tutorial implements standard DevOps practices around continuous delivery capabilities by managing your deployments in Satellite locations. After you create clusters and associate them with a Satellite cluster group, you can create a toolchain to change your deployment source code and push the change to the GitHub repo. When you push changes to your repo, the Tekton-based delivery pipeline automatically deploys the code to your clusters.

Audience

This tutorial is for administrators who are using Continuous Delivery toolchains and Satellite Config to deploy resources for the first time.

Prerequisites

Before you start this tutorial, make sure that you have the following resources in place.

An IBM Cloud account. Depending on your IBM Cloud account type, access to certain resources might be limited. Depending on your account plan limits, certain capabilities that are required by some deployment strategies might not be available. For more information about IBM Cloud accounts, see Setting up your IBM Cloud account and Upgrading your account.
A Satellite cluster or an Red Hat® OpenShift® cluster on IBM Cloud that is registered with your Satellite location.

If you don't have a Satellite cluster, you can register a Red Hat OpenShift cluster with Satellite.

A Satellite cluster group that contains the cluster that is required by the toolchain. The toolchain in this tutorial supports a Satellite cluster group that contains only Red Hat OpenShift clusters.
Image Pull Secrets. Make sure that you configure the image pull secrets that are required to deploy application images in your cluster namespace. For more information, see understanding how to authorize your cluster to pull images from a private registry.
A Satellite location for deploying the resources.
An instance of the Continuous Delivery service.

Getting started

Start to create a toolchain in IBM Cloud.

Log in to IBM Cloud Toolchains with your IBM Cloud credentials.
Select the Resource Group and Location for your toolchain.
Click Create toolchain.
On the Create a Toolchain page, select Satellite under Filters to display templates that are applicable for Satellite.
Select the Deploy Kubernetes resources to multiple clusters template.
Read through the information to understand how toolchains work and then click Start.

Defining toolchain settings

Define the name, region, and resource group for the toolchain.

Provide the name for the toolchain.
Select the region where you want the toolchain to be created.
Select a resource group where you want the toolchain to be created.
Click Continue.

Defining your source repository

Specify details of the source repository you want this toolchain to listen to. You can specify this info by using either standard configuration options or advanced configuration options.

Select your source provider. Depending on the source provider you choose, options specific to that source provider are displayed. For example, you can select Github Enterprise Whitewater as the source provider.
Define the source repository.
- To use a new repository for this toolchain, click Create new source repository and name the new repository.
- To use an existing repository for this toolchain, click Use existing source repository and provide the repository URL. Select the Source Provider and enter the URL of your repo, for example: https://github.com/my-org/my-repo.
Click Continue.

If you want to access more advanced source repository settings such as using a custom server and changing the cloning behavior, select Switch to advanced configuration.

Setting up your delivery pipeline

Name the delivery pipeline for deploying your applications to multiple clusters in your Satellite cluster group.

Enter the pipeline name, which is displayed in your toolchain.
Click Continue.

Providing an API key

Provide the IBM Cloud API key info that the toolchain can use to access your Satellite location.

If you have an existing API key or multiple existing API keys, follow these steps.

Select the secret provider or providers that you use. You can select one or more.
Click Continue.
Provide the necessary info for accessing your secret provider.

If you don't have an existing API key, you can ignore the options on this page and click Continue to proceed to the next page, where you can create an IBM Cloud API key and save it to a secret provider.

Setting up Satellite Config

Specify the settings that the Satellite Config tool can use when deploying resources.

Provide IBM Cloud API key. If you did not provide an existing IBM Cloud API key on the previous page, you can create a new IBM Cloud API key by clicking New.

You can save this key to a secret provider of your choice for reuse by selecting that option when you create the new key or by clicking the key icon.
Define the namespace that you want your resources to be deployed to. This must be an existing namespace.
Specify the branch to deploy the resource to; for example, v1.
Provide the path to deploy the resource to; for example, deployments.
Select the cluster group to receive the resources that you are deploying.
Provide the displayed name of the Satellite configuration.
Click Continue.

Reviewing the summary

Review the summary and confirm to create your toolchain.

To change any parameters you provided earlier, click Back.
To create the toolchain with the provided parameters, click Create toolchain.

Testing the toolchain

When the toolchain is created, the toolchain Overview page is displayed. On this page, you can view the repositories, pipelines, and any IBM Cloud tools that are associated with this toolchain.

Under Repositories is your source repository as well as additional repositories for your Tekton catalog and pipeline tasks. If you are comfortable with using Tekton, you can go to these Tekton repositories to make changes to your toolchain.

Under Delivery pipelines, you can see the status of your pipeline runs. You can click the name of the pipeline to see details about your pipeline and set From this pipeline overview, you can set the triggers for your pipeline. Triggers define when the pipeline starts.

You can start the delivery pipeline in either of the following ways.

Trigger the delivery pipeline manually by setting a manual trigger.
Push a commit to the deployment source repo as defined by a Git repository trigger. To set a Git repository trigger, see Deploying a new version of your app from a different branch.

To start a manual pipeline run, follow these steps.

On the Overview of your toolchain under Delivery pipelines, select the delivery pipeline to view its status.
Click Run pipeline.
Review the trigger properties to make sure that they match your configuration.
Click Run to run the toolchain and deploy your app.
Optional: Click the name of the run to see the status, logs, and details.
Optional: After the app is running, go to Satellite Configuration or run ibmcloud sat config command to see your Satellite Config resources.

Verifying that the sample app is running

After your toolchain is set up and the Delivery Pipeline successfully completes, run the following steps to check your app.

From the Clusters page, click the cluster that you used to deploy your app.
Click OpenShift web console.
In the Workloads > Pod section, filter by the project or the cluster namespace, and verify that the pods are running.
In the Networking > Routes section, filter by the project or the cluster namespace, and locate the app URL.
Verify that the app is running by visiting the app URL with your browser.
Optional: You can view your Satellite configuration in the console, or by running the ibmcloud sat config ls command.

Deploying a new version of your app from a different branch

If you have multiple branches in your repository representing multiple versions of the app, you can deploy a different branch to see a new version of your app running. Follow these steps to modify the toolchain to deploy a different branch of your source repository.

On the Overview of your toolchain, select the delivery pipeline to modify.
Click Triggers.
Click the action menu for the commit-push trigger.
Select Edit.
In the Branch field, select the branch you want to deploy. For example, v2.
In the deployment-branch line under Properties, click the Edit icon.
Modify the value of this property to the branch name you want to deploy. For example, v2.
Save the changes.
Check your app to see if it is running the new version by visiting the app URL with your browser.
Optional: View the new version of your configuration in the Satellite configurations console or by running running the ibmcloud sat config get --config CONFIG command.

Now you can deploy Kubernetes resources to multiple clusters with a single toolchain.